This tutorial shows how to customize your graphs. From changing edge and node styles to adding metric color scaling, it's easy to make Understand's graphs completely yours. While we provide a full API that you can access to write all of your own custom graphs, sometimes you just don't have the time to learn another API and that's where we come in. We have a dedicated team ready to give you the graphs that you and your team need in a timely manner. We will work with you to get them just right so that you can focus on the objective of your project. Learn more or email [email protected]

TABLE OF CONTENTS

• Show the Legend
• Right Click Legend Entries to modify
• Add Custom Node Styles
• Add Custom Edge Styles
• Adding a metric color scale to your graph
• Saving, importing, and exporting styles

I’ll use a dependency graph for the FastGrep sample project Directory Structure architecture. I'm going to use shades of blue to communicate the file size, change the edge colors and change Icons for the folders. Then I'm going to save it as a theme so other graphs can inherit these changes as well.

Show the Legend

The first step to customizing the graph is to show the legend. If a graph has a legend, there will be an icon in the toolbar to toggle the legend’s visibility:

The legend is a floating window that can be dragged around the screen. If the legend shows a hamburger menu, like this one does, then the graph styles can be customized:

Right Click Legend Entries to modify

Suppose I want a different color for my bidirectional edges. I can right-click on the Bidirectional entry to see available options:

Colors have a few pre-built options and a color selection option. I’ll change the color to orange. The graph will automatically update with the new setting:

For bidirectional edges, I can configure both the arrow head and the arrow tail. Other edges will only have the arrow head option. I can also change the line style to be dotted or dashed.

Nodes have options too. Let’s change expandable nodes to be folders instead:

The final option in the menus is disable. Styles that come built-in with Understand are not deleted. Instead they can be disabled, and re-enabled from the hamburger menu in the legend.

Add Custom Node Styles

Custom node styles are created with “Add Node Style” in the Legend hamburger menu. That opens this dialog:

The first field gives the rule for when the style applies. Custom styles apply to entity nodes whose kind matches the typed in value. The drop down icon provides some pre-built filters:

It’s also possible to type in custom kind. See the Perl or Python API for available kind strings. I’ll use a custom kind string to style header files differently:

The node style will appear in the legend immediately, but it initially inherits all values from default. So, there won’t be a visible change in the graph.

I’ll use the right click menu to set the shape back to box 3D for header files:

Notice that a header file is both expandable and a header file. The last style listed takes precedence, so in this case the shape is box3D instead of folder.

 Add Custom Edge Styles

Adding an edge style is similar. Edge styles can only be added to graphs with references as edges. So, they aren’t applicable in architecture graphs or control flow graphs. The rule for the style is based on reference kinds:

I’ll add Call, Include, and Use rules:

Note that because these styles occur after the Bidirectional style, their color takes precedence. Also, since these edges are a single direction, only the Arrow Head option is available and not the Arrow Tail.

Custom edge styles stack with each other. So, If I change the color for my styles, I end up with this graph:

So, I can immediately tell that all the files that include regexp.h also use something in regexp.h except for timer.c.

Adding a metric color scale to your graph

Suppose I want to shade my nodes by a metric. The first step is to add a metric color scale, using the Legend hamburger menu:

The dialog defaults to the cyclomatic metric. I want to see this for the files already visible in the graph, so I’ll pick CountLine.

The new scale appears immediately in the legend. Since I left automatic range checked, the numbers on the scale reflect the minimum and maximum values in my graph:

Note that metrics can apply to both entities and architectures. In this case, the maximum value of 2,673 is from the architecture fastgrep-changed which is visible in the graph.

Just like adding a new node or edge style, adding a metric scale doesn’t immediately impact the graph. Instead, it adds an automatic color option to node styles:

Note that the metric scale option isn’t available for the Default style. If a metric is not applicable, like Cyclomatic for a file, then the default value is used instead. Therefore, the default value cannot depend on a metric.

Since all my files are expandable nodes, I’ll use the scale for the fill color of my expandable nodes. I’m also going to edit my scale to use a fixed scale from 0 to 100 instead of automatically scaling based on graph contents. This makes the scale visible for smaller files:

Note that even though I set the scale on the Expandable Node style, it still applies to my header file nodes. That’s because my header file nodes are inheriting their color so there isn’t a conflict between the two styles.

Saving, importing, and exporting styles

You may have noticed that the screenshots of the legend show a * next to Legend. This indicates I have unsaved changes.

I can save changes to the theme, and all other graphs that use this same theme will have these changes. Note that themes are based on both name and graph content, so a dependency graph theme will have no impact on a Control Flow graph.

I’ll create a new theme with my changes.

The name determines what appears in the menu. The ID is used when importing themes to determine if it’s a new theme or should overwrite an existing theme. I’ll keep the default ID but change the name to “My Theme”.

There are no immediate changes in the graph because my new theme copied all the settings I already had set. But, from the hamburger menu, I can tell that I’m on “My Theme” instead of “Basic”:

Because it’s a custom theme, I now have the option to rename or remove it. I can also toggle back and forth between my two themes.

The export option allows sharing themes. Themes are exported as json files. I’ll save mine as “themedemo.json”. You can download it and import it using the Import Themes menu option. If you import a theme with the same ID as a theme you already have, you will get a warning:

Importing a theme will not change your currently selected theme, but if the imported theme is applicable to your current graph, you will see it in the list of available themes.