Part II crams a great deal of information about Cocoa into a relatively small space. In this chapter we take a look at how this information is organized and how to read the quick-reference entries.
Chapter 13 and Chapter 15 cover the classes of the Foundation and Application Kit frameworks. Chapter 14 and Chapter 16 contain quick-reference entries for the protocols of these two frameworks. Within these four chapters quick-reference entries are arranged alphabetically. Finally, the Method Index contains an alphabetical listing of every method in the Foundation framework and Application Kit. Each method name in the index has a list of classes that implement that method. Here's how to read a quick reference entry.
Following the title of each quick-reference entry is a brief description of the class or protocol. Descriptions may be as short as a couple of lines, or as long as several paragraphs of text.
Every class in the quick reference has a figure illustrating the hierarchy of the class, and any protocols adopted by the class or its ancestors. In the hierarchy figure classes appear as rectangles containing the name of the class, and formal Objective-C protocols appear as rectangles with rounded corners. The root object of each hierarchy (either NSObject or NSProxy ) is at the left of the figure, with subclasses extending horizontally to the right. Subclasses are connected by a solid line, which denotes an inheritance relationship. The protocols adopted by any class in the hierarchy appear vertically beneath the class. Note that the hierarchy only shows the superclasses of a class. Subclasses of the class, if any exist, are listed after the class synopsis in the "Subclasses" cross-reference.
The synopsis is the most important part of the class reference, providing a list of the methods that are part of the class interface. Additionally, the class synopsis provides a list of methods that a delegate object might implement, as well as a list of notifications that the class can post. Each class synopsis begins with the class interface declaration as it would appear in the class header file. The interface declaration displays the class name, superclass name, and any protocols that the class adopts. For example, NSDate has the following interface declaration in its class synopsis:
@interface NSDate : NSObject <NSCoding, NSCopying>
Following the interface declaration is a list of methods that are a part of the class's interface. This includes all methods that may be declared in a category of a method. The class interface method list is ended with @end . Following the class method list is a list of methods a delegate object may implement, and a list of notifications that instances of the class may post to the notification center.
Protocol synopses take on two forms, depending on whether the protocol is formal or informal. Formal protocols enclose the method list as follows:
@protocol ProtocolName // Methods @end
While an informal protocol synopsis appears as a category interface declaration:
@interface NSObject (ProtocolName) // Methods @end
Methods in the class synopsis are broken up into several optional categories, within which the methods are listed alphabetically. A class may have groups of convenience constructors, initializers, and property accessor methods, in addition to class and instance methods. Additionally, the synopsis lists methods a class expects its delegate to respond to, as well as notifications posted by instances of the class. Method groups are separated in the synopsis with C comments, such as // Initializers , // Class Methods , and // Notifications . Protocol synopses group methods either as instance or class methods. Not every class has methods that fall under each of these categorizes. The various categories are as follows (in the same order they would appear in the class synopsis):
Lists any convenience constructors of a class. Convenience constructors are class methods that combine object allocation and initialization into one step. By convention, objects returned by convenience constructor have already been sent an autorelease method, and will be released at the end of the event-loop. If you wish to use an object for a longer period of time you must send a retain message to the returned object. Generally speaking, convenience constructors very nearly mirror the initializers of a class. A class may have other factory methods listed in the Class Methods grouping in addition to these convenience constructors.
This grouping lists all of the initializers of a class, which is any method that begins with init . When instantiating an class with alloc , you must initialize the new object with one of the class's initializers before it is used. Objects created and initialized in this way have a reference count of 1, unlike objects returned by convenience constructors, which have been autoreleased before they are returned.
This section lists methods that are used to access the properties of a class. Any instance method that begins with set... is listed here; these are used to set the property indicated in the method name. Conventionally, methods used to access properties are named after the property. For example, NSBezierPath has the method setLineWidth: to set the line width of the path. The associated get-property instance method is lineWidth the name of the property. Accessor methods are listed alphabetically by the property name, so that the "set" methods appear grouped with their respective property query methods.
This section of the synopsis lists all class methods that are not constructors or accessor methods.
This section lists all instance methods that are not initializers or accessor methods.
This section groups methods that implement the same protocol. For each protocol adopted by the class, there is one subgroup of methods.
This section lists any methods a delegate of the class may optionally implement. Delegate methods are not part of the class interface; generally, they are declared as a category of the root class, NSObject .
This section lists the symbolic names of any notification that the class may post during its lifetime.