Working with C++ Visualization in IBM Rational Systems Developer

An introduction

The C++ Visualization features of IBM® Rational® Systems Developer enable you to work with C++ code, using a UML-like notation that provides an experience similar to UML modeling. This article shows how to graphically represent (visualize) C++ elements, discover and display their relationships in UML diagrams, create new C++ elements, edit source code directly from diagrams, and create relationships and navigation features.

Janees Elamkulam (janees.ek@in.ibm.com), Software Engineer, IBM

Janees Elamkulam works for IBM Rational Software, where he develops software for UML- based modeling and code-generation tools. His interests include code generation, modeling, and verification of software. Janees has a Master of Technology degree in Computer Science from the Indian Institute of Technology Bombay (IIT Bombay) and a B. Tech. in Computer Science from Calicut University.



05 June 2007

Also available in Chinese

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.

Getting started

About CDT project indexers

The Rational Systems Developer C++ Visualization features rely on the Eclipse CDT indexer to get information about the source elements. Therefore, it is advised to enable Full Indexing for projects. You can set this option either while you are creating the project or from the project Properties page. You can also set the full indexer as the default indexer for all C++ projects from the Preferences page (Main menu > Windows > Preferences > C/C++ > Indexer).

  • 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:

  1. Activate the pop-up menu.
  2. Select Visualize > Add to New Diagram File > Class Diagram.
Figure 1. Visualize the pop-up menu
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
Figure 2. A C++ Class visualized on a Class diagram
Table 1. Icons and stereotypes for C++ elements
C/C++ ElementIconStereotype
ClassC++ class icon<<class>>
StructStruct icon<<struct>>
UnionUnion icon<<union>>
TypedefTypedef icon<<typedef>>
EnumEnum icon<<enum>>
NamespaceNamesapce icon<<namespace>>
Source fileC (source) file icon<<file>>
Header fileHeader file icon<<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
Figure 3. Shows the Visualize Existing pop-up menu

For example, to visualize class LibraryEntry from the sample project by using this option., follow these steps:

  1. Select Visualize Existing > C/C++ Type from the UML diagram's pop-up menu.
  2. 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 Li in the Choose a type field.
  3. The dialog box will list the matches. Select LibraryEntry from the match list, and then click OK.
Figure 4. Type Selection dialog
Figure 4. Shows the 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
Figure 5. Shows the updated class diagram

Drag-and-drop operation

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:

  1. Change the setting in the C++ modeling Preferences page, which you can access from Windows > Preferences.
  2. Then selecting Modeling > C++ Modeling from the Preferences tree (see Figure 6).
Figure 6. Preference for extracting elements from a C/C++ file
Figure 6. Preference for extracting elements from a C/C++ file

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
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
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:

  1. Right-click on the diagram, and select the Filters > Show/Hide Relationship entry from the pop-up menu.
  2. Then select to hide all of the relationships except association relationships, as Figure 8 shows.
Figure 8. Show/Hide Relationship dialog
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
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
Figure 10. How to 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:

  1. Right-click on the visualized element.
  2. Then select Filters > Show Related Elements from the pop-up menu (Figure 11).
Figure 11. Show Related Elements menu
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
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)
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:

  1. 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 Book class.
Figure 14. Browse diagram for the Book class
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
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:

  1. 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 Book and LibraryEntry.
  2. 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.
  3. 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.
  4. 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 16. Creating a new Topic diagram
Figure 17. Topic diagram dialog
Figure 17. Topic diagram dialog
Figure 18. Topic diagram
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 19. C/C++ palette
Figure 20. Pop-up action bar
Figure 20. Pop-up action bar

For example, to create a new C++ class named ElectronicMedia that is derived from LibraryEntry:

  1. Select C++ Class from the palette, and then click on a class diagram.
  2. This will pop up the CDT New Class wizard (see Figure 21).
  3. Type the name of the class as ElectronicMedia.
  4. Now, to select the base class, click the Add button, and select LibraryEntry from the dialog box.
  5. 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
Figure 21. CDT New Class wizard

Next, create a new enumeration that represents the ElectronicMedia type, which you will name EMediaType:

  1. Place the cursor on an empty location in the Class diagram.
  2. When the action bar pops up, select the brown E (letter E). (See Figure 20, shown previously.)
  3. This launches the New Enum wizard (Figure 22). Type in the name as EMediaType.
  4. Click Finish.

Tip:
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
Figure 22. The New Enum wizard

Adding members

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 23. C/C++ Add member pop-up menu for the C++ class
Figure 24. Popup action bar 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 ElectronicMedia class:

  1. Click the Add Field icon in the pop-up action bar of class ElectronicMedia (see Figure 24 again).
  2. Enter publisher as name in New C/C++ Field wizard that appears (Figure 25)
  3. To select the type Publisher, click Type Browse.
  4. In the Type Selection dialog, type the letter P to list all elements that start with P.
  5. Select Publisher from the list , and click OK.
  6. From the Access Visibility drop-down menu, select Protected.
  7. Click Finish.
