Introduction to the C++ Visualization features
The C++ Visualization features of IBM® Rational® Systems Developer bring the modeling experience to C++ projects that use the Eclipse C/C++ Development Toolkit (CDT), the open source development environment. This makes agile modeling possible on live C++ projects by creating Unified Modeling Language 2.0 (UML 2) proxy elements for C++ source elements, which enables you to use them as UML elements. These proxy elements reside only on the diagram where they were created and require no underlying, physical UML model element.
When you create such an element, the visualization engine looks into only the code element that is selected and to its immediately related elements. Thus, it does not traverse the complete source code, unless you specify that action. This is where it differs from reverse-engineering tools. Another advantage of graphically represented (visualized) C++ elements is that they are always synchronized with the source code, which means that UML diagrams, like Class or Topic diagrams, always reflect changes in code as they happen.
This article describes how the C++ Visualization features can help during the day-to-day activities of programming and documenting code.
- Install Rational Systems Developer on your system. See Resources for a link to the trial download.
- Import the sample Eclipse CDT library project Download for this article into your Rational Systems Developer workspace.
Visualizing C++ elements on the Class diagram
Rational Systems Developer supports these elements:
- Visualization (graphic representation) of C++ class, struct, enum, and typedef as UML classifiers
- Namespace as a UML package
- Files and folders as UML artifacts
You can visually represent (visualize) these elements on a UML diagram by using either the pop-up menu or the drag-and-drop method.
Using the C++ element pop-up menu
The C++ Visualization features provide a Visualize context menu entry for C++ elements (see Figure 1), which allows you to visualize C++ elements to new or existing Class Diagram by following these steps:
- Activate the pop-up menu.
- Select Visualize > Add to New Diagram File > Class Diagram.
Figure 1. Visualize the pop-up menu
Figure 2 shows class
Book from the sample project visualized on a diagram. Visualized C++ elements on diagram are differentiated from UML classes by using C++ specific icon and stereotypes, which are shown in Table 1.
Figure 2. A C++ Class visualized on a Class diagram
Table 1. Icons and stereotypes for C++ elements
|Header file||<<header file>>|
Using the UML diagram pop-up menu
Another way to visualize existing C++ elements is by using a UML diagram's pop-up menu. (See Figure 3.)
Figure 3. Visualize Existing pop-up menu
For example, to visualize class
LibraryEntry from the sample project by using this option., follow these steps:
- Select Visualize Existing > C/C++ Type from the UML diagram's pop-up menu.
- A type selection dialog pops up (Figure 4), where you can type the first few characters of the class to visualize. For this example, type
Liin the Choose a type field.
- The dialog box will list the matches. Select LibraryEntry from the match list, and then click OK.
Figure 4. Type Selection dialog
Figure 5 shows the newly visualized class added to the diagram. Note that the inheritance relationship that exists between Book and LibraryEntry shows automatically.
Figure 5. Updated class diagram
Rational Systems Developer supports visualizing C++ elements with an existing diagram by dragging them from the C/C++ project browser or Project Explorer onto the diagram. When visualizing a file, the default option is to visualize all of the elements in the file. You can change this behavior by following these steps:
- Change the setting in the C++ modeling Preferences page, which you can access from Windows > Preferences.
- Then selecting Modeling > C++ Modeling from the Preferences tree (see Figure 6).
Figure 6. Preference for extracting elements from a C/C++ file
Navigating to the source code from the diagram
To navigate from a diagram element to its associated source code, you can either double-click the diagram element or use its pop-up menu.
- Double-clicking class, struct, union, typedef, or their member fields navigates to the element declaration location.
- Double-clicking class member methods navigates to the definition of the operation instead, if it exists, or to the method declaration.
The C++ Visualization features also provide an advanced navigation feature called Auto-Navigation. This option can be enabled and disabled by selecting the C++ Auto-Navigation icon from the diagram toolbar (see Figure 7a).
Figure 7a. Auto-Navigation icon in the Diagram toolbar
When enabled, this option splits the editor window into two parts, with the diagram in the top half and the C++ editor in lower half, highlighting the source code location of the element selected in the diagram. (Figure 7b).
Figure 7b. Auto-Navigation screen capture
Show or hide the relationship in the Class diagram
Relationships between elements can be shown or hidden by using the pop-up menu of the Class diagram. For example, to see only the association relationship between elements displayed on the diagram:
- Right-click on the diagram, and select the Filters > Show/Hide Relationship entry from the pop-up menu.
- Then select to hide all of the relationships except association relationships, as Figure 8 shows.
Figure 8. Show/Hide Relationship dialog
Show as an association or attribute
An association between two elements can be shown either as an attribute in the class or as an association to the related element. For example, visualize the class
Book on to the diagram. Now drag the
authorName field out of the class as shown in Figure 9. This will show the relationship between them as an association. This can also done by right-clicking on the attribute and then selecting Filter > Show as Association from the pop-up menu.
Figure 9. Show association by dragging
To show an association as an attribute, right click on the association and choose Filter > Show as Attribute from the pop-up menu as shown in Figure 10.
Figure 10. Show as Attribute Action
Show related elements in the Class diagram
Show Related Elements is a very useful feature in Rational Systems Developer that enables you to find related elements for C++ element visualized on a class diagram. To run this action:
- Right-click on the visualized element.
- Then select Filters > Show Related Elements from the pop-up menu (Figure 11).
Figure 11. Show Related Elements menu
This brings up the Show Related Elements dialog (Figure 12), which has predefined queries that help to visualize the inheritance tree, to include graphs, and so on. By using the custom query option, you can control the kind, direction, and depth of the related element that you want to visualize.
Figure 12. Show Related Elements dialog
Using the Modeling Assistant
Show Related Elements queries can also be run from the modeling assistant. For example, to query incoming related elements, place the mouse on the element and double click on the box of the incoming arrow that pops up. This will show a pop-up menu with a list of the queries that can be run (Figure 13). Doing the same on the outgoing arrow provide queries for outgoing relationships. Note that these queries are limited to one level only, meaning that you cannot select the depth of the query.
Figure 13. Show Related Elements by using the Modeling Assistant (Incoming)
Explore the code for the Browse diagram
Browse diagrams are non-editable diagrams that help explore relationships from a single focus element. To create a browse diagram:
- Select Visualize > Explorer in Browse Diagram from the element's pop-up menu. This is available from both Project Explorer and Diagrams views. Figure 14 shows the Browse diagram for the
Figure 14. Browse diagram for the Book class
The type and depth of relationship to display can be controlled using the browse diagram tool bar (see Figure 15). Focus element of the browse diagram can be changed by double clicking, in the browse diagram, on the element that is to become the new focus, or by using the pop-up menu, as described previously, to select the new focus element. For example, try double-clicking LibraryEntry.
Figure 15. Browse diagram toolbar
Browse diagrams keep a history of the views it displays so that you can navigate forward and backward from each view. However, you cannot save the browse diagram, but a copy of the diagram can be saved as a new diagram file or image file using the File menu of the diagram's pop-up menu.
Dynamic diagram example: Topic diagram
A Topic diagram is a query-based, non-editable diagram that helps to view relationship between elements. To create a Topic diagram:
- Select Visualize > In Topic Diagram from diagram elements or Visualize > Add to New Diagram File > Topic Diagram from the C/C++ project browser or from the Project Explorer. For example, to create a topic diagram for elements related to
- Select both from the browser, right-click to bring up the pop-up menu, and choose Visualize > Add to New Diagram File > Topic Diagram as Figure 16 shows. This action pops up a dialog asking for the name and location to create the topic diagram.
- For this exercise, you can accept the default values. This will bring up the topic diagram wizard. On the first screen, select the query to run. For example, select the Related Elements query (Figure 17), and then click Next.
- The next wizard page enables you to customize the depth and the kind of relationship to display. For this example, accept the default by clicking Finish. This will create the Topic diagram shown in Figure 18.
Figure 16. Creating a new Topic diagram
Figure 17. Topic diagram dialog
Figure 18. Topic diagram
A Topic diagram saves only in context: the elements originally selected and the query to run. The query consists of the relationships, plus the direction and the depth that you have selected. Unlike other diagrams, each time a topic diagram is opened, it runs the query automatically and updates the diagram to reflect the latest source code. If a relationship has been changed after the diagram is open, you need to select Refresh from the diagram pop-up menu or close and open the topic diagram to get it updated. A Topic diagram can be customized after you have created it, by using the Customize Query item from the diagram's pop-up menu, which will show the second page of Topic Diagram wizard Figure 17, shown previously).
Visually editing source code
Rational Systems Developer tools support the creation and editing of C++ elements from the Class diagram by using the palette, pop-up action bar, Modeling Assistant, or pop-up menu.
Creating new C++ elements
A new C++ Class or enumeration can be created by using either the C/C++ (Figure 19) or the pop-up action bar (Figure 20) of a Class diagram.
Figure 19. C/C++ palette
Figure 20. Pop-up action bar
For example, to create a new C++ class named
ElectronicMedia that is derived from
- Select C++ Class from the palette, and then click on a class diagram.
- This will pop up the CDT New Class wizard (see Figure 21).
- Type the name of the class as
- Now, to select the base class, click the Add button, and select LibraryEntry from the dialog box.
- Click Finish.
You can also change the default files to be created and specify a namespace to which this class belongs in the New Class wizard.
Figure 21. CDT New Class wizard
Next, create a new enumeration that represents the
ElectronicMedia type, which you will name
- Place the cursor on an empty location in the Class diagram.
- When the action bar pops up, select the brown E (letter E). (See Figure 20, shown previously.)
- This launches the New Enum wizard (Figure 22). Type in the name as
- Click Finish.
You can also change the default source files and specify the namespace that the enumeration belongs to in this wizard.
Figure 22. The New Enum wizard
You can add new fields and operations to a visualized C++ class by using either the pop-up menu (Figure 23) or the pop-up action bar (Figure 24).
Figure 23. C/C++ Add member pop-up menu for the C++ class
Figure 24. Popup action bar for the C++ class
For example, to add a protected field of type
Publisher to the
- Click the Add Field icon in the pop-up action bar of class
ElectronicMedia(see Figure 24 again).
publisheras name in New C/C++ Field wizard that appears (Figure 25)
- To select the type
Publisher, click Type Browse.
- In the Type Selection dialog, type the letter
Pto list all elements that start with P.
- Select Publisher from the list , and click OK.
- From the Access Visibility drop-down menu, select Protected.
- Click Finish.
Figure 25. Add Field wizard
Similarly, to add a new method called
Publisher getPublisher() to the
- Right-click the class ElectronicMedia as visualized on a diagram.
- Select Add C/C++ > Method from the pop-up menu, as previously shown in Figure 23.
- In New C/C++ Method wizard that pops up (Figure 26, which follows), enter
getPublisheras the method name.
- To select Publisher as the return type, click the Browse button for Return Type.
- In the Type Selection dialog that pops up, type
Pto list all elements that start with the letter P.
Publisherfrom the list and click OK button.
- Click Finish.
Figure 26. Add Operation wizard
Adding enumeration literals
You can also add enumeration literals to an
enum element that is visualized on a class diagram by using either the pop-up action bar (Figure 27) or the pop-up menu (Figure 28). For example, to add a new literal of
- Hover the cursor over the visualized EMediaType.
- Select the Add enum literal button from the pop-up action bar (Figure 27)
- In the Enumeration Literal wizard (Figure 29) that pops up, enter the literal name as
- Click Finish.
Figure 27. Add Enumeration Literal pop-up action bar
Figure 28. Add Enumeration Literal pop-up menu
Figure 29. Add Enumeration Literal wizard
Creating relationships between C++ elements
You can easily create relationships between C++ elements by using the click-and-drag method. The type of the relationship can be selected from the C/C++ Palette (See Figure 19, previously.) For example, to create an association relationship from
- Select Create Association from the C/C++ palette (Figure 19, shown previously).
- Click ElectronicMediaType, and drag that element to Author.
- Specify the name, visibility, and other details in the wizard that pops up (Figure 30).
- Click Finish.
Figure 30. Create Association wizard
If you prefer, you can create relationships by using the Modeling Assistant, instead. With this tool, you can create relationships with elements that are already on the diagram, with existing elements that are not on the diagram, or with new elements. For example, to create a new class called
EBook that inherits from the
- Hover the cursor over ElectronicMedia.
- Click and drag the incoming arrow from the element to an empty diagram location. This will pop up a menu (Figure 31).
- Select Create Inherits (Generalization) from > New Element: C++ Class. This will launch the New Class wizard shown here earlier in Figure 21.
- Enter the name as
EBook, and click Finish.
- Next, you'll see the Inheritance wizard, where you can specify the visibility as Public.
- Click Finish.
Figure 31. Create an inheritance related to a new class by using the Modeling Assistant
Figure 32. The Create Inheritance wizard
To create a relationship between elements on the diagram by using the Modeling Assistant:
- Drag either of the incoming or outgoing arrows between the two elements.
- Then select the type of relationship, such as Author or Publisher, as shown in Figure 33.
Figure 33. Creating an association by using the Modeling Assistant
Changing member visibility
Visibility of a C++ class member can be easily changed from the diagram by using the element's pop-up menu. For example, under ElectronicMedia, to change the visibility of the field publisher to private, right-click the field and select Visibility > Private from the pop-up menu, as shown in Figure 34.
Figure 34. Changing member visibility
You can rename an element visualized on a diagram from the element's pop-up menu: Refactor > Rename. For example, to rename the field
- Right-click on the field type and select Refactor > Rename, as shown in Figure 35.
- Enter the new name,
mediaType, in the Rename Refactor wizard when it appears (Figure 36).
- Select Preview to preview your changes, and then click OK.
Figure 35. The Rename pop-up menu
Figure 36. The Rename Refactor wizard
Editing directly from a diagram
Another method for renaming of elements is by editing them directly from the diagram. You can also change types of fields and operations by this method. For example, under the
Library class, to change the name and type of the
entries: int field to
totalEntries:long, follow these steps:
- Select the Entries field.
- Click the diagram to make the diagram text editable (Figure 37).
- Enter the new name and type-in format as
totalEntries: long, and press Enter.
This is the UML way of specifying the name and type. Do not use the C++ style of specifying this information.
- When you see the Edit Preview dialog (Figure 38), click OK in that dialog screen.
Figure 37. In-diagram edit in action
Figure 38. Edit Preview dialog
Renaming directly in the diagram can be a simple rename or refactor. You need to set this option on the C++ modeling Preferences page:
- Select Window > Preferences.
- The select Modeling > C++ Modeling from the tree (Figure 39).
- When you choose Simple rename, only name at the location represented in the diagram will be changed.
- When you choose Refactor rename, all reference to this name will be changed.
Figure 39. C++ Modeling Preference page
It is best to review the changes by using the Preview option. This is because the actual source code and the variable binding can change, based on the environment or the build time definitions of macros and preprocessor commands.
Harvesting UML elements
Harvesting provides a way to create UML elements from visualized C++ elements. The C++ elements harvested from the diagram can be pasted into a UML model as new UML elements. These UML elements are a copy of the C++ element at the time of harvest and do not change when the source code changes. For example, to harvest the
ElectronicMedia elements to add them the UML
- Select the element that you want to harvest on the diagram, right-click, and select Harvest from the pop-up menu (Figure 40).
- A dialog box will confirm the harvest action, and the UML element created will be placed on the clipboard.
- Right-click the UML model called LibraryModel, and select Paste (Figure 41).
- This will show the Paste Objects dialog. Choose Automatic Paste or, if you want to be able to see what you're pasting, choose Visual Paste, instead.
- The element will be pasted into the model, as shown in Figure 42.
Figure 40. Harvest menu
Figure 41. Harvest Paste menu
Figure 42. UML elements harvested from C++ elements
Note that all fields and methods of the element have been copied to the new UML element. References to other element that are not harvested still refer to the actual C++ elements. For example, if you drag the Author field out of the harvested element on a diagram, it shows an association with the C++ element in the source code, as you see in Figure 43.
Figure 43. Harvest relationship
Process and benefits summary
Rational Systems Developer gives you UML modeling experience with C++ projects by using the C/C++ Development Toolkit (CDT). It enables you to use C++ elements in UML diagrams, such as Class, Topic, and Browse diagrams, thereby providing a very useful feature to visually discover and study relationships between C++ elements in the project and, at the same time, reflect any source code change as it happens.
|Sample C++ project for this article||library.zip||10KB|
- How to use the C/C++ Development Toolkit (CDT) with the Eclipse platform (IBM developerWorks®, updated June 2006).
- Eclipse site information about the C/C++ Development Toolkit (CDT), the open source, Eclipse-based C/C++ development environment.
- For technical resources, visit the Rational Systems Developer area on developerWorks, where you'll find technical documentation, how-to articles, education, downloads, product information, and more. IBM Rational Systems Developer is an Eclipse-based design and construction product that aids model-driven development for software products and systems development. It enables software architects and developers to create C/C++ and Java (J2SE) applications by using the Unified Modeling Language (UML).
- Subscribe to the developerWorks Rational zone newsletter. Keep up with developerWorks Rational content. Every other week, you'll receive updates on the latest technical resources and best practices for the Rational Software Delivery Platform.
- Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.
- Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
- Stay current with Technical events and webcasts.
- Browse the technology bookstore for books on these and other technical topics.
Get products and technologies
- Download a trial version of IBM Rational Systems Developer Version 7.0. The download is free but requires registration.
- Download trial versions of other IBM Rational software.
- Check out the developerWorks Forum for Rational Systems Developer, Software Architect, Data Architect, Software Modeler, Application Developer and Web Developer. Ask questions, share tips, talk about solutions to problems related to Rational Systems Developer and the C++ Visualizer feature. To participate by e-mail, subscribe with a note to firstname.lastname@example.org. Subscribers may post by e-mail to email@example.com.
- Check out developerWorks blogs and get involved in the developerWorks community.