So you’ve got a shiny new link class that you’d like to use in your networks, but GunnShow doesn’t know about it! Here’s how to create a new GunnShow shape for your link so you can add it to your network drawings.

I’m creating a new shape for the gunns/core/GunnsBasicExternalSupply link to add to the new Thermal shape library, so I’ll use this as our example.

You can do all of this in Visio Standard. You don’t need Professional to make or change link shapes.

The first thing to do is create the shape data XML file for your link class. This file defines the config and input data that shows up as shape data in the GunnShow drawing, which allows you to configure each instance of the shape individually.

• See the Update Shape Data section in the GunnShow User’s Guide (JSC only) for details on the file syntax.

• Prior to GunnShow v17.2.1, all such files have to reside in the gunns/gunnshow/ShapeDataXml folder, even if your link class code resides outside of the gunns/ repo. Starting with v17.2.1, GunnShow can look for your shape data XML file where your link code lives:
  • Being able to keep your custom link’s shape data XML in the same location as your link code is more convenient and makes for a cleaner break between user-developed & core link classes.
  • To enable this, you must provide search paths in the GsExternalModelPaths field in your GunnShow user settings. Editing this field is covered in First-time User Setup.
  • Your shape’s ShapeSheet defines a relative path to the link’s .hh file: this is the Prop.ModelPath row’s Value field. GunnShow replaces the .hh file extension with .xml and searches for your shape data XML file with that relative path/filename.
  • The search order is as follows:
    • Relative to paths in your GsExternalModelPaths user settings, in order,
    • Relative to your gunns/ repo path, defined by your GsGenericModelPath user settings,
    • Finally, gunns/gunnshow/ShapeDataXml, defined by your GsGunnsLinkHome user settings. In here, it no longer searches relative paths, and instead only looks for the .xml file directly in the ShapeDataXml folder.
  • Following the above search order, GunnShow will use the first matching .xml file it finds.

• Normally the .xml syntax for a config or input term looks like this, inside the block or block as appropriate:
  

  
      <DataTerm Name="malfBlockageFlag">
        <TermType>const bool          malfBlockageFlag</TermType>
        <DefaultValue>false</DefaultValue>
        <Description>Description for malfBlockageFlag term.</Description>
      </DataTerm>
  

• If a or block needs to be empty because your link has no such terms, the xml syntax for that block should look like this:
  

  
    <ConfigData /> or <InputData />
  

For our example, the file I came up with is gunns/gunnshow/ShapeDataXml/GunnsBasicExternalSupply.xml. I just copied from GunnsFluidExternalSupply.xml and changed it to reflect the Basic link’s data.

New in v14.5, links whose node connections are assigned by Port Map objects have a special way of defining the shape data for primitive vector types. These links have a dynamic number of ports that are assigned to nodes by the Port Map objects. Because they’re dynamic, they often have a dynamic number of configuration data values that also need to be passed in, and the C++ std:vector is a handy way to do this.

This is enabled for a link shape by a special syntax in the shape data XML file. The DataTerm’s TermType field should be: vector class_attribute. Note that the class_attribute should be the actual class attribute name, not the constructor argument name like we normally use (i.e. in the example below, we need mPortLabels, not portLabels).

Here is an example from the new GunnsElectSelector link. It’s config data mPortLabels term is a std::vector of std::string:

    <DataTerm Name="portLabels">
      <TermType>vector std::string mPortLabels</TermType>
      <DefaultValue>0</DefaultValue>
      <Description>Description for portLabels term.</Description>

Although the std::string is technically not a primitive, it has a primitive-like assignment operator, i.e. std::string myString = “value”. This syntax also works for true primitive types like double, int, and bool.

For more info, see the link help pages for Port Mapped link types like GunnsThermalSource and GunnsElectSelector.

Next you need to determine which shape library (Visio stencil) your new shape is going to be in. GunnShow has built-in “core” shape libraries for Fluid, Electrical, and Thermal networks. These are the .vss files in gunns/gunnshow/Model_Libraries. We’d prefer that these libraries be reserved for links that reside in the GUNNS repo (gunns/core or gunns/aspects, etc). Usually, your new link class code should be in your user area, and not added to the GUNNS repo. The GUNNS repo should only contain generic links supported by the GUNNS core team.

• For clarity, use one of the core libraries if your link code is in the GUNNS repo, and use your own library if your code is outside of GUNNS.

• Note that although each aspect has its own core libary (Fluid, Electrical, Thermal), libraries do not actually have to be aspect-specific. You could have your own user library that has a mix of custom fluid & thermal links, etc.

Fire up Visio and open the shape stencil that you’ll be adding to, or create a new stencil. In the Shapes window, select More Shapes > Open Stencil for your already existing stencil or More Shapes > New Stencil (Metric) if you’re creating a new stencil. Actually US units vs. Metric doesn’t matter, but let’s all go with Metric anyway. If editing the default “core” shape libraries (Electrical, Thermal, Fluid), don’t open them from the GunnShow ribbon (Open Library drop-down in the Utilities section), because those open the read-only versions of the libraries in the GunnShow install. Instead, open them manually from the More Shapes > Open Stencil command and navigate to gunns/gunnshow/Model_Libraries in your repository.

Now open the stencil for editing by right-clicking on the stencil label and selecting Edit Stencil. A red asterisk should appear next to the stencil name — this means it can be edited. Here’s a picture of the ThermalSymbols stencil ready for editing:

Rather than build a whole new shape from scratch, it’s a lot easier to copy an existing shape and modify it. It’s easiest to copy an existing shape that looks similar to what your new shape should look like. In my example case, the core Fluid library has a Supply shape for fluid networks that I’ll copy from.