Figure 25. Add Field wizard
Figure 25. Add Field wizard

Similarly, to add a new method called Publisher getPublisher() to the ElectronicMedia class:

  1. Right-click the class ElectronicMedia as visualized on a diagram.
  2. Select Add C/C++ > Method from the pop-up menu, as previously shown in Figure 23.
  3. In New C/C++ Method wizard that pops up (Figure 26, which follows), enter getPublisher as the method name.
  4. To select Publisher as the return type, click the Browse button for Return Type.
  5. In the Type Selection dialog that pops up, type P to list all elements that start with the letter P.
  6. Select Publisher from the list and click OK button.
  7. Click Finish.
Figure 26. Add Operation wizard
Figure 26. Add Operation wizard

These actions will show, respectively, in the Add Field wizard or the Add Operation wizard, as Figure 25 and Figure 26 show.

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 CD to EMediaType:

  1. Hover the cursor over the visualized EMediaType.
  2. Select the Add enum literal button from the pop-up action bar (Figure 27)
  3. In the Enumeration Literal wizard (Figure 29) that pops up, enter the literal name as CD.
  4. Click Finish.
Figure 27. Add Enumeration Literal pop-up action bar
Figure 27. Add Enumeration Literal pop-up action bar
Figure 28. Add Enumeration Literal pop-up menu
Figure 28. Add Enumeration Literal pop-up menu
Figure 29. Add Enumeration Literal wizard
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 ElectronicMediaType to Author:

  1. Select Create Association from the C/C++ palette (Figure 19, shown previously).
  2. Click ElectronicMediaType, and drag that element to Author.
  3. Specify the name, visibility, and other details in the wizard that pops up (Figure 30).
  4. Click Finish.
Figure 30. Create Association wizard
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 ElectronicMedia class:

  1. Hover the cursor over ElectronicMedia.
  2. Click and drag the incoming arrow from the element to an empty diagram location. This will pop up a menu (Figure 31).
  3. Select Create Inherits (Generalization) from > New Element: C++ Class. This will launch the New Class wizard shown here earlier in Figure 21.
  4. Enter the name as EBook, and click Finish.
  5. Next, you'll see the Inheritance wizard, where you can specify the visibility as Public.
  6. Click Finish.
Figure 31. Create an inheritance related to a new class by using the Modeling Assistant
Figure 31. Create an inheritance related to a new class by using the Modeling Assistant
Figure 32. The Create Inheritance wizard
Figure 32. The Create Inheritance wizard

To create a relationship between elements on the diagram by using the Modeling Assistant:

  1. Drag either of the incoming or outgoing arrows between the two elements.
  2. 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
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
Figure 34. Changing member visibility

Rename refactor

You can rename an element visualized on a diagram from the element's pop-up menu: Refactor > Rename. For example, to rename the field type of ElectronicMedia to mediaType:

  1. Right-click on the field type and select Refactor > Rename, as shown in Figure 35.
  2. Enter the new name, mediaType, in the Rename Refactor wizard when it appears (Figure 36).
  3. Select Preview to preview your changes, and then click OK.
Figure 35. The Rename pop-up menu
Figure 35. The Rename pop-up menu
Figure 36. The Rename Refactor wizard
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:

  1. Select the Entries field.
  2. Click the diagram to make the diagram text editable (Figure 37).
  3. Enter the new name and type-in format as totalEntries: long, and press Enter.

Important:
This is the UML way of specifying the name and type. Do not use the C++ style of specifying this information.

  1. When you see the Edit Preview dialog (Figure 38), click OK in that dialog screen.
Figure 37. In-diagram edit in action
[In-diagram edit in action]
Figure 38. Edit Preview dialog
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:

  1. Select Window > Preferences.
  2. 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
Figure 39. C++ Modeling Preference page

Tip:
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 Book and ElectronicMedia elements to add them the UML LibraryModel model:

  1. Select the element that you want to harvest on the diagram, right-click, and select Harvest from the pop-up menu (Figure 40).
  2. A dialog box will confirm the harvest action, and the UML element created will be placed on the clipboard.
  3. Right-click the UML model called LibraryModel, and select Paste (Figure 41).
  4. 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.
  5. The element will be pasted into the model, as shown in Figure 42.
Figure 40. Harvest menu
Figure 40. Harvest menu
Figure 41. Harvest Paste menu
Figure 41. Harvest Paste menu
Figure 42. UML elements harvested from C++ elements
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
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.


Download

DescriptionNameSize
Sample C++ project for this articlelibrary.zip10KB

Resources

Learn

  • 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

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=227503
ArticleTitle=Working with C++ Visualization in IBM Rational Systems Developer
publish-date=06052007