5 C++ Class Browser

This chapter provides an overview of the C++ Class Browser's features and capabilities. For more detailed information on how to use this tool, choose Help: On C++ Class Browser. You can print Help topics using the HyperHelp Viewer.

The C++ Class Browser allows you to analyze the class hierarchy for a C++ program, and to browse the source code using the FUSE Editor, Emacs, or vi. The C++ Class Browser provides a Member Information pane for displaying more detailed information about members. Figure Figure 5-1 shows the C++ Class Browser main window.

Figure 5-1: C++ Class Browser Main Window

Key elements are the major window panes running from the top to the bottom of the window:

Configuration area: Displays basic information such as the current project and data directory.
Graph display area: Displays a graphical representation of the class structure and hierarchy of the C++ program. You can reduce the size of the viewport using Zoom menu items on the Graph menu. (See the online Help for more information on creating and interpreting the graph.)
Member Information pane: When you click on a class in the graph, its members are displayed here. The Member menu (or pop-up menu) lets you edit the source or set a breakpoint for a selected member.
Member filter buttons: Directly filter or provide access to additional filters for the list in the Member Information pane.
Information area: Displays information messages and Quick Help on menu items when you press and hold MB1 on the item. Displays access control and inheritance information for members when you drag MB1 over arcs.

5.1 Summary of Features

The C++ Class Browser lets you do the following:

View and analyze the class hierarchy for a C++ program

Display classes and derivations graphically
- Operate on the graph to isolate areas of interest or add and remove classes
- View the inheritance path for a member

Magnify a selected area of the graph or pan the graph

Locate classes using a Class List dialog box that accepts regular expressions for filtering

List detailed information about each class and member

Filter members based on function versus data, regular expression, access specifier, and other characteristics

Provide integration with the editors (to display or edit source code for classes and members), Debugger (to set breakpoints), Cross-Referencer, and Call Graph Browser

5.2 When to Use the Class Browser

The C++ Class Browser provides a graphical view of the C++ class hierarchy in a program. It also provides information about individual classes and members. Use the C++ Class Browser when you need to:

Become familiar with the structure of a C++ program.

Work on a program error.

Isolate possible causes of a performance problem.

Determine if the class hierarchy has been correctly defined.

Determine if individual class members have been correctly specified.

5.3 Requirements for Using the C++ Class Browser

The C++ Class Browser provides a graphical view of the class relationships in your application, including system classes. The C++ Class Browser develops the class graph based on information in a static analysis database. The Database Manager (see Chapter 11) creates and maintains the static analysis database using static analysis data files typically generated using features in the Builder. See Section Section 4.8 and the online Help topic Generating Static Analysis Data as Part of the Build for information on creating a static analysis database.

Before using the C++ Class Browser, make sure that:

All the files are available.

All disks containing source and intermediate files are mounted and available.

You have configured the browser tools using the Project Manager dialog box (Browser Tools Settings Category). Note that, because of the existence of default settings, this is not an absolute requirement. However, you will likely want to edit the defaults to customize the static analysis database generation and to make sure the compiler macros are consistent with your environment.
See Chapters Chapter 9 and Chapter 11 for more information on configuring a project and the browser tools.

You used the Builder (or some other build mechanism) to generate static analysis data during a build of your target application.

5.4 Accessing the C++ Class Browser

The C++ Class Browser is available only if you have a license for DEC FUSE Support for C++. If you have this optional license, the C++ Class Browser appears on your Tools menu.

5.5 Starting the C++ Class Browser

You can start the C++ Class Browser in several ways:

Use the command line.

If you have CDE installed, use the C++ Class Browser icon.

Use the FUSE Control Panel once FUSE is running.

Use the Tools menu from most FUSE tools.

5.5.1 Use the Command Line

You can start the C++ Class Browser from the command line using the following command:

% fuseclass [Xt-Options]

See Appendix Appendix D and the specific reference pages for the command syntax and options.

If the Control Panel is not running, it starts automatically as a minimized icon. If FUSE is already running, the C++ Class Browser is placed in the current project. Whenever you start a browser tool, you minimally need a working directory specified for the project. The C++ Class Browser inherits its working directory from the project.

