My Tricks for Using Understand

As an Understand engineer, I use Understand not just for static analysis, but also as my primary IDE. So, one of the most frequent things I do with Understand is navigating between files. Here are a few tricks.

One frequent task is switching between a header file and the corresponding code file. It turns out that there’s a built-in keyboard shortcut for this: “Ctrl+’(apostrophe)”. The shortcut toggles between files that have the same base name but different extensions. So, for instance, when I’m adding a parameter to a function in GraphWindow.cpp, I can use the shortcut to quickly switch to the header file and add it in GraphWindow.h as well.

GraphWindow, it turns out, also has a QT Designer file: GraphWindow.ui. When there is more than one possible companion file, then clicking the apostrophe multiple times toggles between the possible ones:

When I’m not paying enough attention, then sometimes I accidentally land on the ui file. Keyboard shortcuts to the rescue again! On Mac, “Cmd+W” closes a document window (on Windows, it “Ctrl+F4”).

But, sadly, closing a window activates the next window in the tab bar. Since I don’t usually have GraphWindow.ui open, chances are I landed on the last document window in my tab bar instead of back in GraphWindow.cpp or GraphWindow.h. This is where the option “Use ‘Most Recently Used’ order for next tab activation when documents close” is a lifesaver. Under Preferences (Tools->Options on Windows) User Interface, checking this box will use the most recently used order instead of the tab bar order for activating windows. It lets me land on the wrong file occasionally, and then “Cmd+W” right back to the file I was just in.

The key bindings for closing document windows and editing companion files are also editable from Preferences (Tools->Options on Windows) Key Bindings section.

Another helpful way to navigate is “Browsing.” In “Browse Mode,” everything in the editor is treated as a link, and clinking the links takes you to the definition. Browse mode is activated when holding down Ctrl. So, from the header file GraphWindow.h, if I want to jump in the cpp file specifically to a given function, I could Ctrl+click to go to the definition.

But, to be honest, I never use “Browse Mode” that way because of my favorite dock window, the Previewer. I might be slightly biased since I wrote the Previewer, but it’s one of only 4 dock windows that I always have open. The other three are the Information Browser, the Window Selector, and the Project Browser.

The 4 windows I always have open

When the Previewer window’s “Prefer” checkbox is checked, it intercepts most events that would otherwise open in a full editor. So, when I ctrl+click on functions, I see the definition in the Previewer. I use Ctrl+Click to reference code, rather than to edit it. For example, while I’m writing code in GraphWindow.cpp, I might need to remember the name of a member function for an Entity object, so I ctrl+click on “Entity” to pull up the class definition and find the function I need.

Suppose I really did need that ctrl+click to open an editor instead of just the Previewer? Double-clicking in the Previewer opens the same location in a full editor, allowing me to edit.

The Previewer helps me reduce the number of open editors I have, but they still stack up. I had an embarrassing 124 open at last count. That’s too many to navigate using the tab bar. So, that’s why the Selector (View->Window Selector) is one of my four always-open dock windows. The selector lets me quickly scroll between editors.

Why you might ask, do I bother to have the Project Browser open then? It doesn’t seem to add much to the Selector which tends to contain all the files I regularly want to edit. For me, the Project Browser is actually how I update the Previewer. If I don’t have a fast way to Ctrl+Click to the document I want to reference, I find it in the project browser and single click. When the “Sync” check box is checked, selecting a file entity updates the Previewer even when an editor wouldn’t normally open.

The final dock window I always have open is the Information Browser. As an example of how this works for file navigation, suppose I’m refactoring a function. I want to remove the final optional parameter that I think isn’t necessary. So, first I need to check all the calls to see if any of them provide a value for that optional parameter. Clicking through each reference shows the call in the Previewer. If the call provides that final parameter, I double-click the previewer to open it an editor and modify it. If it doesn’t, I can move to the next call without having the overhead of opening an editor.

This is only one style of navigating files in Understand. In fact, discussing it with other Understand engineers, none of us had the same style. One of the wonderful things about Understand is that there are lots of options available so you can customize the tool to fit your style.

Cover Photo by Cleyton Ewerton on Unsplash