In the previous chapter, you saw how to search the Code Sense index for symbols and definitions. The class browser provides a much more structured way of exploring your project's Code Sense database; it builds a structured summary of your project's classes that describes their methods, instance variables, and inheritance. You can open it at any time, and it's always up-to-date — or at least as current as your Code Sense index. It's one of my favorite development tools, and I use it incessantly to review classes, untangle inheritance, and jump to their definitions.
Chapter 14 shows you some additional high-level tools for analyzing your classes graphically. The best part about the class browser is that it's free. You don't have to do anything special to your project beyond turning on Code Sense. Once the Code Sense index for your project is built, the class browser is ready to go.
Choose the Project
The class browser's toolbar typically includes the Option Set control and the Configure Options button. The Option Set menu and Configure Options button work like the Project Find window's batch find options set, described in Chapter 8. The pop-up menu lets you select the named set of browser options, and the Configure Options button allows you to alter the options in a set or create new sets. This chapter covers option sets and the browser options shortly.
The class browser is broadly divided into three panes. The pane on the left is the class list. This lists all classes, interfaces, and protocols defined in the project. These can be organized in a hierarchy — a superclass becomes a group that contains all of the subclasses that inherit it. Expand or collapse groups using the triangle to the left of the class name. Hold down the Option key to recursively collapse or expand all subclasses. Alternatively, you can list the classes in alphabetical order. Java class names include the package so that similarly named classes in different packages can be distinguished easily. Classes defined in your project appear blue. Classes defined in frameworks are black.
Selecting a class in the list displays the member elements of that class in the details pane on the right, and the source that defines the class in the editor pane below it. The details pane lists the member elements, grouped by type. Members defined in the class are black, and inherited members (if shown) are grey. Member functions and methods are listed first, followed by variables. Class (static) members are listed before instance members. You can reorganize and resize the table columns by dragging in the column headers, but you cannot change the sorting order.
Selecting any member in the details list displays its declaration in the editor pane below it. Double-clicking either the class name or a member jumps to that location in a new editor window.
If online documentation is available for a class, a small book icon appears to the right of the class name. Clicking the book icon jumps to that class's documentation in the help viewer, as shown in Figure 9-2.
Normally, there is one class browser window for each project. It is possible to open multiple class browser windows using the New Class Browser button in the toolbar of the class browser window itself — not to be confused with the Class Browser button that appears on most other windows. This button isn't in the default set of toolbar buttons; to use it you must add it to your toolbar. See the "Toolbars" section of Chapter 3 if you're unsure how.
Figure 9-3 shows the New Class Browser button. Multiple browser windows permit you to view different aspects of your classes simultaneously, so consider adding the New Class Browser button to your class browser's toolbar (View
The class browser comes preconfigured with four option sets. These four sets of options display just those classes defined in the project or all classes visible to the project. The classes can be organized in a hierarchy or listed alphabetically irrespective of relationships.
Click the Configure Options button to edit the configuration of a set. This displays the class browser options configuration sheet, shown in Figure 9-4.
Select the set of options to edit using the pop-up menu at the top of the sheet. You can edit the predefined sets, but avoid making any changes that run counter to their descriptive names. Changing the Hierarchy, Project Classes set to display only framework classes in a flat list is guaranteed to cause confusion. If you want to make significantly different sets of browser options, create new sets using the Add button. With the Delete button, you can delete sets you don't care to use.
Warning
Like the Project Find window, the class browser option sets are shared among all projects. Make changes to them judiciously.
The left side of the sheet contains the Class List Display Settings, which consist of four options that determine which classes are included in the class browser, and how those classes are organized in the class list.
The first option has two choices: Hierarchical Outline groups subclasses within their superclass in a tree, and Flat List simply sorts all of the class names alphabetically.
The next option has three possible settings that determine what classes are included in the list. Show Project and Framework Entries includes all classes and members defined in the project source and any classes defined in any referenced frameworks. Show Project Entries Only excludes classes defined in the frameworks, and Show Framework Entries Only lists only those classes defined in the frameworks. When you use the Hierarchical Outline display, an exception is made for superclasses. Superclasses of a class, regardless of where they are defined, are always included in the hierarchical display as the parents of that class. This also affects the display of inherited class members. If a project class inherits a method or variable from a framework class, and Show Project Entries Only is selected, those inherited members are not listed.
The third option also has three possible settings: Show Classes & Protocols/Interface, Show Classes Only, and Show Protocols/Interfaces Only. This control determines whether only the class definitions, only protocols/interface definitions, or both are included in the class list. If both are included, protocols and interfaces are grouped together at the bottom of the class list. In the hierarchical view, they are listed under the title Protocols/Interfaces. In the list view, each is prefixed with the "Prot:" text.
The last option applies only to Objective-C and determines how Objective-C categories are organized in the class list. For those not familiar with Objective-C, a category is a way of defining a set of methods for a class where the definition and implementation of those methods is completely outside the definition of the class itself. In other words, it's a way of "attaching" methods to a class without subclassing, just as if those methods had been defined in the class itself. (If the C++ and Java programmers in the audience are scratching their heads wondering how this is possible, the magic occurs at run time — all message dispatching in Objective-C is dynamic, so new method handlers can be added to any class during program execution.) The problem is that categories don't fit in the neat hierarchy of classes and interfaces, because they are neither.
The As Subclass setting treats the category as if it were a subclass in the hierarchy. The category appears as a subclass of the attached class with a "Cat:" prefix. This makes it clear which class the category was written for, but is somewhat misleading because the category is not a subclass. The methods defined by the category are defined in that class and inherited by any subclasses — neither of which will be reflected in the class browser. If you're looking for the methods in a class, you have to browse not only that class but all of its categories, and any categories of its superclasses as well.
The second alternative is the As Subclasses for Root Classes setting. This treats a category as though it was a subclass of the root object of the class it is attached to (almost invariably NSObject). Although this is also a fabrication, it has the advantage that categories are easy to find because they end up grouped together at the end of NSObject's subclasses. More important, the methods defined by a category correctly appear in the attached class and any of its subclasses. This is probably the most useful setting.
The final choice, Always Merged into Class, is the most accurate in that it merges the category methods into each class just as though those methods had been defined in that class. The categories themselves are not shown anywhere in the class list. To discover which methods of a class are defined by a category you must refer to the source declaration of each method.
On the right are three controls that influence the amount of detail presented about each class:
The Show Inherited Members option causes the members of a class to include all inherited members. Inherited members are displayed in grey, and the members defined or overridden in the class are black.
The Show Methods & Data, Show Methods Only, and Show Data Only options display all members of the class, or only methods, or only instance variables, respectively.
The Show Instance & Class, Show Instance Only, and Show Class Only options further refine the class details such that it lists all class members, or only instance members, or only class members. The term class is really an Objective-C term, where it refers to messages that can be sent to the Class object, as opposed to regular messages that would be sent to an instance of that class. In C++ and Java, class refers to static members and variables. Note that so-called static nested classes are regular classes and will appear in the browser hierarchy within their superclass.
Xcode provides an internal editing action (Reveal in Class Browser) that jumps from the currently selected symbol in the editor to its entry in the class browser. In Xcode's default key bindings, this action (sadly) isn't bound to any keyboard shortcut. If you find the Reveal in Class Browser shortcut useful, add a key binding for the action in the Key Bindings preferences. Key bindings are explained in Chapter 23.
The class browser is a powerful tool for illuminating the class structure of any project. Learning to use it effectively will help you understand and navigate your code. In some ways, it is both a search tool and a documentation tool. Object-oriented programs were once said to be self-documenting. Although this is rarely true, being able to see the class structure of a project can provide insights into its organization that code comments and documentation often fail to provide.
With the ability to find text, symbols, and class information, you're ready to start making serious changes to your code. The next two chapters help you make those changes intelligently and safely.