Until you have a static analysis database, the C++ Class Browser cannot show any data. You can specify a data directory to contain the static analysis database and associated files. You also should check the default properties in the Project Manager dialog box (Browser Tools Settings Category) before you generate static analysis data from your source files. See the online Help topic Generating Static Analysis Data as Part of the Build for details on creating a static analysis database.

5.5.2 Use the C++ Class Browser Icon from CDE

When you have CDE installed, FUSE provides a FUSE application group icon and icons for the individual tools that make up the FUSE environment.

To invoke the C++ Class Browser:

Double click on the Application Manager icon in the CDE Front Panel to display the application group icons.

Double click on the FUSE application group icon to display the icons in the FUSE application group.

Double click on the C++ Class Browser icon to start the tool.

5.5.3 Use the FUSE Control Panel

To start the C++ Class Browser from the FUSE Control Panel, select C++ Class Browser from the Tools menu in the Control Panel

FUSE first lists the tool under the current project in the Control Panel display area. Then, the tool main window appears.

5.5.4 Use the Tools Menu from Most Tools

Most FUSE tools have a Tools menu. To start the C++ Class Browser, select the tool from the Tools menu.

5.6 Updating the Class Graph

If the underlying static analysis data files change, most likely as a result of a new build, you can update the data in the Class Browser by choosing Database: Update.

When you modify the source code for the application currently displayed in the C++ Class Browser, you can update the graph only after regenerating new static analysis data files, typically using features in the Builder.

For example, suppose you add a Reptile class to the animal_sayings example program while viewing the class graph for that program. You can update the class graph for animal_sayings to show the new Reptile class only by rebuilding the application in the Builder with the Generate Static Analysis Data button toggled on (or using some other build mechanism that generates static analysis data). You can then choose Update from the Database menu.

5.7 Adding and Removing Classes from the Graph

The C++ Class Browser allows you to build up your graph by adding classes and following relationships across the hierarchy. Conversely, you can choose to reduce the complexity of a class graph by filtering out certain classes based on their names or relationships to other classes.

You can show the entire class hierarchy for your application by choosing either Graph: Show User Classes or Graph: Show System Classes. You can clear the graph at any time by choosing Graph: Clear.

5.7.1 Adding a Class

There are two ways to add a single named class that already exists:

Enter the exact name in the Class field below the graph and enter Return.

Use the Class List dialog box (click on the Browse... button) by double clicking on a name in the list.

There are three ways to add a base or derived class:

For a selected class, choose Class: Show Base Classes or Show All Base Classes; choose Class: Show Derived Classes or Show All Derived Classes. The Show version of the menu item only adds the immediately adjacent classes whereas Show All adds the extended hierarchy of related classes.

Use the pop-up menu by clicking MB3 on the selected class.

Select a class from the Base Classes or Derived Classes menu lists to add and highlight the classes. These are tear-away menus to make it easier to navigate the class hierarchy by following base and derived class relationships. Click on a tear-away menu button and then double click on the line at the top of the menu.

You might decide to build up your graph based on a single class. For example, to graph the complete single branch of the Mammal class for the animal_sayings example program (see Section Section 2.8) :

Step	Action
1	Enter the `Mammal` class name in the Class text field and then press Return. This graphs the `Mammal` class and its immediate base and derived classes.
2	Choose Class: Show All Base Classes (also available from the MB3 pop-up menu when invoked directly over the class node).
3	Choose Class: Show All Derived Classes. You now have a complete branch of the `Mammal` class. Zoom out to view the text in the nodes.

You can choose Class: Focus to graph only the immediate base and derived classes. This option is also available from the MB3 pop-up menu when invoked directly over the class node.

5.7.2 Removing a Class

There are two ways to remove a single selected class:

Choose Class: Remove.

Use the pop-up menu by clicking MB3 on the class.

There are two ways to remove all base or derived class:

Choose Class: Remove All Base or All Derived Classes.

Use the pop-up menu by clicking MB3 on the class whose base or derived classes you want to remove.

There are two ways to remove all but the selected class and its immediate base and derived classes:

