Queries

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 Sequence Diagram 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 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 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

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

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

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

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