Themes in IBM Rational Software Architect
Using themes to make easily understood and better looking diagrams
Before you start
Learn what to expect from this tutorial, and how to get the most out of it.
About this tutorial
This tutorial explains theme and appearance concepts, as introduced in Version 8 of the IBM® Rational® Software Architect solution.
This tutorial covers the following topics:
- What is a theme?
- Applying a theme
- Creating and modifying your own theme
- Setting the default theme
- Using appearances outside of themes
- Sharing your themes with others (export)
- Using themes created by others (import)
All examples in this tutorial are based on a Unified Modeling Language™ (UML) model, but the same techniques can be applied to Deployment and Business Process Modeling Notation (BPMN) models. In addition, the examples depicted in the tutorial are shown using the Rational Software Architect environment.
What is a theme?
To explain themes, let us apply one of the ready-to-use, predefined themes that are included in the product. We will start with an example State Machine Diagram that has the default appearance, as shown in the figure below.
Figure 1. Sample State Machine diagram with default look
There are several ways to apply a theme, as discussed in the next section. For now, we will use the Themes toolbar drop-down icon to apply one of the predefined themes.
Figure 2. Themes toolbar menu
Select the Brown theme. The figure below shows how the diagram appearance changes.
Figure 3. Sample diagram after applying Brown theme
Let us take a look at how the Brown theme is defined. Click on the Themes toolbar drop-down icon again, and scroll to the bottom. Select the "Theme Details…" option. The Theme Details dialog opens up initialized with the Brown theme, since that was the last theme applied to this diagram. See Figure 4, below.
Figure 4. Themes Details dialog showing Brown theme
In the dialog above, Orthogonal State, Composite State and Submachine State have the Brown 5 appearance assigned. That is why these three types of states on the diagram in Figure 3 have the appearance that matches the Brown 5 sample, as shown next to that appearance name. Other elements on the diagram (States, Join, etc) are not listed in the theme definition table. That means that they will have the appearance as specified next to Shape element type on top of the table, which is Brown 1 in this case.
As you can see, a theme is defined by assigning various appearances to element types that can have visual representation on diagram. Appearance assigned to Shape element type applies to all shapes, unless a customization is done, like for Orthogonal, Composite and Submachine states in Brown theme. The same rule applies for connectors: appearance next to Edge element type will be applied to a connector, unless a customization for that connector type is done.
Below are the samples of the same diagram, but with other predefined themes applied to it: Gold, Green, Khaki and Purple.
Figure 5. Sample diagram with Gold, Green, Khaki and Purple themes applied
Note: you may have noticed in the examples above that each State figure (e.g., State1, State2 etc.) on the diagram has a darker header, filled with the gradient. While gradient colors change as fill color changes (gradient colors are darker), gradient itself is a part of the design and not the definition of the appearance that is assigned to State. If you do not like this darker gradient fill, you can turn it off by going to the Appearance preference page and selecting "No gradient" option of "Gradient in text compartment". The different options are shown below.
Figure 6. State shape with various gradient preferences set
Applying a theme
There are several ways to apply a theme:
- Using the Themes toolbar icon, as shown in Figure 2. You can either select one of the themes offered in the drop-down list, or select the "Theme Details…" option, which opens the Theme Details dialog. From there you can select, or optionally create or modify a theme, and then apply it.
- Using one of the themes diagram context menu options. They are:
- Themes…: this option opens the Theme Details dialog.
- Apply Default Theme: this option will apply the theme as set in the appearance preferences (for more on default theme, see Setting the default theme section).
- Using one of the themes options on the Diagram menu option. Theme options here are the same as those on the diagram context menu.
- Using the diagram Appearance property tab. The "Applied theme:" drop-down box on top of this tab lets you select either a theme to apply, or the "Theme Details…" option that opens the Theme Details dialog. If there is a theme applied to the diagram, its name is selected here. You can see this in Figure 18.
- Using one of the themes context menu options on a diagram or model element selected in the Project Explorer. With this method, the selected diagram does not need to be opened, and you can apply the theme to several diagrams at once. On the other hand, you can select one or more models in the Project Explorer and apply the theme using the context menu option. In this case, the model or models need to be opened before the theme can be applied. Applying the theme to a model results in applying the theme to all of the diagrams in that model.
Creating and modifying your own theme
The previous section demonstrated a few predefined themes that are included with the product. It is very likely though that you will need to create your own themes that suit your taste, or that are useful for making your diagrams more clear.
A theme can be created, or an existing user-defined theme can be modified, from the Theme Details dialog. For different ways to access the Theme Details dialog, see the Applying a theme section. For a sample image of this dialog, see Figure 4. Before starting, let us explore the Theme Details dialog a bit more.
The name selected in the drop-down list on top of the dialog shows the name of the theme whose definition is in the table underneath it. You can select any of the themes from the drop-down list to work with.
The option next to the theme name drop-down lets you restrict the elements in the list to only those elements relevant to the diagram type whose context was used when opening the dialog. Note that if the dialog was opened from the Project Explorer context, then this option is not present. If you want to work with all elements, for example when defining a theme that works for all diagram types, you need to un-check this option.
Figure 7. Name drop-down and check box on Theme Details dialog
The theme definition table has three columns: one for the appearance assigned to a specific element type, another one for the element type, and a third column for the palette drawer. This last column shows where you can find the element of given type if you wanted to create it on diagram. Each of the three columns in the themes definition table can be sorted by clicking on the column header.
Figure 8. Columns of the theme definition table
Changing the appearance associated with an element type
Let us say that you want a theme that is similar to the Brown theme, but you want the Orthogonal State to use bold font and a different fill color. Start by selecting the Brown theme in the name drop-down. Then click in the Brown 5 appearance cell next to the Orthogonal State, and click on the "…" button that shows up. The list of existing appearances opens, as you can see in the figure below.
Figure 9. Changing appearance in the theme definition table
Just like there is a set of predefined themes, there is also a set of predefined appearances that are included in the product. At this point, you can either choose one of these, or create a new one. To create a new appearance, scroll to the bottom of the list and select the "Appearance Details…" option. The Appearance Details dialog opens up, initialized to the Brown 5 appearance.
Figure 10. Appearance Details dialog
Since Brown 5 is a predefined appearance, you cannot modify it directly, but you can create a new appearance based on it. For example, set the font to bold and set the fill color to orange. Then click on "Save As…". In the dialog that pops up, enter a unique appearance name, for example "Orange bold". Press OK, and your custom appearance is saved. If you examine the Name drop-down list, you will see that your newly created appearance is listed. User-defined appearances are listed on top, and do not have the bold font like predefined appearances do. This is shown in Figure 11 below.
Figure 11. Appearance list after creating a new appearance
Now just click on Apply button at the bottom of the dialog and your new appearance will be set as the one for the Orthogonal State in Brown theme. Tip: you can change the appearance selection for several element types at once. For example, to change the appearance of both the Orthogonal State and the Composite State, select both of these rows, and then proceed as described previously.
You can test out your modification by clicking on the Apply button at the bottom of the Theme Details dialog and examining the diagram. At any point, you can click on the Revert button at the bottom of the dialog, which will remove all your changes since the last save.
Adding element types to the theme definition
You can easily add new elements to the theme definition. For example, if you want to define a specific appearance for the Join State and the Final State, you need to click on the Add button on the right side of the themes definition table.
Figure 12. Add button on the Theme Details dialog
You will see a dialog with the list of all element types that have not been added to the definition of the current theme yet. Remember that if the "Show only elements relevant to Statechart" option on the Theme Details dialog is selected, you will only see element types related to the Statechart diagram, as shown below.
Figure 13. Choosing element type(s) to add to theme definition
You can sort the list by any of the three columns by clicking on the column header. Sort by Element type, and select Final State and Initial State. The Next button becomes enabled. Click on it to get to the next page, which lets you choose the appearance for the selected elements.
Figure 14. Choosing an appearance for selected element type(s)
At this point, you can either select from the list of existing appearances, or create a new one by selecting the "Appearance Details…" option. Creating a new appearance was discussed previously, so now just select an existing appearance, for example "Red with red border", and click Finish. Two new rows appear in the theme definition table – one for Initial State and one for Final state. Note: you could also click Finish without selecting an appearance. In that case, two new rows would be added to the theme definition table, and their appearance could be selected later.
Deleting element types from the theme definition
Let us assume that you want the Composite State to have Brown 1 appearance, which is assigned to the Shape element type. This means that you no longer need customization row for the Composite State, and you can delete that row by selecting it and clicking on Delete button. You can also select several rows (keep Control button down while selecting) and delete them all at once.
If, when creating a new theme, you want to start with a blank theme definition, unselect the check box on top of the dialog (so that a complete definition of the theme is considered) and click the Delete All button. All rows are deleted, except the ones for Shape and Edge element type.
Figure 15. Deleting appearance-element type pairs from theme definition
Saving the theme
In previous sections, we started from the Brown predefined theme and made the following changes:
- Created new appearance Orange bold and assigned it to Orthogonal State instead of Brown 5 appearance
- Added the Initial State and the Final State element types to the theme definition and assigned the Red with red border appearance to them.
- Deleted the Composite State row from the table.
Here is how our sample diagram looks like after applying all of these modifications.
Figure 16. Sample diagram after applying modified Brown theme
You are now ready to save the theme. You started from a predefined theme, so you cannot update it (i.e., you cannot use the Save button). But you can create a new theme that will contain all the modifications made. Click on the Save As… button and in the dialog that appears, enter a unique theme name, e.g., My Theme, and click OK. Your theme is saved and ready to use. If you look at the Name drop-down menu, you will see My Theme at the top. User-defined themes are listed on top, and unlike predefined themes, do not use bold font. Later on, you can modify this theme, and use the Save button to save the changes. If you no longer need it, you can delete it by clicking on Delete button on the bottom of the Theme Details dialog. Note that you cannot delete predefined themes.
Setting the default theme
When you apply a theme to a diagram, then all diagram elements created from that point on will have the appearance defined in that theme. If you never apply a theme to a diagram, the default theme is used. The default theme is set in the preferences. Navigate to the Window -> Preferences -> Modeling (or BPMN Modeling for BPMN models, or Topology Editor for Deployment) -> Appearance preference page. A theme called Default is set as the default theme, but you can change it to whatever theme suits your needs. The Figure below shows the relevant part of the Appearance preference page.
Figure 17. Default theme on Appearance preference page
You can check if a theme was applied to a diagram by navigating to the diagram Appearance property tab in the Properties view, as shown below. This theme, if any, will be used when new diagram elements are created. You can remove this theme application, in which case the default theme takes over.
Figure 18. Checking what the last applied theme is
Note that changing the default theme only affects diagram elements created after the change was made. However, there is a quick way for you to indicate that you want all, or some of the old diagrams to have the new default theme. In the Project Explorer, select one or more models, or select one or more diagrams, to which you want the new default theme to apply. Then, from the context menu, select the "Apply Default Theme" option. All of the selected diagrams, or all of the diagrams in the selected models, will have the default theme applied.
Using appearances outside of themes
Previously, appearances were introduced while explaining the concept of themes. A theme consists of appearance-element type pairs. In addition to being part of a theme, an appearance can be used independently of themes as well.
Applying an appearance
In our sample diagram shown in Figure 16, we may want State 1 and State 2 to be distinguishable from other States. We can achieve that by applying a different appearance to them directly. Select State 1 and State 2, and then select the Appearances toolbar drop-down icon.
Figure 19. Appearances toolbar menu
You may choose from the list of existing user-defined or predefined appearances, or navigate to the bottom of the list and select the "Appearance Details…" option to create a new appearance (or modify an existing user-defined appearance). Creation of a new appearance here is the same as described in Changing the appearance associated with an element type section. Choose, for example, Khaki 3, and note how the appearance of State 1 and State 2 changes.
You can also apply an appearance from the element’s context menu option "Appearances…", or from the Appearance properties tab, as shown below.
Figure 20. Applying an appearance from Appearance property tab
There is one more function on the Appearance Details dialog that should be mentioned here. Open the Appearance Details dialog from the context of a diagram element, e.g., State 1. Notice that the dialog has an option on the bottom to apply the appearance to all shapes with the same appearance as State1. Check this option. Select an appearance from the Name drop-down, e.g. "Light blue with blue border", and click the Apply button. Notice how State 2 changed, since it had the same appearance as State 1. This is shown in the figure below.
Figure 21. Changing appearance of all elements with the same appearance as selected
Using the "Add to Appearance List" option
If you have formatted some of your diagram elements before by using Formatting menu options, or by changing properties on the Appearance property tab, you now may want to capture these formats into appearances and themes. You can do this by selecting the diagram element whose format you want to capture and either choose the "Add to Appearance List" context menu option, or click on the Apply… button on the Appearance property tab of that element (you can see this button in Figure 20). The dialog appears, as can be seen in the figure below.
Figure 22. Dialog that lets you save selected formatting into an appearance and possibly a theme
Enter a unique name for the new appearance, e.g., My Gradient. Notice that after you entered an appearance name, the Theme drop-down became enabled. You can leave this drop-down blank. However, if you want the new appearance My Gradient to be assigned to the State element in one of the user-defined themes, you can select that theme from the list. Or you can choose to create a new theme that will include My Gradient – State pair.
Figure 23. Choosing a theme for selected element type - new appearance pair
To create a new theme, select "New…" option. The Theme Details dialog appears, and you can see how the new theme will be defined.
Figure 24. Entering the name of new theme in process of adding selected element type - new appearance pair
Note that appearances for Shape and Edge element types are taken from the theme that was last applied to the diagram (if no theme is applied to the diagram, then the default theme is consulted). At this point, you just need to enter a unique name for the new theme, e.g., My Gradient Theme and click Apply.
Finally, notice the checkbox on top of the dialog in Figure 22. If you leave it selected, all states will have this formatting after clicking OK.
Click OK. Now examine the appearance list and the theme list. Note how My Gradient is listed as another user-defined appearance, and My Gradient Theme is listed as another user-defined theme. This is shown in the figure below.
Figure 25. List of appearances and list of themes
Sharing your themes with others (export)
When you apply a theme to a diagram and you share the model that contains that diagram with someone else, they will see the diagram with the exact same styles as you are viewing. However, if you applied a theme that you created, that theme itself will not be available to them. It is local to your workspace, and you need to export it in order to share it with others.
To export the theme, navigate to File > Export. In the Export dialog, select the Themes node, as shown below, and click Next.
Figure 26. Export dialog: choosing themes node
On the Export page, select one or more themes to export, and/or one or more appearances to export (see figure below). You also need to enter the full path to the destination file. The export file must have an epf extension.
Figure 27. Export dialog: choosing themes and appearances to export
Note that user-defined appearances that are part of themes selected for export will be automatically included in the export. In our example, both the My Gradient and Orange bold appearances will be exported, since the selected themes reference them.
After you click the Finish button, your themes are exported and ready to be imported by someone else.
Using themes created by others (import)
If you want to use a theme created by someone else, or created by you in another workspace, you need to import it into your current workspace. First, you need to obtain the file that contains the exported theme (see the previous Sharing your themes with others (export) section). Then, navigate to File > Import. In the Import dialog, select the Themes node, and click Next. On the Import page, enter the full path to the exported file. Select the themes and appearances to be imported. The figure below illustrates that.
Figure 28. Import dialog: choosing themes and appearances to import
Click on the Finish button. All selected themes and appearances are imported. User-defined appearances that are referenced by themes selected for import will be imported automatically, regardless of their selection. Note that if you already had a theme with the same name as one of the imported themes, that theme will be overridden by the imported one. The same holds for the appearances.
This tutorial explains theme and appearance concepts, introduced in Version 8 of IBM® Rational® Software Architect. It covers different functions that you can utilize in order to make your diagrams look better or make them easier to read. You saw how to use predefined themes that are included in the product, how to create your own themes, how to use appearances outside of themes, and how to share user-defined themes. You also learned how to convert visual style formatting that you created before the latest Rational Software Architect 8.0 version into reusable appearances and themes.
- Rational Software Architect Designer for WebSphere Software
- Release documentation
- Download a trial version of Rational Software Architecture
- Get IBM training and skills