Select a class and then choose Class: Focus.

Use the pop-up menu by clicking MB3 on the class you want to focus on.

5.7.3 Finding a Class by Name

If you know the name of the class, you can enter it directly in the Class field to add and highlight it in the graph. You can use the Class List dialog box to filter a class hierarchy by regular expression. To access the Class List dialog box, choose Class: Browse Class List... or click on the Browse... button in the main window.

Depending on how you named classes in your C++ application, you could filter its class graph to include or exclude the classes for a single component. For example, if you are using the Rogue Wave classes, you can graph them by searching for names that start with RW.

To filter the class graph for the animal_sayings example program to show only those classes having a name that contains a P followed by either an e or an o:

Step	Action
1	Click on the Browse... button to display the Class List dialog box.
2	Enter `P[eo]` in the Text Filter field. The Filter field accepts regular expressions as described in the `egrep(1)` reference page.
3	Select one or more of the classes that are in the list.
4	Click on the Graph button.

5.8 Understanding the Class Graph

In the class graph, classes are represented by rectangular nodes. If you are using DEC C++, instantiations of templates are represented as rectangular nodes as well. Templates themselves are represented as oval nodes.

The class graph in Figure Figure 5-2 is for the example program animal_sayings. (See Section Section 2.8 for instructions on obtaining copies of the example programs.)

Figure 5-2: C++ Class Browser Class Graph

5.8.1 Colors in the Class Graph

The colors (or shadings on a monochrome display) used in the class graph are listed in Table Table 5-1.

Table 5-1: Colors Used in the C++ Class Graph

Color Meaning

Yellow

Currently selected class in the graph. In the case of a selected abstract class, the yellow fill color has white pinstripes.

Blue border

If a derived class inherits a selected member function without change, it has a blue border.

Red border

This class defines the selected member function.

Color	Meaning
Yellow	Currently selected class in the graph. In the case of a selected abstract class, the yellow fill color has white pinstripes.
Blue border	If a derived class inherits a selected member function without change, it has a blue border.
Red border	This class defines the selected member function.

5.8.2 Lines in the Class Graph

The weight and pattern of the lines connecting nodes represent the type of link, as shown in Table Table 5-2.

Table 5-2: Meaning of Lines in the Class Graph

Line Pattern/Weight Represents

Thin, solid line

Public, private, or protected subclass links

Thin, solid line with bar

Public, private, or protected virtual subclass links; a virtual inheritance is represented by the bar on the line near the arrowhead.

Dashed line

Friend links between classes

Thick, solid line

Template-to-instantiations links

Line Pattern/Weight	Represents
Thin, solid line	Public, private, or protected subclass links
Thin, solid line with bar	Public, private, or protected virtual subclass links; a virtual inheritance is represented by the bar on the line near the arrowhead.
Dashed line	Friend links between classes
Thick, solid line	Template-to-instantiations links

A virtual inheritance is represented by a tick mark on the line near the arrowhead.

5.9 Navigating the Class Graph

The C++ Class Browser provides a variety of methods for navigating a class graph:

Use the scroll bars to pan the class graph.
When the pointer is inside the display area, you can press and hold MB2 to grab the graph and move it around (this is similar to moving the slider in the scroll bar). Use Shift+MB2 to move the graph in increments (this is similar to clicking inside the scroll bar).

Change the size of the viewport.
You can choose Graph: Zoom In (accelerator Shift+MB1) and Graph: Zoom Out (accelerator Shift+MB3) to change the viewport size. When the pointer is in the display area, you can press Shift+MB1 and drag the pointer to select a region to be magnified. Choose Graph: Zoom to Text to size the class text to be readable.

Use any of the following methods to select a class:
- Click on the node representing the class in the class graph.
  Enter the name of the class in the Class field and press Return.
- Click on the class name in either the Base Classes or Derived Classes Menus.
- Click on the Browse button (or choose Class: Browse Class List...) to display the Class List dialog box and double click on a class name.

5.10 Displaying Data for Classes and Members

