This chapter provides an interactive sample session that demonstrates most of the C++ Browser's main functions. The session outlines common tasks you can perform with the browser, using example C++ application source to illustrate the use of each function. For complete reference information on the browser's user interface, see Chapter 7, “C++ Browser Reference.”
This chapter contains the following sections:
The C++ Browser comes with a demonstration directory, /usr/demos/WorkShop/bounce, which contains the complete source code for the C++ application bounce. To prepare for the session, you first need to create the fileset and static analysis database, then launch the browser from the Static Analyzer.
Prepare for the session by following these steps:
Open a shell window and start the WorkShop Static Analyzer in the
/usr/demos/WorkShop/bounce directory:% cd /usr/demos/WorkShop/bounce
% cvstatic
The Static Analyzer window opens.
Click the C++ toggle under the list of files.
Click the Move Files Parser button to move the list of files into the Parser Fileset list box.
Click OK.
Once the static analysis database is built, you can continue with the steps or close the Static Analyzer. If you have closed it, restart it as follows:
cvstatic -readonly |
The -readonly option suppresses the Static Analyzer's Build Window.
Select the “C++ Browser...” command from the Admin menu of the Static Analyzer window (see Figure 5-1). The Class View window opens, along with a chooser window, List of Classes, that contains the names of each C++ class included in the demo directory.
Stow the Static Analyzer Window as an iconusing the minimize button in the upper right of the window frame; you will be using it later (see Figure 6-1).
Position the Class View window in a convenient place on the screen.
You are now ready to begin the sample session.
The List of Classes chooser window that opened with the Class View contains the complete list of C++ classes included in the current fileset. Select Actor, the first class listed in the List of Classes window, by clicking on it with the left mouse button. Then click on the OK button. The List of Classes window closes, and Actor is now listed in the Current Class: text field. Information about the class appears in the two outline list views below it (see Figure 6-2). Actor is now the current class.
Now select the name in the Current Class: field by rapidly double-clicking on it using the left mouse button. You want to replace the class Actor with the class MainWindow as the current class. Type
Main |
into the Current Class: field, and then press the <space bar>. The Current Class: field completes the name of the class for you. Press the <Enter> key to set MainWindow as the current class. See Figure 6-3.
The lower two-thirds of the Class View window contains two side-by-side lists which contain information about the currently selected class in outline form:
The lefthand, or members, list provides a detailed view of the members of the current class.
The righthand, or related class list displays the relationships of other classes and of friend functions in your application's or library's class hierarchy to the current class.
By clicking on the outline icon to the left of a heading, you can collapse or expand the list under that category. The direction in which the outline icon points indicates if the heading is expanded or collapsed.
A downward-pointing outline icon indicates that the list is expanded, as shown in Figure 6-4.
In the member list, click on the PUBLIC heading's downward-pointing outline icon using the left mouse button. Class View hides all of the entries for that heading, and the icon toggles to become a right-pointing arrow (see Figure 6-5).
Click the PUBLIC heading's right-pointing icon again. Class View once again displays the entries for that heading, and the icon toggles to become a downward-pointing arrow.
To learn details about the structure of your C++ code, you make queries—predefined questions—about the current class's members and related classes. By making queries, you can gain a detailed view of a large, complicated class structure from the “viewpoint” of any class or member.
Queries search the static analysis database for specific information about classes and their members, including class hierarchy, class and member declarations and definitions, and the interactions among members and classes (for example, which members call which members, where a definition overrides another, where an instance is created or destroyed, and so on).
The C++ Browser answers queries by highlighting items in the member and related class lists that match the query. Optionally, you can display more detailed query results in the Static Analyzer window from which you launched the browser.
In the following sections, you will explore the queries available for data members, methods, and classes, plus several other display features of the Class View window.
In this section, you will examine a data member in the class MainWindow (see Figure 6-6).
To select the data member in the member list, do the following:
Use the member list's scroll bar to scroll until the outline heading PROTECTED is visible (if it is not already).
Left-click the corresponding outline icon, and then scroll until the heading DATA and the members under it are visible.
Click on the data member
Widget _workArea;
using the left mouse button. The member is highlighted with a raised bar.
Hold down the right mouse button anywhere in the member list. The Queries on Data Members pop-up menu appears, as shown in Figure 6-7.
Try each of these items and note the results. Methods in the member list and classes in the related class list are highlighted, and the list is automatically scrolled to display the highlighted items.
Also notice the use of the annotated scroll bars: they show where highlighted entries occur in the member and related class lists by displaying ticks in the highlight color at the proper location in the scroll bar. When the bottom or top of the scroll bar overlaps a given tick, the corresponding entry is visible in the list window.
The query type, target, and result are shown in the message area between the current class field and the outline lists.
Next, try double-clicking on the member you've selected (Widget _workArea). A Source View window opens, highlighting the location of the source for that member (see Figure 6-8). This works for all members in the member list.
Now, suppose you want to see more detailed information on your queries. Choose “What Accesses” from the Queries on Data Members pop-up menu (see Figure 6-9). Note that the display scrolls to show the results of your query. Then click on the Last Query button in the upper right corner of the Class View window.
Now open the Static Analyzer window that you had minimized earlier. The window contains precise information on where the member is accessed, as shown in Figure 6-10. Using the left mouse button, double-click anywhere in the first entry listed in the Static Analyzer window. A Source View window opens, displaying the highlighted access. Double-click anywhere in any other entry in the Static Analyzer window, and the Source View shifts to the corresponding access.
Try this for each of the other query items, and examine the results.
When you have finished, return to the browser Class View. Click on the Show in Static Analyzer toggle button (see Figure 6-11). The label to the right of the toggle should change to Yes. All subsequent queries you make display detailed results in the Static Analyzer window automatically.
In this section, you will examine a method (member function) in the class MainWindow. To select the method in the member list, follow these steps:
Use the member list's scrollbar to scroll until the outline heading PUBLIC : INSTANCE : VIRTUAL_METHODS is visible.
Using the left mouse button, click on the method
void initialize(void);
The method is highlighted with a raised bar.
Hold down the right mouse button anywhere in the member list to bring up the Queries on Methods pop-up menu (shown in Figure 6-12).
Try each of the items on the menu (except “Call Graph”), and note the results. Make sure to look at the detailed results that appear in the Static Analyzer window. Also try double-clicking on the method to get a view of its source.
When you are finished, go back and choose “All (method and data access)” from the What is Used submenu (see Figure 6-13).
Notice that several items in the heading DATA (under PROTECTED) are highlighted. Try clicking on the outline icon next to the heading. You'll see that when the list collapses, the outline icon is highlighted. This indicates that there are highlighted items within the collapsed heading. Note that the annotated scroll bar adjusts accordingly.
With MainWindow& MainWindow (char*); selected, try “What Uses” from the Queries on Methods pop-up menu. The Static Analyzer becomes active and displays an error message, as shown in Figure 6-14.
In this section, you'll examine the current class (MainWindow) and one of its ancestors. To get ready, scroll the related class list so that the heading BASE CLASSES is visible. You'll notice that beneath the heading there are class names, each of which is indented from the previous one (see Figure 6-15). The first of these is
<-This |
which represents the current class. Each class listed below it is an ancestor of the current class; parentage is denoted by indentation. Thus, in this case, UIComponent is the parent of MainWindow, and BasicComponent is the parent of UIComponent. Notice that child classes have outline icons associated with them, allowing you to collapse and expand the hierarchy. Try clicking on the current class outline icon to collapse the hierarchy, and then click again to expand it.
Select the current class (<-This) by clicking on it with the left mouse button, then hold down the right mouse button anywhere in the related class list to bring up the Queries on Current Class pop-up menu. The menu is divided into four sections, as shown in Figure 6-16.
Try each of the first three sections of the menu, and examine the results in both the Class View and the Static Analyzer windows. All the queries on the current class in the first three sections are also available from the Queries menu in the Class View menu bar.
The last section of the Queries on Current Class pop-up menu contains two items:
“Show Source” opens a Source View window on the source or header file containing the declaration of the selected class. The declaration is highlighted in the source. Note that if you minimized a Source View previously, this command updates the window. However, the window remains minimized.
“New Class View” opens a new Class View window with the selected class as the current class within it.
These two items are found on almost every pop-up Query menu in the related class list, so they won't be mentioned again. Feel free to try them out while you are running this session, but close each new window after trying it so you don't get lost.
Now select the class UIComponent by clicking on it with the left mouse button. Then hold down the right mouse button anywhere in the related class list to bring up the Queries on Base Class pop-up menu (see Figure 6-17).
Try each of the menu items, and examine the results in both the Class View and the Static Analyzer windows.
In this section, you'll examine a class derived from (that is, a descendant of) the current class (MainWindow, see Figure 6-18). To get ready, scroll the related class list so that the heading DERIVED CLASSES is visible. Notice that beneath the heading there are class names, each of which is indented from the previous one. Each class listed below it is a descendant of the current class; childhood is denoted by indentation. Thus, in this case, MenuWindow is the child of MainWindow (the current class is not listed under the heading, however); and BounceWindow is the child of MenuWindow. Note that the meaning of indentation is the opposite of what it was under the BASE CLASSES heading.
Notice that parent classes have outline icons associated with them, allowing you to collapse and expand the hierarchy. Try clicking on the MenuWindow outline icon to collapse the hierarchy, and then click again to expand it.
Now select the class MenuWindow by clicking on it with the left mouse button, then hold down the right mouse button anywhere in the related class list to bring up the Queries on Derived Class pop-up menu (see Figure 6-19).
Try finding the members of the current class that are overridden by choosing “What Is Overridden” from the menu, and examine the results in both the Class View and the Static Analyzer windows. (The other items won't find results in this example.)
In this section you'll examine a class that the current class uses. Scroll until the heading USES is visible in the related class list, and select the class Application using the left mouse button. Hold down the right mouse button anywhere in the related class list to bring up the Queries on Used pop-up menu.
Try finding the methods that call members of Application by selecting “By Calling Methods” from the “What Uses” submenu (see Figure 6-20). Be sure to check the results in the Static Analyzer window as well.
In this section you'll examine a class that uses the current class. For this example, we're going to change to a different current class, the class Application. Instead of going back to the current class text field, however, we're going to use a shortcut.
Double-click on any mention of Application in the related class list (the currently selected one is fine). Notice that the current class in the Class View window switches to Application, and that the member and related class lists are updated accordingly. You can change classes from the related class list at any time by double-clicking on the class you wish to make current.
Scroll until the heading USED BY is visible in the related class list, and select the class BouncingBall using the left mouse button. Hold down the right mouse button anywhere in the related class list to bring up the Queries on Users pop-up menu as shown in Figure 6-21.
This menu is very similar to the Queries on Used menu from the last section. Try finding the members of Application that BouncingBall calls by selecting “By Calling Methods” from the “What Is Used” submenu.
Remember that the results for the next query appear only in the Static Analyzer window.
To see the results of this query, you must have the Show in Static Analyzer toggle set, or you must click on the Last Query button after making the query. Now, double-click on BouncingBall to make it the new current class. Select the class AddBallCmd under the heading USED BY. Find the members of AddBallCmd that instantiate BouncingBall by selecting “What Instantiates” from the Queries on Users pop-up menu (see Figure 6-22).
Now let's return to the previously displayed current class, Application. There's an easy way to do this: go to the History menu in the Class View menu bar, and choose “Show Previous Class,” as shown in Figure 6-23. The current class reverts to whatever it was before the last change.
Now try the other item from the History menu, “Show History.” This item brings up the List of Classes Shown window (see Figure 6-24) that lists each of the previous current classes you have examined, in the order you examined them. To choose one, double click on the name in the list. For now, though, click on the Cancel button.
Next you'll examine the kinds of friend relations that Class View supports. For a selected friend function (of the current class Application), you'll find methods in the following choices:
current class that the friend function uses
current class that uses the friend class
friend class that uses the current class
Locate the heading FRIEND FUNCTIONS in the related class list, and select the function listed under it. Hold down the right mouse button in the related class list to bring up the Queries on Friend Function pop-up menu (see Figure 6-25). If you try “What It Uses,” you'll find that the function main() uses no members of the current class. However, double-clicking the function opens the related Source View.
Now locate the heading FRIENDS in the related class list, and select the class listed under it. Hold down the right mouse button in the related class list to bring up the Queries on Friend Class pop-up menu (see Figure 6-26). Try the query item “What Is Used.” Check the results in both the Class View and Static Analyzer Windows to see if it highlights all members of the current class that the selected friend class uses.
Finally, locate the heading FRIEND OF in the related class list, and select the class listed under it. Hold down the right mouse button in the related class list to bring up the Queries on Friend Of Class pop-up menu (see Figure 6-27).
Try the query item “What Uses.” Check the results in both the Class View and Static Analyzer Windows to see if it highlights all members of the current class that use the friend class.
Now that you're familiar with the basic functions available within the Class View window, let's look at the C++ Browser's other two main windows, the Class Graph window and the Call Graph window.
You can minimize (but don't exit) the Static Analyzer window; you won't be using it for the rest of the session. (If you exit the Static Analyzer, you also exit the Browser.)
The Class Graph window provides you with a graphical view of your fileset's class hierarchy. Open the Class Graph from the Views menu in the Class View window. The Class Graph displays the complete class hierarchy as found in the fileset, according to one of four available relationships, and highlights the current class. From there, you can prune the graph of classes until you are viewing only those classes that you are interested in.
The Class Graph has the same basic user interface as the other graph views found in the WorkShop suite of tools, which are explained in Appendix A, “Graphical Views in the CASEVision Environment,” in the CASEVision/WorkShop User's Guide. For functions specific to the C++ Browser Class Graph window, refer to “Class Graph and Call Graph Displays”.
Go to the Views menu in your Class View window and you'll see the selections shown in Figure 6-28.
Choose “Show Inheritance Graph.” The Class Graph window appears (it takes a little bit of time for the browser to access the static analysis database). You can resize the Class Graph by dragging the window frame with the left mouse button and by using the zoom in and zoom out buttons. This graph represents the complete inheritance structure of the example application. Later on, you'll see how to change the relationship being viewed from within the Class Graph window.
Once you are comfortable with the Class Graph window, scroll until you find the class Application. This is the current class in your Class View window, and is highlighted in the Class Graph window.
You may have noticed that the graph is large and somewhat complicated, and this is only a small example! Luckily, there's an easy way to prune the classes displayed so that only those related to the current class are displayed.
Go to the View menu in the Class Graph window, and select “Show All Related.” The graph changes so that only the current class (Application) and its direct relatives (ancestors UIComponent and BasicComponent) are visible.
Go back to the Class View for a moment, and change the current class to Application's parent, UIComponent. Notice that the Class Graph window updates to reflect the change. Note that the view is still restricted to those classes related to the current class: all ancestors and descendants.
Now choose “Show Butterfly” from the View menu. Now the graph is even more restricted, showing only immediate relations (in this case, parents and children).
Changing the current class from the Class View can be troublesome when you're using the Class Graph. Luckily, you can change the current class from inside the Class Graph by double-clicking on a class node with the left mouse button. Choose “Show All” from the View menu. Find the class ColorView in the Class Graph window, and double-click to make it the current class. Note that the Class View window and the butterfly view in the Class Graph window both update accordingly.
Now you'll change the kind of relationship you're going to view. First, choose “Show All” from the View menu, just to make the graph more exciting. Then use the option menu in the lower right corner of the Class Graph window to choose a new relationship. Note the change in color of the arcs for the differing relationships. Figure 6-29 shows the Interaction relationships.
Experiment with the different views and relationships available in the Class Graph window for as long as you like. When you're finished, close the Class Graph by choosing “Close” from the Admin menu.
Now you've seen the basic functions available within the Class Graph window. Your next exercise is to examine the Call Graph window.
The Call Graph window provides you with a graphical view of the methods and their calls in your classes. Open the Call Graph from the Views menu in the Class View window, or the Queries on Methods pop-up menu for a selected method of the current class. The Call Graph displays the calling structure of any method you choose to add from the Class View window.
The Call Graph, like the Class Graph window, has the same basic user interface as the other graph views found in the WorkShop suite of tools. This interface is explained in the appendix titled “Graphical Views in the CASEVision Environment” in the CASEVision/WorkShop User's Guide and are also covered in “Call Graph Window”. This section familiarizes you with the functions specific to the C++ Browser Call Graph window.
Go to the Views menu of your Class View window and select the first item, “Show Call Graph.” You'll probably want to resize the window (even though there's nothing in it yet) so that a comfortable area is visible.
Now go back to the Class View window for a moment, and make ControlPanel the current class. Find and select the method named:
ControlPanel& ControlPanel(Widget,char*,Clock); |
You may have to stretch out the Class View window and slide the sash (central divider) to see the whole name.
Once you've selected it, choose “Call Graph” from the Queries on Methods pop-up menu. Choose “Add” from the Call Graph submenu. The selected method and its calling structure are added to the Call Graph window as shown in Figure 6-30.
 | Note: If a Call Graph window is closed, you can open it by choosing “Call Graph”: “Add” from the Queries on Methods pop-up menu. This provides a method of the current class that is selected in the member list. |
The Call Graphnodes do not show argument lists, by default. Select a node of the calling structure. Look at the “Show Arg List” toggle from the Admin menu (see Figure 6-31). Turn it on by releasing the left mouse button directly over the toggle. Notice that each method in the Call Graph now shows its argument list. The node that you clicked matches the Node Selected information in the message area over the display.
Go back to the Class View. Find and select the method named:
const Widget baseWidget(void); |
Select “Replace” from the Call Graph submenu of the Queries on Methods pop-up menu. Note that the Call Graph is cleared, then the newly selected method is added to the Call Graph. The graph shows where the method is currently defined. Here BasicComponent provides the current definition of baseWidget.
Add some other methods to the Call Graph. To replace part of the display, use “Remove” and “Add” from the Call Graph submenu of the “Queries on Methods” pop-up menu, with selected individual methods in the member list.
The Browser generates reference page templates from your classes so that all you have to do is fill in the descriptions and provide comments. To create reference pages for classes in the fileset, follow these steps:
Select “Generate Man Pages” from the Class View Admin menu. The Generate Man Pages window opens, as shown in Figure 6-32.
Output files go in the directory shown in the Man Page Directory field. If you would like to specify a different output directory (an existing directory, where you have write permission), click Set Directory. The Select Man Page Directory dialog box lets you specify your choice. Click OK or Cancel to close the window.
Select classes from the class list. Use Select All to select every class in the source directory. To select no classes, click Unselect All. When you are satisfied with the classes selected in the class list, go on to the next step.
Click Generate. Wait for a few seconds while your files are generated.
To view the output files, Click View. A winout window opens as shown in Figure 6-33. You can edit the files using any text editor, such as vi.
