14 Class Modeling WHAT'S IN THIS CHAPTER? Graphically modeling classes Learning the basics of the Xcode modeling tools Customizing diagrams and fi ltering 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 refl ects, any changes made to your source fi les. 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. ➤ ➤ ➤ c14.indd 285c14.indd 285 1/21/10 3:41:30 PM1/21/10 3:41:30 PM Download at getcoolebook.com 286 ❘ CHAPTER 14 CLASS MODELING 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. ➤ ➤ ➤ ➤ ➤ FIGURE 14 - 1 c14.indd 286c14.indd 286 1/21/10 3:41:33 PM1/21/10 3:41:33 PM Download at getcoolebook.com Creating a Class Model ❘ 287 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 defi nitely 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. CREATING A CLASS MODEL A class model is stored in a class model document. The documents themselves are extremely lightweight, containing little more than a list of source fi les. Think of a class model document as just another “ view ” into your project. 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. FIGURE 14 - 2 c14.indd 287c14.indd 287 1/21/10 3:41:33 PM1/21/10 3:41:33 PM Download at getcoolebook.com 288 ❘ CHAPTER 14 CLASS MODELING Creating a New Class Model Document You add a class model document to your project much as you would any new source fi le: 1. Choose File ➪ New File. 2. Choose the Class Model document template. 3. Give the class model document a name. 4. Ignore the project targets. 5. Select the source fi les and source groups that you want to model. You begin by using the File ➪ New File (or any equivalent) command. If you have any questions about that process, see the “ Creating New Source Files ” section in Chapter 5. Next, select the Class Model document type from the list of fi le templates, as shown in Figure 14 - 3. You will fi nd 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 fi le; don ’ t check any targets in the list. Class model documents are for reference only; they shouldn ’ t be included in any build targets. FIGURE 14 - 3 After naming your new document, Xcode presents the model ’ s fi le tracking dialog box, shown in Figure 14 - 4. c14.indd 288c14.indd 288 1/21/10 3:41:44 PM1/21/10 3:41:44 PM Download at getcoolebook.com Creating a Class Model ❘ 289 On the left are all the source groups and fi les defi ned in the project. On the right is the list of fi les or groups that will be tracked by the new model. Select the source fi les, 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 fi le 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 fi les 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 fi le that you like, but the class modeler is only interested in class defi nitions. For Objective - C and C++, this will typically be the class ’ s header ( .h ) fi le. In Java, the .java fi le that defi nes the class should be added. The class modeler creates a model using every class defi nition that it fi nds in those fi les. Files that contain non - class declarations, libraries, and so on are ignored. There ’ s no harm in adding those fi les to the model, but there ’ s no point either. It also makes no difference how many source fi les defi ne 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 fi le contained in that group. If the contents of the group change, so do the fi les in the model. You can add both a source fi le and the group that contains that source fi le 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. ➤ ➤ FIGURE 14 - 4 c14.indd 289c14.indd 289 1/21/10 3:41:45 PM1/21/10 3:41:45 PM Download at getcoolebook.com 290 ❘ CHAPTER 14 CLASS MODELING Frameworks can be added. A framework is, logically, a source group that contains a number of header fi les. All of the classes defi ned in those headers will be added to the model. Don ’ t fret about what fi les 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 defi ne scores, if not hundreds, of classes. This can make for an unwieldy model. If you want to include classes defi ned in frameworks, add the specifi c 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 ➪ Hide/ Show Model Browser (Control+Command+B) command quickly collapses or expands the browser portion of the pane. Creating a Quick Model 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: 1. Select one or more source fi les or groups in an open project. You can do this in the project source group or in the details list. 2. Choose Design ➪ Class Model ➪ Quick Model. The Design ➪ Class Model ➪ Quick Model command immediately constructs a class model from the selected sources. The new model window is not associated with a class model document and nothing is added to your project. 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 modifi cations 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 fi le as is. The document is a temporary fi le, so just saving the fi le doesn ’ t preserve it — it will still be deleted once you ’ re fi nished with the diagram. If you later decide you want to save the quick model as a permanent class model document, choose the File ➪ Save As command, and save the class model document in your project ’ s folder. You will then need to add the new document fi le to your project. See Chapter 5 for one of the many ways of adding a source fi le to your project. ➤ ➤ c14.indd 290c14.indd 290 1/21/10 3:41:46 PM1/21/10 3:41:46 PM Download at getcoolebook.com CLASS MODEL BROWSER 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. FIGURE 14 - 5 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: Properties refer to instance or member variables of a class. Operations refer to class methods, functions, or messages. Protocols refer to either Objective - C protocols or Java interfaces. Categories are Objective - C categories. Packages are Java packages. Not all modeling concepts apply to all languages. Categories only appear when modeling Objective - C classes. 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. ➤ ➤ ➤ ➤ ➤ Class Model Browser ❘ 291 c14.indd 291c14.indd 291 1/21/10 3:41:46 PM1/21/10 3:41:46 PM Download at getcoolebook.com . the data modeling tools. ➤ ➤ ➤ ➤ ➤ FIGURE 14 - 1 c14.indd 286c14.indd 286 1/21/10 3: 41 :33 PM1/21/10 3: 41 :33 PM Download at getcoolebook.com Creating a Class Model ❘ 287 The data modeling tools,. that contains the classes it models. FIGURE 14 - 2 c14.indd 287c14.indd 287 1/21/10 3: 41 :33 PM1/21/10 3: 41 :33 PM Download at getcoolebook.com 288 ❘ CHAPTER 14 CLASS MODELING Creating a New Class. document to your project much as you would any new source fi le: 1. Choose File ➪ New File. 2. Choose the Class Model document template. 3. Give the class model document a name. 4. Ignore the project