When you select a class, the C++ Class Browser shows the Base Classes and Derived Classes in the Menu lists below the display area. The Member Information pane displays detailed information about members, including member names, access control (public, private, protected), data type for data members, and return values and parameters for function members. Figure Figure 5-3 shows the information listed in the Member Information pane for the Mammal class in the animal_sayings program.

Figure 5-3: Member Information Pane

When you click on a member in the Member Information pane, the class graph displays the inheritance path and redefinitions for a member by highlighting the related graph components. See Table Table 5-1 for the meanings associated with the colors used for highlighting.

When you press and drag MB1 over arcs inside the class graph, the information area at the bottom of the C++ Class Browser window shows the inheritance relationship.

5.11 Filtering the Members List

The Class Browser provides basic filtering directly from the main window and more detailed filtering from the Member Filter dialog box. By default, members appear grouped by access control and then in order of declaration by class. Following that are members that are inherited by base classes, grouped by class with the most immediate base class listed first. In the case of multiple inheritance, the list is depth first (one complete hierarchy followed by the next).

5.11.1 Filtering from the Main Window

You can choose to have function members and/or data members listed. With the data toggle on, the Member Information pane includes all non-function members, that is, data, nested classes, structure definitions, and enums.

The signature toggle causes member information to include return values and parameters for function members.

5.11.2 Detailed Filtering by Name and Characteristic

Detailed filtering is available when you click on the Member Selection button. You can also use the toggles in the dialog box to further refine the Members List. If you enter a regular expression in the Filter field, only members having a name that matches the regular expression are listed. See the egrep(1) reference page for more information about specifying regular expressions.

For example, you set up a filter operation as follows:

Toggle on the Functions toggle in the main window.

Toggle off the Data, Alphabetic, and Signature toggles.

Click on the Member Selection button to display the Member Selection dialog box.

Click on the Clear All button and then the operator and inherited toggles in the Member Selection dialog box.

Enter the regular expression "Li" in the Text Filter field.

The Class Browser displays all members that are functions, either operators or inherited, and contain the letters "Li." Figure Figure 5-4 shows the results of such a filtering operation.

Figure 5-4: Filtering the Members List

5.12 Changing the Layout of a Class Graph

The C++ Class Browser allows you to modify the layout of the graph to improve its legibility or its suitability for printing (see the online Help topic Adjusting the Size of a Graph for Printing for more information). To modify the layout of the class graph, use the Graph Layout dialog box. This dialog box allows you to specify:

Layout Direction: The orientation of the graph (whether horizontal, vertical, or a best fit for the current size of the display area)

Arc Method: How connecting lines should be drawn (whether directed through nodes or routed around them)

Node Style: The size of nodes (whether fixed or variable, based on the size of their labels)

To access the Graph Layout dialog box, choose Layout... from the Graph menu. After making changes to the settings, click on Apply to see the results in the display area.

5.13 Editing and Debugging Source Code

The C++ Class Browser allows you to start the default editor and load the source code for the currently selected class or member. Typically the source code for the selected class is annotated with a colored icon next to the appropriate source line.

To start the editor, double click on a class in the graph. The current editor reads in the appropriate file that contains the source code into its buffer. You can also use the Class List dialog box (click on the Browse... button in the main window) to select one or more classes and read them into the editor using the Edit button.

When you click MB3 on a selected member in the Members Information pane, you can choose to invoke the editor at the definition or declaration associated with that member. In a similar way, you can set a debugging breakpoint. The Debugger must be running and set to the same executable as the Class Browser.

5.14 Starting the C++ Class Browser from an Editor

When editing a file with the FUSE Editor or Emacs, you can select a class name in the editor's buffer and invoke the C++ Class Browser to display that class, highlighted in the class graph, with member information.

To invoke the C++ Class Browser from the FUSE Editor:

Step	Action
1	Select the name of the class you want to view by placing the cursor on the name or by highlighting it.
2	Choose Show Class from the Utilities menu.

If the C++ Class Browser is already running and is configured, FUSE searches the currently loaded database and then highlights the class in the C++ Class Browser graph. If the Class Browser is not already running and configured, FUSE starts the C++ Class Browser.To start the C++ Class Browser from Emacs, place the cursor on the class name and enterC-c C-c.