Introduction

Book Organization

This book contains sections for each kit. Each section contains chapters describing the kit's classes, protocols, functions, and types and constants. The following outline shows the book organization:

• Application Kit

  · Classes

  · Protocols

  · Functions

  · Types and Constants

• Foundation Kit

  · Classes

  · Protocols

  · Functions

  · Types and Constants

• Display PostScript System

  · Classes

  · Protocols

  · Display PostScript Operators

  · Client Library Functions

  · Single-Operator Functions

  · Types and Constants

• Sound Kit

  · Classes

  · Types and Constants

Chapter Organization

The following sections desribe each chapters organization, and briefly discusses:

• Inheritance Hierarchies
• Delegates
• Formal and Informal Protocols

Classes

Each class chapter contains a kit's class descriptions listed alphabetically. Each class description starts with a table listing the class's inheritance hierarchy, protocol conformance, and header file containing the class interface. For example:

Inherits From:	NSCell : NSObject
Conforms To:	NSCoding, NSCopying (NSCell), NSObject (NSObject)
Declared In:	AppKit/NSActionCell.h

The first line in this example specifies a class's inheritance hierarchy, in this case NSActionCell's inheritance hierarchy. It specifies that NSActionCell inherits from NSCell, and that NSCell inherits from NSObject. NSCell is called NSActionCell's superclass. NSObject is the root class of almost all OpenStep inheritance hierarchies.

The second line in the previous example specifies the formal protocols that the class conforms to. These include both protocols the class adopts and those it inherits from other adopting classes. If inherited, the name of the adopting class in given in parentheses.

The third line in the previous example specifies the header file that declares the class interface.

After a general description of the class, the class's methods are listed in functional groups. For example, here is NSScroller's list:

Activity	Class Method
Laying out the NSScroller	+ scrollerWidth - arrowsPosition - checkSpaceForParts - rectForPart: - setArrowsPosition: - usableParts
Setting the NSScroller's values	- knobProportion - setFloatValue:knobProportion:
Displaying	- drawArrow:highlight: - drawKnob - drawParts - highlight:
Handling events	- hitPart - testPart: - trackKnob: - trackScrollButtons:

This list is followed by class methods in alphabetical order, then instance methods in alphabetical order. Each method's prototype is given, followed by a brief description.

Some classes have separate sections with titles such as "Methods Implemented by the Superview", "Methods Implemented by ", "Methods Implemented by the Owner." These are informal protocols. They document methods that can or must be implemented to receive messages on behalf of instances of the class.

Methods Implemented by the Delegate

If the class describes a delegate, the delegate methods are listed last. These are not methods defined in the class; they are methods that you can define to respond to messages sent from instances of the class. If you define a delegate method, the delegate will receive automatic messages to perform that delegate method at the appropriate time. For example, if you define a windowDidBecomeKey: method for an NSWindow object's delegate, the delegate will receive windowDidBecomeKey: messages whenever the

NSWindow object becomes the key window. Messages are sent to an object's delegate only if you define a method that can respond to the message within the delegate.

In essence, this section documents an informal protocol. But because these methods are so closely tied to the behavior of a particular class, they're documented with the class rather than in the Protocols chapters.

Protocols

The protocol chapters describe OpenStep's formal and informal protocols. Formal protocols are declared using the @protocol compiler directive. They can be formally adopted and implemented by a class and tested by sending an object a conformsToProtocol: message.

Some formal protocols are adopted and implemented by OpenStep classes. However, many formal protocols are declared by a kit, but not implemented by it. These formal protocols list methods that you can implement to respond to kit-generated messages.

A few formal protocols are implemented by a kit, but not by a class that's part of the OpenStep API. Rather, the protocol is implemented by an anonymous object that the kit supplies. The protocol lets you know what messages you can send to the object.

Like formal protocols, informal protocols declare a list of methods that others are invited to implement. If an informal protocol is closely associated with one particular class, for example, the list of methods implemented by the delegate, it's documented in the class description.

---

Note - Informal protocols associated with more than one class, or not associated with any particular class, are documented in the Protocols chapters.

---

Protocol information is organized into many of the same sections as described previously for a class specification. But protocols are not classes and therefore differ somewhat in the kind of information provided.

Each formal protocol description starts with a table listing the classes that adopt the protocol, and the header file containing the protocol description. For example:

Adopted By:	NSText
Declared In:	AppKit/NSSpellProtocol.h

Many protocols declare methods that applications must implement and so are not adopted by any OpenStep classes. Some protocols are implemented by anonymous objects (instances of an unknown class); the protocol is the only information available about what messages the object can respond to. Protocols that have an implementation available through an anonymous object generally don't have to be reimplemented by other classes.

An informal protocol cannot be formally adopted by a class and it cannot formally incorporate another protocol. So its description begins with information about the category where it's declared:

Category Of:	NSObject
Declared In:	AppKit/NSDragging.h

Informal protocols are typically declared as categories of the NSObject class. This gives them the widest possible scope. If the protocol includes enough methods to warrant it, they're divided by type and presented just as the methods of a class are.

Functions

Within the function chapters related functions are grouped together under a heading that describes that groups similarities. Here is a partial list of these headings from the Application Kit:

• Rectangle Drawing Functions
• Color Functions
• Text Functions
• Array Allocation Functions
• Imaging Functions

Each function, its arguments, and its return value are briefly described in an accompanying comment.

Types and Constants

Within these chapters related defined types, enumeration constants, symbolic constants, structures, and global variables are grouped together under a heading that describes where the type or constant is used. Here is a partial list of these headings from the Application Kit:

• Application
• Box
• Buttons
• Cells and Button Cells
• Color

A short description accompanies each group.

Further Reading

In addition to this document, the OpenStep documentation set consists of:

• QuickStart to Using the OpenStep Desktop--for beginning end-users. A minimal set of instructions to get you started running OpenStep.
• Using the OpenStep Desktop--the complete end-user guide.
• User Interface Guidelines--for application developers; identifies the objects supplied in the Application Kit, describes their appearances and behaviors, and the kinds of application-specific behaviors that developers must implement. Includes detailed discussions of the mouse and keyboard operations performed by users to operate the interface. Provides detailed guidelines for such things as choosing keyboard shortcut characters. Also describes the behaviors that should be implemented for custom objects.
• OpenStep Development Tools--describes the essential tools for developing an OpenStep application: the Project Builder, Interface Builder, Header Viewer, Icon Builder, Edit applications, and the distributed Debugger. The manual also included chapters on the Objective C language and the NSObject class.