Imagix 4D User Guide


Queries

The Graph windows' querying facilities provide the fourth `dimension' in Imagix 4D; they enable you to create a graph that clearly and concisely shows you the information relevant to your current questions. As your questions change over time, you can rapidly change the graph.

There are two general activities involved in these queries - identifying symbols of interest and focusing a Graph window to show just the relevant information. You might use the identification operations simply to locate a specific symbol or set of symbols within the graph. Or you may want to perform a simple query to find which of the currently visible symbols meet particular criteria. Often though, you'll do an identification as the initial step in a multi-step query, and then you'll use the results of the identification as a basis for modifying the graph.

The identification operations include Select and Traverse. The Select functions identify symbols based on the characteristics of the symbol itself, while Traverse identifies new symbols based on their relationships to the currently selected symbols.

Focusing is done with the Filter and Group functions. Filtering enables you to simplify your views by hiding any of the symbols that exist in the database. Conversely, when your graph doesn't contain all of the information you're interested in, you can add hidden information back into the display.

With Grouping, unavailable for the Control Flow and UML Diagram views, you're able to condense information by collapsing sets of symbols into single group symbols. You see just those relationships of the collapsed symbols that are external to the group.

The Filter and Group functions can create simplified graphs from within the information that resides in your project's current database. You can achieve more far reaching and persistent results by managing which data sources are included and excluded from the project itself.

Because of their flexibility and extensiveness, the Imagix 4D query facilities can seem formidable while you are still learning the tool. To quickly performing common queries with a few mouse clicks, you can use the Analyze function, which is symbol specific, and available through the MOUSE [Right] popup menu.

Select Functions

The Select functions identify symbols that meet certain criteria, thereby controlling what is highlighted in a Graph window.

The Select functions range from simple operations which clear all the selections (None) or select everything in the graph (All), to very advanced search capabilities. Find enables you to identify symbols having specific attributes.

Certain functions identify symbols based on where they are in the currently visible graph. Roots identifies the top level of the graph hierarchy, while Leaves locates those symbols that are at the bottom of the hierarchy. Roots/Leaves finds symbols which are simultaneously roots and leaves - in other words, free-floating symbols.

At any point, you're able to store a list of currently selected symbols with the Save function. When you restore the list by using the Restore function, all symbols which are on the list and which are still visible become selected once again.

When symbols are selected, they are highlighted in yellow in the current Graph window. Only one Graph window is current at a time; selected symbols in the other Graph windows are indicated with white.

Find

The Find function highlights those symbols in the current Graph window that meet the criteria specified in the Find dialog. The contents of the Graph window do not change.

The Find function enables you to search for symbols based on the symbols' attributes. When Imagix 4D collects the symbol and relationship information, it captures a number of attributes about each symbol. These attributes range from fundamental descriptions of the symbol, such as name and type, to less essential characteristics, such as the symbol's file location and when that file was last changed.

With the Find function, you're able to search symbols based on these attributes. Find locates all the currently visible symbols whose attributes meet the criteria you specify. You can search on a large number of attributes, using glob style expansion (using *) for certain of the attributes, such as name.

You're also able to locate symbols that are containers for, or contained in, the symbol types you search on. For example, you could be in one of the file-level structure views, such as File Calls, and search for a function named foo. The file containing the definition for function foo would be highlighted in the graph, but only if it's already visible.

Traverse Functions

All of the relationships between symbols have a direction. For example, the sets relationship, which occurs when a function assigns a value to a variable, has a direction from the function to the variable. In the Graph windows, this direction is indicated with an arrowhead.

Visually tracing these relationships would be time consuming, and in crowded displays, quite difficult. The Traverse functions automate tracing.

The Step and Full functions follow the relationships into (Up) or out of (Down) selected symbols. The Step functions locate the adjacent symbols, while the Full functions recursively step up or down until root or leaf symbols are reached. The Unique functions follow relationships into or out of a single selected symbol. They also recursively trace relationships to adjacent symbols, but avoid any adjacent symbols that can also be reached from non-selected symbols.

The Intersection and Difference functions operate on two or more selected symbols. The Intersection function locates ancestors (Up) or descendants (Down) that the selected symbols have in common. The Difference function selects ancestors or descendants that exist for some, but not all, of the selected symbols. As one example of using these, you could select the entry functions for different subsystems and apply the Intersection Down operation to find variables that are shared by two subsystems.

These Traverse functions trace relationships of symbols that already appear in a Graph window. If you're interested in examining hierarchies of symbols not yet in the graph, use the Add function.

Grouping Functions