As before, open the stencil to copy from via More Shapes > Open Stencil. In my case the stencil is at gunns/gunnshow/Model_Libraries/FluidSymbols.vss.

You don’t need to open the copied-from stencil for editing.

Click on the shape you want to copy, and drag it up to your destination stencil. The destination stencil will automatically pop open and you can place the shape anywhere you want to in it. I like my shapes to be arranged alphabetically, and I know the eventual name of my new shape will be Basic External Supply, so I placed the Supply shape from the Fluid stencil into my Thermal stencil like so (you can move them around at any time):

The red asterisk in the stencil name has changed to a floppy disk symbol to indicate the stencil has been modified and needs to be saved.

You now have a new master shape in the stencil. You can double-click on the new shape in the stencil or right-click on it and select Rename Master to give it your new name. This can be any name and doesn’t have to match the link’s class name. Or you can keep the same name as what you copied from — there isn’t a name collision since it’s in a separate stencil. I’ve renamed mine to Basic External Supply:

Next we need to make graphical changes to how the shape looks, if needed. I’m keeping the same arrow shape I copied from, but I’m going to change its color to dark red. Right-click on the master shape in your stencil and select Edit Master > Edit Master Shape. This opens up a zoomed-in picture of your shape graphic. You can use the Visio zoom slider tool at the bottom right to zoom out a little. This picture shows the editing window resized to use less of my desktop, zoomed out to 318%, and the shape selected (blue outline):

Now this is very important: most link shapes are actually a group of shapes in Visio, and the ShapeSheet Data that GunnShow cares about is attached to the group itself. DO NOT ungroup the shape, or the GunnShow data will be lost!images/ Instead, select the group and right click on it and select Group > Open Group (not Ungroup!)

This opens up another window that can be used to edit individual graphics inside the group without breaking up the group itself. It looks just like the previous editing window, but has in the title bar. Now you can make whatever graphical changes you want to, including deleting or inserting new elements. I’m changing my shape to be a dark red color. Note that I’m making the graphical edits in the lower window. The previous overall shape window shows the graphical changes too, so don’t get confused between these two windows:

Each graphical element has a ShapeSheet that can be used to fine-tune graphical properties. Right-click on an element and select Show ShapeSheet to open up the ShapeSheet editing window. This window is distinguished from the others by a label in its title bar. It is useful to define the coordinates of line endpoints & such relative to the Height & Width of the overall group, so that each individual element scales properly when resizing the overall shape on a drawing. In the picture below, I’m editing one of the lines of the arrowhead and defining its Begin & End X & Y coordinates in its ShapeSheet window. Note how the line segment is identified by “Sheet.7” in the titlebar, but its coordinates are defined relative to the size of the overall group (“Sheet.5”).

When you’ve finished updating the graphics, close the window. Now you may need to delete, add, or move around the shape’s connection points. The connection points correspond to the link’s ports for attaching to nodes. In Visio, the connection points are little blue x’s that connector lines can attach to. To see where they are in your shape, unselect the shape in the original editing window to get rid of the blue selection border, and from the Visio Home toolbar, in the Tools section, select the blue X button (Connection Point). When you select Connection Point, the shape’s connection points show up in the editing window. You can move them around or add/delete them. Keep in mind, however, that these connection points are order-dependent. We’ll talk about this more when we get into the ShapeSheet data below.

Now it’s time to point GunnShow to your link class. This is done in the ShapeSheet for the master shape. In the same editing window, select the shape group, right-click on it and select Show ShapeSheet. This opens up the shape group’s ShapeSheet editing window. Note that this is the ShapeSheet for the whole shape group, as opposed to an individual graphical element’s ShapeSheet as discussed above. There are 2 sections we are interested in. If you don’t see these sections in the ShapeSheet then you are probably editing one of the graphical elements instead of the overall group, so go back and show the ShapeSheet for the whole group. Double-click on a cell to edit it and tab to exit the cell & keep the changes.

• Shape Data:
  • Change Prop.InstanceName Value to the default for your link (this can be anything you want)
  • Change Prop.ModelPath Value to the relative path/filename of your link’s header file. This should be relative to the gunns/ folder or whatever folder is included in your make path. This should be equal to the ClassHeaderFile value inside the tag in your new shape data .xml file.

• Connection Points:
  • These start numbering from 1 but correspond to link port numbers starting at 0, so Connection Point 1 is for link Port 0, etc. There should be one Connection Point for each link port. The X & Y values can be used to make sure you have the correct ports assigned to each point on the graphic. For example, most Fluid links have Port 1 (Connection Point 2) at the tip of the arrow.
  • Hint: define X & Y as functions of the Width & Height parameters so that they move properly when you resize the link in the drawing, as shown below.
  • Use this section to verify that you have the correct number of Connection Points and that they are properly placed. The X & Y formulae override the placement from the graphic editing window.

When you’re done with all graphic & ShapeSheet updates, close the shape’s editing window. A pop-up window will ask "Update ‘Basic External Supply’? Click Yes. This applies all updates to the master shape in your stencil:

Now test out your new shape by dragging it from the stencil onto your drawing. If all goes well, the shape should appear on the drawing and look as you intended, and it should have an instance name label beneath with the default name you gave in its ShapeSheet data.

Check a few more things:

• Change the instance name in the Shape Data window and verify the shape’s label changes to match.
• Use the Visio connector tool to check that connections can be made at the desired Connection Points.
• Resize the shape on the drawing and verify its graphic and Connection Points scale properly.
• Export the drawing and verify the link gets generated and configured properly in the network manager class.

Finally, save the changes to the stencil by clicking the floppy-disk icon, and turn off its editing mode by selecting Edit Stencil again. You should now see changes in your source control repository: the new shape data .xml file for your new link, and the modified .vss file for the shape library. That’s it, you’re done!