Graphically modeling classes
Learning the basics of the Xcode modeling tools
Customizing diagrams and filtering out extraneous detail
To be an effective object-oriented programmer, you must have a clear mental picture of the classes in your application and their relationships. Sometimes this "picture" is hard to form, because class relationships can be both complex and abstract. The class browser, discussed in Chapter 9, uses the project's index to list your project's classes. Although this helps, it still doesn't present a bird's-eye view of your application's structure. Enter class modeling. Class modeling performs the same function as the class browser, but in a much more visual and customizable way.
You model classes by creating a class model document. The document can include any set of classes; this could be your entire application or just a set of functionally related classes. Xcode then graphs those classes, as shown in Figure 14-1. The class model tracks, and instantly reflects, any changes made to your source files. Unlike data modeling, discussed in the next chapter, the class modeler is not an editor. You cannot design or alter the declarations in a class model and then transform that model into code. In other words, the class modeler is not a UML design tool.
Class models are really useful when:
You want to maintain a clear picture of a complex set of classes.
You're considering refactoring a group of classes.
You're trying to assimilate a set of classes written by another developer or team.
You want to clearly document a set of classes for other developers.
If you're not in any of those circumstances, don't skip to the next chapter just yet. There's one more reason why you should learn to use the class modeler:
The class modeling tools use nearly the same interface as the data modeling tools.
The data modeling tools, described in the next chapter, build on the interface elements you learn in this chapter. The data modeling tools are used to create Core Data models — something in which you should definitely be interested. At the very least, skim this chapter to learn the basics of creating, browsing, navigating, editing, and customizing models. That knowledge will serve you well in Chapter 15.
A class model is stored in a class model document. The documents themselves are extremely lightweight, containing little more than a list of source files. Think of a class model document as just another "view" into your project.
Note
The information about your classes is gleaned from the project's Code Sense index. This exposes two very important prerequisites of class model documents:
Your project must be indexed for class modeling to work.
The project containing your classes must be open.
If Code Sense indexing is turned off, turn it on in the Code Sense panel of the Xcode Preferences. If your project is currently being indexed in the background, class modeling starts working as soon as the index is complete.
Class model documents cannot be used outside the context of a project. You cannot open a class model document unless the project that it refers to is also open. Although it is possible to create class model documents outside of your project, it is not advisable. If you are intent on keeping a class model, it should be stored in your project's folder, added to the project's source group, and only opened when the project is open.
For small projects, I tend to create a Models source group and store my project's class model documents there. For larger projects, like the one shown in Figure 14-2, I organize my classes into functional groups, and then store the class model document in the group that contains the classes it models.
You add a class model document to your project much as you would any new source file:
Choose File
Choose the Class Model document template.
Give the class model document a name.
Ignore the project targets.
Select the source files and source groups that you want to model.
You begin by using the File
Next, select the Class Model document type from the list of file templates, as shown in Figure 14-3. You will find the Class Model template under the Mac OS X "Other" group. Class model documents are universal, applying equally well to iPhone and other project types. Give the document a name. Xcode will want you to select the targets the class model document should be included in, as it does for any new project file; don't check any targets in the list. Class model documents are for reference only; they shouldn't be included in any build targets.
After naming your new document, Xcode presents the model's file tracking dialog box, shown in Figure 14-4.
On the left are all the source groups and files defined in the project. On the right is the list of files or groups that will be tracked by the new model. Select the source files, or source groups, that you want to model on the left and click the Add button to include them in the model. You can do this all at once or incrementally. The Add All button adds every single source file and group in your project. This is usually excessive and is not recommended; it's only useful in the case where it's more succinct to specify the files and groups you do not want to track.
If you have added too many sources, select them in the list on the right and click the Remove button. Remove All removes all of the sources, so you can start over.
You can add any kind of source file that you like, but the class modeler is only interested in class definitions. For Objective-C and C++, this will typically be the class's header (.h) file. In Java, the .java file that defines the class should be added. The class modeler creates a model using every class definition that it finds in those files. Files that contain non-class declarations, libraries, and so on are ignored. There's no harm in adding those files to the model, but there's no point either. It also makes no difference how many source files define the same class; a class appears in the model only once.
Here are the key points to keep in mind when building the tracking list for a class model:
Adding a source group to a model implicitly tracks every source file contained in that group. If the contents of the group change, so do the files in the model.
You can add both a source file and the group that contains that source file to the model. One reason for doing this would be to avoid having a class disappear from a model if it were moved outside its current source group.
Frameworks can be added. A framework is, logically, a source group that contains a number of header files. All of the classes defined in those headers will be added to the model.
Don't fret about what files to include, or exclude, at this point. The list of sources for the model can be freely edited in the future (as explained in the "Changing the Tracking" section).
Be judicious when adding system frameworks, because these typically define scores, if not hundreds, of classes. This can make for an unwieldy model. If you want to include classes defined in frameworks, add the specific headers you want by digging into the framework group.
After assembling your initial list of choices, click the Finish button. The class model document is added to the project and Xcode displays the new model.
Figure 14-1 showed a typical class model window. Like any project document, a class model pane can appear in the project window or in a separate window. The top portion of the pane contains the class browser and the bottom portion shows the class diagram. The horizontal divider between the two can be resized to show just one or the other. As a shortcut, the Design
The Quick Model command is a fast way of creating an ephemeral model for a select group of classes, and is an alternative to the more formal procedure for creating class model documents that was just described. Follow these steps to create a quick class model:
Select one or more source files or groups in an open project. You can do this in the project source group or in the details list.
Choose Design
The Design
Use the Quick Model command to gain quick insight into the class structure of an application. When you are done with the model, simply close it. If you made no modifications to the model, it just goes away. If you did, Xcode treats it like any unnamed document window and prompts you to save it. As mentioned earlier, class model documents are useless outside the context of the open project. If you don't want to keep the model, discard the changes or just save the file as is. The document is a temporary file, so just saving the file doesn't preserve it — it will still be deleted once you're finished with the diagram.
If you later decide you want to save the quick model as a permanent class model document, choose the File
The upper pane in the class model is the class model browser, as shown in Figure 14-5. On the left is the list of classes being tracked by the model. Selecting a class displays the class's members in the middle list. Selecting an item in either list displays additional information about that item in the details pane on the right. You can use the dividers between these sections to resize them, within limits.
Note
To avoid any confusion, the term "class browser," or just "browser," in this chapter refers to the class model browser, not the class browser discussed in Chapter 9.
Class modeling can be used to model C++, Java, and Objective-C classes. The terminology used in class modeling tends to be neutral:
Not all modeling concepts apply to all languages. Categories only appear when modeling Objective-Cclasses. Package names only appear when you're modeling Java classes. Multiple-inheritance can only occur with C++ classes.
You can customize the browser display a number of different ways. In the lower-left corner of both the class and member lists is a pop-up menu that will alter a list's display. The choices for the class list, shown on the left in Figure 14-6, are Flat List and Inheritance Tree. Flat List lists all of the classes alphabetically. Inheritance Tree lists the classes in a hierarchical browser.
The list options for the members list lets you select between Show All Members, Show Properties, and Show Operations.
You can resize and reorder the columns for both lists as desired by dragging the column separators or headers. Right/Control-click the column titles to control which columns the list displays, also shown in Figure 14-6. Check only those columns you want to see. The menu for both lists includes a Show All Columns command.
In the lower portion of the pane is the class diagram, as shown in Figure 14-7, and is class modeling's raison d'être. The diagram presents a graphic visualization of the class relationships. Note that the browser and diagram show much of the same information, just in different ways.
The entire class model diagram is contained on a variable number of pages that look like graph paper. The number of pages automatically expands to encompass the diagram.
Entities in a class model diagram are represented as nodes. At the top of each node is its title. Nodes may optionally show additional detail — quite a bit of detail, if you like. The form and color of the title indicate its type, as listed in the following table:
NODE TITLE | COLOR | NODE TYPE |
|---|---|---|
PlainTitle | Blue | Class |
<TitleInBrackets> | Red | Objective-C protocol or Java interface |
(TitleInParentheses) | Green | Objective-C category |
The background color of framework classes is darker than that of classes defined in your application.
Lines between nodes denote inheritance. The arrow points to the superclass, interface, or category from which the node inherits, conforms, or extends. The possible combination of arrows and lines is listed in the following table:
LINE AND ARROW TYPE | RELATIONSHIP |
|---|---|
Solid line with an open arrow | Points to the superclass or category that the class inherits |
Dashed line with an open arrow | Points to the interface or protocol that the class adopts |
Solid line with no arrow | Indicates an attached annotation node |
The compartments below the title detail the members of the class. The Properties member lists the instance variables and the Operations member lists the methods or functions. You can completely hide these details by "rolling up" the node, and reveal them again by rolling them down. You accomplish this by using the Design
The lists within the compartments can be individually expanded or collapsed by clicking the disclosure triangle to the left of the compartment title. To collapse or expand all the compartments at once, select a node or nodes and choose either the Design
The members of a class may optionally display their visibility (private, protected, or public), type, return type, or method parameters. All of these display options are set in the General tab of the diagram's Info window. With the selection tool, click anywhere on the background of the diagram so that no nodes are selected, and then choose File
The Show Visibility option refers to the scope or accessibility of class members, indicated by a small icon next to each member. The possibilities are as follows:
VISIBILITY/SCOPE | SYMBOL |
|---|---|
Private | red circle |
Package | orange triangle (pointing down) |
Protected | yellow triangle (pointing up) |
Public | green square |
The Show Property Type option includes the variable type after each class property. Show Operation Return Type shows the return value type of each operation. This may appear before or after the operation name, depending on the language being modeled. The Show Operation Parameter List option includes the entire parameter list of each operation, and can make for some very wide class nodes.
The Show Package option applies only to Java. If you select this option, the package name appears below the name of the class or interface in the node's title compartment.
Figure 14-10 shows a diagram with all the display options turned on (left) and off (right). Static, also known as class, operations are underlined. This is one display option that is not customizable.
Five tools, listed in the following table, are displayed in the palette in the lower-left corner of the class diagram. To use a tool, click it. The currently selected tool is highlighted, and the cursor reflects the current tool whenever it is in the class diagram pane.
TOOL | DESCRIPTION |
|---|---|
Arrow | Selection tool. Used to select elements, move, expand, and resize nodes. This is the default tool. |
Note | Note tool. Creates annotation nodes. |
Line | Line tool. Connects nodes. |
Magnifying Glass | Zoom tool. Enlarges or shrinks the diagram display. |
Hand | Drag tool. Pans the diagram around in the window. |
Choose the Arrow tool whenever you need to select, move, resize, or otherwise manipulate the nodes in a diagram.
The Note and Line tools are described later in the "Adding Annotations" section.
The Magnifying Glass and Hand tools are ways of navigating the diagram, and are described in the next section.
Moving around the class diagram is pretty straightforward. You can use the scroll bars at the bottom and right side of the pane to scroll the diagram. You can also select the Hand tool and drag the diagram around.
Reduce or magnify the diagram by selecting a magnification amount in the zoom control in the lower-right corner of the pane. You can select a specific magnification from between 10 and 1600 percent.
Use the Magnifying Glass tool to incrementally zoom the diagram. Select the tool and click anywhere in the class diagram pane to increase to the next zoom magnification in the menu. Hold down the Option key and a minus sign (−) appears in the tool. Click with the Option key held down and the diagram is shrunk to the next zoom magnification level in the menu. To zoom the diagram to fit an arbitrary portion of the diagram, drag out a rectangle using the Magnifying Glass tool. The image zooms so that the approximate area of the diagram selected fills the pane.
The Design
You can select class nodes in a variety of ways. Selecting a class also causes the diagram to scroll if the selected class is beyond the edge of the visible diagram.
Click a node to select it. Drag out a rectangle using the Arrow tool to select all of the nodes that intersect the rectangle.
Class selection in the diagram and browser are linked. Selecting a class in the browser selects the same class in the diagram, and vice versa. The Functions menu in a class diagram lists all of the classes in the model, as shown in Figure 14-11. Choosing one selects that class in both the browser and diagram, and scrolls to make both visible.
You can add class nodes to the selection by holding down the Shift key while clicking unselected nodes or dragging out a selection rectangle. Nodes can be individually removed from a selection by clicking a selected node while holding down the Shift key. It may be necessary to click the background area or the edge of a node; clicking the node's title or a member may not deselect it.
You can also type the first few letters of a class name. When listed alphabetically, the first class that matches the characters typed is selected.
Double-click any class or member in the class browser, and Xcode jumps to its declaration in the source code.
In the class diagram, Right/Control+click on a node, as shown in Figure 14-12, and choose one of the commands:
These same three commands can be found in the Design
If a class or method appears in the API documentation, a small "book" icon appears next to its name in the browser. Clicking the book icon jumps to its documentation, and is the same as choosing the Design
"Editing" a class diagram is limited to customizing its appearance. As mentioned at the beginning of this chapter, you can't alter the definition of a class in a class model. Class modeling is strictly a visualization tool. Any changes you make will be (mostly) cosmetic. That said, you can alter the layout and appearance of the class diagram significantly, which can profoundly influence its effectiveness as a programming aid.
The main point of class diagrams is to visually represent the relationship between classes. Creating a pleasing and readable distribution of class nodes is, therefore, paramount to creating a useful class model. Xcode provides a variety of tools and techniques by which you can reshape a class diagram. The inheritance lines between class nodes are permanent fixtures and will follow the nodes as you reposition them. In fact, organizing the diagram such that all of the inheritance lines are visible and unambiguous will be your biggest challenge.
You can move nodes individually, or in groups, by selecting and dragging them to a new position. You can also use the arrow keys on the keyboard to move selected nodes.
A variety of alignment commands are found in the Design
Xcode provides two algorithms for automatically rearranging class nodes: hierarchical and force-directed. Select the set of nodes you want laid out — or select none to rearrange them all — and choose the desired layout command from the Design
Force-directed layout tends to put progenitor classes in the middle of the diagram, with descendants radiating outward. Imagine that all of the nodes are negatively charged particles that are equally repelled by all other nodes. Imagine that the lines connecting the nodes are elastic bands. Now, pick up the root nodes of the model and let the remaining nodes hang like a mobile. This is, approximately, the effect of force-directed layout. The diagram in Figure 14-13 is the same diagram shown in Figure 14-12, reorganized using force-directed layout.
Hierarchical layout is the most predictable and produces extremely easy-to-see relationships, but it can produce unwieldy results for large collections of classes. Force-directed layout produces compact graphs, but they are often unintuitive. The release notes for Xcode also warn that the algorithm used to generate force-directed layouts is "unbounded," meaning that it can take an indeterminate amount of CPU time to compute the layout of a large and complex diagram.
Xcode uses hierarchical automatic layout when a model is first created, and whenever the tracking for the model is changed. Automatic layout uses the current size of each node, and tries to create layouts such that nodes do not overlap. Locked nodes (see the "Locking Nodes" section) can interfere with this goal.
You can resize nodes using the resize "handles" that appear on the edges of the node when it is selected. Choose the Design
You can also set the height or width of multiple nodes so that they are all identical. Begin by selecting a prototype node. Select additional nodes by holding down the Shift key. The Size
Locking a node prevents it from being moved or resized. To lock or unlock a node, or nodes, use the Lock and Unlock commands in the Design
As an aid to positioning and sizing nodes, Xcode provides an optional grid. The grid is drawn in light gray behind the diagram, as shown in Figure 14-15.
When you're dragging nodes around, their position will normally "snap" to the nearest grid line. To enable or disable grid snap, choose the Design
Use the Design
A class diagram occupies a series of pages. Like a WYSIWYG word processor or spreadsheet, Xcode extends the graph area in page increments to accommodate the size of the diagram. Drag a node off the edge of the page, and a new page appears. A solid gray line indicates the boundary between pages. If you plan to print a diagram, you can use the page guides to ensure that nodes don't straddle two or more pages. If they are unimportant, the page guides can be hidden using the Design
The size of a page is controlled using the File
You can add or remove classes to and from a class model at any time. Click the diagram background, so that no nodes are selected, and then choose the File
Warning
Changing the tracking may add, remove, or replace existing nodes. This may cause customized diagrams to lose some of their customization. At the very least, any change will perform an automatic hierarchical layout, undoing any hand-arranged node positions. Save your document before changing your document's tracking — or better yet, take a snapshot or check it into source control first.
To add new sources, click the + button. This presents the sheet shown in Figure 14-16. Select the additional sources you want added to the model and click the Add Tracking button.
Warning
In its current incarnation, Xcode occasionally exhibits problems constructing class models. The symptom is missing inheritance between classes, protocols, or categories. If this happens, try removing the subclass and adding it back to the model following the classes and other nodes it inherits from. If that doesn't work, create a new, empty, model. Add classes in batches, starting with the superclasses, in such a way that you never add a class unless all of the superclasses and interfaces or protocols from which it inherits are already in the model. An easy way of accomplishing this is to keep the Class Browser window visible behind the diagram's Info window. That way, you can easily refer to the hierarchical arrangement of classes as you add them to the model.
Beyond altering its appearance, the only real content that can be added to a class diagram is an annotation node. Create annotation nodes by dragging out a rectangle using the Note tool, or by choosing the Design
The content of the node is free-formed text. Double-click the node to enter text edit mode. All of the typographical formatting features in the Edit
Annotation nodes can be connected to any number of other regular nodes, but not another annotation node. To connect an annotation node to a class node, use the Line tool to drag out a line between the two nodes. To remove a connection or an annotation node, select the line or node and press the Delete key or choose Edit
You can customize the text color, font, size, and style of nodes in the Appearance tab of the Info window. Choose File
Figure 14-18 shows the Appearance tab. The three categories — Name, Property, and Operation — address the three compartments of each node. Changing the color changes the color of the text. Changing the font, by clicking the Set button to the right of each sample, allows you to change the font face, style, and size of the text of each compartment.
You can change the background color used in the title to distinguish between different types of nodes — in a roundabout way. Drop a color from any color source onto a node to change its background color. Probably the easiest way to get a color source is to choose Edit
One of the primary uses of a class diagram is to maintain a high-level vision of class relationships — but sometimes there can be so many classes, class members, protocols, and categories that its essence is obscured by the details. You can regain some perspective by selectively hiding superfluous classes and members. You can do this on a per-class basis or automate it using rules.
You might want to hide classes or certain members of classes for many reasons:
Private or protected members that shouldn't be exposed
Internal utility or helper classes
Base class methods, like
-(NSUInteger)hash, that don't add anything significant to the description of the classesUnrelated or superfluous classes that happen to be defined in the same file as important classes
Categories that are unrelated or are used to hide private methods
Selectively hiding classes and class elements lets you pair down the diagram to exactly the detail you want to see. For example, an Objective-C class that can be archived probably implements initWithCoder: and encodeWithCoder:. Having these methods listed in every single class node really doesn't impart any useful information.
Why you would want to hide elements also depends a lot on your goals. If you're using a class model as an aide to developing your code, you'll probably want to see all of the private and protected members. If your intent is to provide a class model to other developers as a means of documenting how your classes relate and their public functionality, private and protected variables probably shouldn't be visible.
You can individually control the visibility of classes, protocols, categories, and packages. Or, you can create rules to determine which classes are visible automatically. You can also create rules to determine the visibility of properties and operations; those can't be set individually.
Start by manually setting the visibility of classes. To set the visibility of one or more classes manually:
Select a node or nodes in the diagram, or select one or more classes in the class list.
In the details pane of the browser (upper right), set the visibility of the class or classes to:
Hide per Filter
Always Show
Always Hide
Choosing Always Show or Always Hide fixes the visibility of the class in the diagram.
Selecting the Hide per Filter option shows, or hides, the class based on the model's classes filter. When this option is selected, a line of text below the control indicates the visibility of the class based on the filter. There is also a Hidden column available in the class list of the browser. Right/Control+click the class column titles and reveal the Hidden column in the table. Click the box in the row of each class to selectively hide (checked), show (unchecked), or filter it (indeterminate).
You can create class, property, and operation filters in the General tab of the diagram's Info window. Make sure no nodes are selected, and then choose File
To enable a filter, check the box next to the desired filter. If disabled (or the filter rule is left empty), the filter will not hide any nodes in the diagram.
If you're conversant in Mac OS X's predicate language, you can edit the predicate statement directly in the text field. If you're like me and need some help constructing the condition statement, click the Edit Filter button. Xcode presents a predicate editor, as shown in Figure 14-21.
The predicate editor allows you to graphically create arbitrarily complex conditional statements. The predicate editor is described in more detail in Chapter 15, but here's the short version.
An expression is built from basic conditionals. A condition consists of three parts: variable, operator, and value. Variables are properties of each node or member in the class model, and the set of variables is fixed. For properties and operations, the variables are Name, Visibility, Type, and Static. For classes, the variables are Name, Kind, Superclass, Language, and Project Member. These variables are described in the following table:
VARIABLE | DESCRIPTION |
|---|---|
Name | The class or member's name. |
Kind | The type of the class node in the diagram: Class, Protocol, Interface, or Category. |
Superclass | The name of the class that the class or category extends. |
Language | The language in which the class was defined: C++, Java, or Objective-C. |
Project Member | This value will be Yes if the class is defined in the project. |
Visibility | The visibility or scope of the property or operation: Public, Package, Protected, or Private. |
Type | The type of the variable. |
Static | This value will be Yes if the property or operation is a static or class member. |
To configure a conditional, select the variable from the left side and an operation from the middle, and then enter a value or a select a constant on the right side.
You can insert a new Boolean operator into the expression by choosing the Add AND or Add OR item in either a variable or Boolean operator menu. Adding a Boolean operator makes the entire subexpression one term in a new Boolean operator clause. Each Boolean operator logically combines the results of two or more subexpressions. You can add or remove subexpressions to or from a Boolean operator using the round plus and minus buttons on the right.
To remove a Boolean operator, remove all but one of its subexpressions.
You can negate a conditional or Boolean operator by selecting the Add NOT item. This inserts a negation operator, which you can remove again by choosing Remove in its menu.
Figure 14-22, 14-23, and 14-24 present a practical example that uses three predicate formulas to filter a class diagram. The goal is to hide much of the minutia — simple framework classes, common methods, private instance variables, and so on — that would otherwise clutter the diagram.
The Hide Classes rule, shown in Figure 14-22, hides the NSObject base class and every immediate subclass of NSObject that is not defined in the current project.
The Hide Properties rule, shown in Figure 14-23, hides all properties that are private or whose name begins with an underscore (_) character.
The Hide Operations rule, shown in Figure 14-24, hides the following methods in every class:
-dealloc-compare:-descriptionAny method that starts with an underscore character
Any method whose name ends in
WithZone:
Class modeling is a powerful analysis tool. You can use it to understand the structure of someone else's code, or classes that you haven't visited in a while. Because class models instantly reflect changes in your code, class modeling is a great tool for watching as your code develops and is a powerful aid when it comes time to reorganizing a set of classes. Class model annotations are a convenient way of highlighting key concepts and communicating them to other developers. Class and member filtering lets you tailor how much detail is revealed, keeping the focus on the important aspects of the class model.
In this chapter, you've seen how powerful visual modeling can be. In the previous chapter, you saw how easy and efficient visual editing of run time objects can be. The next chapter combines these two technologies, allowing you to visually design your data model objects.