As you examine your software, a Graph window will often become too complex to be easily understood. Typically, you'll simplify it by completely removing particular symbols and their relationships from the window, using the Filter functions. However, at times you may prefer to condense a number of symbols together, while not removing information about them altogether. With the Group functions, you're able to accomplish this. The Group functions are unavailable while a Graph window is displaying a Control Flow or UML Diagram view.

When you group a set of symbols together, you create a new symbol that acts as an external representation of the set of individual symbols. In the current Graph window and related Graph Symbols tab in the Project Panel, you no longer see the grouped symbols individually. Nor do you see any of the intra-group relationships. Instead you see one symbol representing the entire group. You also see all the relationships that any of the grouped symbols have with any visible symbols outside the group. Thus, you're able to examine the external interface of the group.

Through the Group Definitions function, groups can be created and deleted. Individual group members can be added to or removed from groups. These groups apply to the whole project, and the Group Definitions dialog can be accessed through the Project menu on the main menubar. Typically however, you'll access the Group Definitions dialog through the Group menu in a Graph window's local menubar.

Automated definition of groups is available to simulate files and classes. The right click menu in the File Index and Class Index includes an item "Create group for members". This causes a group to be created that contains all of the function and variable members of a file or class. You can use these groups in Function Call views to understand and evaluate packaging and encapsulation approaches for your files and classes.

While the groups are defined on a project-wide basis, you control whether a group is active for each specific Graph window, through the Activate Groups function. Typically, you'll control this through the Activate Groups dialog, available through the Group menu in a specific Graph window's local menubar. Again however, the right click menu in the File Index and Class Index can be used, this time to activate any of the file and class member groups that were automatically defined previously.

All of the Select, Traverse and Filter functions continue to operate with groups. The operations are applied to the group as a whole. For example, if you do a Find operation and it identifies a symbol which is inside a group, that group itself becomes selected / highlighted.

There is a wide range of ways you might apply grouping. To examine your architecture at a high-level, you might create some long-term groups that partition your software according to subsystem or developer. You might use grouping as a way to do what if analysis, and create groups which simulate the impact of moving program elements from one file to another. Or if you are going to objectify some existing C software, you can use grouping to model encapsulation, to determine what symbols to combine in what classes.

Filter Functions

As you visualize the structure of your software, you may want to add some symbols that are currently hidden, or eliminate currently visible symbols that are extraneous. The Filter functions control which symbols appear in a Graph window.

You can use certain of the Filter functions to add hidden symbols, and their relationships, back into a Graph window. One approach is to manually select the symbols in other display windows, and then use the Add Selected function to add them to the graph. Add is an automated, dialog-based way to use database knowledge of the symbols' attributes and relationships to control what gets added. Restore All adds all the hidden symbols of whatever symbol types are viewable in the current view; unless applied carefully, this adds too much information.

The Isolate and Hide functions remove symbols from the graph. While Hide All completely clears the graph and Hide Library removes library functions from the graph, Isolate Selected and Hide Selected remove symbols based on what is currently selected. You control this by first using the Select and Traverse functions to select / highlight specific symbols. Then, once you have selected specific symbols that you want to remove or keep, you can use the Hide Selected and Isolate Selected functions.

If you add or remove too many symbols, you can reverse your action with the Undo function (LOCAL MENU Edit > Undo), or you can modify the graph further with other Filter functions.

Add

While you're examining your software structure in a Graph window, you may want to view certain symbols in addition to those currently displayed. The Add function enables you to add specified symbols to the graph, using information about the attributes and relationships of the symbols.

You can use a symbol's hierarchical relationship to the currently visible symbols to control whether it gets added to the graph. To do this, you first select symbols in the current graph. Then you can use any of the step/full up/down controls in the Add dialog to describe the relationship of the potential new symbols to the selected symbols.

The Add function also enables you to add symbols based on their attributes. When Imagix 4D collects the symbol and relationship information from your source code, it also captures a number of attributes about each symbol. These attributes range from fundamental descriptions of the symbol, such as name and type, to less essential characteristics, such as the symbol's file location and when that file was last changed.

With the Add function, you're able to filter symbols based on these attributes. Add locates all the symbols whose attributes meet the criteria you specify. You can use glob style expansion (using *) for certain of the attributes, such as name.

You're also able to add symbols that are containers for, or contained in, the symbol types you search on. For example, while you have a Graph window set to display just functions, you might search for a class named bar. The result of your search would be that all the functions that are client members of the class bar would be added to the graph. Conversely, you could be in a file-level view and search for a function named foo. The file containing function foo's definition would be added to the graph.

Analyze

Because of their flexibility and extensiveness, the query functions available in the Graph window can seem formidable while you are still learning Imagix 4D. For help in quickly performing common queries with a few mouse clicks, you can use the Analyze function.