IB

Characteristic	Description
Adopted By:	no OpenStep classes
Declared In:	include/InterfaceBuilder/IBApplicationAdditions.h

Protocol Description

Interface Builder's subclass of the NSApplication class conforms to the IB protocol. Thus, objects in your custom palette can interact with Interface Builder's main module by sending messages (corresponding to the methods in this protocol) to the NSApplication object NSApp. for your application.

Method Types

Activity	Class Methods
Accessing the document	- activeDocument
Accessing the selection owner	- selectionOwner
Querying the mode	- isTestingInterface

Instance Methods

activeDocument

- (id<IBDocuments>)activeDocument

Returns the active document, as represented by an object that conforms to the IBDocuments protocol. The active document is represented by the nib file window of the document containing the selection.

isTestingInterface

- (BOOL)isTestingInterface

Returns YES if Interface Builder is in Test mode.

selectionOwner

- (id<IBSelectionOwners>)selectionOwner

Returns the owner of the currently selected object or nil if no object is selected.

IBConnectors

Characteristic	Description
Adopted By:	no OpenStep classes
Declared In:	include/InterfaceBuilder/IBConnectors.h

Protocol Description

This protocol declares the programmatic interface of connector objects. Connectors are designed to store information about connections between objects in a nib document. For example, the private class that Interface Builder uses to store information about outlet connections conforms to this protocol and adds a method to store the name of the outlet. Connector objects are archived in the nib file.

When an application loads a nib file, the connector objects in the nib file are unarchived and are sent the establishConnection message. In response to this message, the connector establishes its type of connection between the source and destination. For example, Interface Builder's outlet connector sets the named outlet to the destination object.

Your Connection inspector must set the source and destination in each of its connectors (for example, with setSource: and setDestination: methods). The protocol does not include methods to set these outlets, only to query them.

Method Types

Activity	Class Methods
Establishing a connection	- establishConnection
Labeling a connection	- label
Querying outlets	- destination - source - nibInstantiate
Updating a connector	- replaceObject:withObject

Instance Methods

destination

- (id)destination

Implement to return the object that is the destination of the connection. See also - source.

establishConnection

- (void)establishConnection

Implement to connect the source and destination objects. Interface Builder sends this message to each connector object after all objects have been unarchived from the nib file.

label

- (NSString *)label

Implement to label the connection when it is displayed in the nib file window in outline mode.

nibInstantiate

- (id)nibInstantiate

Implement to verify the identities of the connector's source and destination objects.

Interface Builder sends a nibInstantiate message to allow a connector object to verify that its source and destination instance variables point to the intended objects. For example, consider the case in which a user puts an NSCustomView in a window and then reassigns the NSCustomView's class to MyView. The MyView class has a textfield outlet that the user connects to a neighboring NSTextField object. This action causes Interface Builder to create a connector object and set its destination to the NSTextField and its source to the NSCustomView. The source cannot be set to the MyView object since that class does not exist in InterfaceBuilder, which is why the NSCustomView was used.

When the resulting nib file is loaded in the finished application, the connector object is unarchived and sent a nibInstantiate message. At this point the connector must reset its source instance variable from the NSCustomView object to the MyView object.

The Application Kit, in a category of NSObject, provides a default implementation of nibInstantiate. This implementation returns self. Consequently, all objects can respond to a nibInstantiate message. Your connector, therefore, should minimally implement nibInstantiate messages to transmit this message to its source and destination objects. For example, assuming the outlets are named theSource and theDestination, the implementation is as follows:

- (id)nibInstantiate
{
    theSource = [theSource nibInstantiate];
    theDestination = [theDestination nibInstantiate];
    return self;
}

This allows the source and destination objects to return the ids of the intended objects.

replaceObject:withObject:

- (void)replaceObject:(id)oldObject withObject:(id)newObject

Implement to update a connector by replacing its old source or destination object (oldObject) with a new object (newObject). This is used by Interface Builder, for example, when a user drags an NSButton object into an NSMatrix of NSButtonCells. Assuming that the NSButton was connected, the connection information must be updated to reflect the replacement of the NSButton by an NSButtonCell. Interface Builder accomplishes this by sending the appropriate connector object a replaceObject:withObject: message with the NSButton as oldObject and the NSButtonCell as newObject.

source

- (id)source

Implement to return the object that is the source of the connection. See also - destination.

IBDocuments

Characteristic	Description
Adopted By:	no OpenStep classes
Declared In:	include/InterfaceBuilder/IBDocuments.h

Protocol Description

IBDocuments is the protocol to use to communicate with Interface Builder's document object. The document object is private to Interface Builder but may be accessed by sending Interface Builder's subclass of NSApplication an activeDocument message:

theActiveDoc = [NSApp activeDocument];

The document object maintains the following components of a document:

• The object hierarchy
• The list of connectors
• The active editor

It also mediates in copy and paste operations and controls the redisplay of objects in Interface Builder.

Through the document object, you keep Interface Builder informed of changes to the data structure that you want archived in the nib file. For example, if your custom editor allows the user to add an object by dragging it into the editor's window, you must inform Interface Builder of this addition by sending the document object an attachObject:toParent: message. Interface Builder does not archive an object in the nib file unless it has been added to the object hierarchy.

---

Note - A paste operation, which uses the pasteType:fromPasteboard:parent: method, automatically updates the hierarchy.)

---

Method Types

Activity	Class Method
Managing the document	- touch - documentPath:
Managing the object hierarchy	- attachObject:toParent: - attachObjects:toParent: - detachObject - detachObjects - replaceObject:withObject: - objects: - containsObject: - parentOfObject: - copyObject:type:toPasteboard: - copyObjects:type:toPasteboard: - pasteType:fromPasteboard:parent::
Setting object names	- setName:forObject: - nameForObject: - containsObjectWithName:forParent:

Activity	Class Method
Managing connectors	- addConnector: - removeConnector: - connectorsForSource: - connectorsForSource:ofClass: - connectorsForDestination: - connectorsForDestination:ofClass
Managing editors	- openEditorForObject: - editorForObject:create: - setSelectionFromEditor: - resignSelectionForEditor: - editor:didCloseForObject:
Updating the display	- drawObject:

Instance Methods

addConnector:

- (void)addConnector:(id<IBConnectors>)connector

Adds a connector object to the list maintained by the document. (See "IBConnectors" on page D-3 for more information on connectors.) This is the message a custom connection inspector sends Interface Builder's document object to register a connection. See also - removeConnector:.

attachObject:toParent:

- (void)attachObject:(id)object toParent:(id)parent

Adds object to the document's object hierarchy by attaching it to parent. This method (and the related method attachObjects:toParent:) lets you keep the document's object hierarchy informed of changes in the objects under the control of your custom editor. See also - attachObjects:toParent:.

attachObjects:toParent:

- (void)attachObjects:(NSArray *)objects toParent:(id)parent

Adds the objects in objects to the document's object hierarchy by attaching them to parent. This method (and the related method attachObject:toParent:) lets you keep the document's object hierarchy informed of changes in the objects under the control of your custom editor. See also - attachObject:toParent:.

connectorsForDestination:

- (NSArray*)connectorsForDestination:(id)destination

Places all connector objects whose destinations are destination in an array and returns the array.

An object can be the destination of multiple connections, so the connectors information are returned in an array. Each connector in the array conforms to the IBConnectors protocol and contains the information for one connection.

Do not free the connection objects ; the array will autorelease. See also - connectorsForDestination:ofClass:, - connectorsForSource:.

connectorsForDestination:ofClass:

- (NSArray*)connectorsForDestination:(id)destination
    ofClass:(id)classObject

Places the connector objects of class classObject whose destinations are destination in an array and returns the array.

An object can be the destination of multiple connections, so the connectors are returned in an array. Each connector in the array conforms to the IBConnectors protocol and contains the information for one connection.

Do not free the connection objects ; the array will autorelease. See also - connectorsForDestination:, - connectorsForSource:.

connectorsForSource:

- (NSArray*)connectorsForSource:(id)source

Places all connector objects whose sources are source in an array and returns the array.

A source can have multiple connections, so the connectors are returned in an array. Each connector in the array conforms to the IBConnectors protocol and contains the connection information for one connection.

Do not free the connection objects ; the array will autorelease. See also - connectorsForSource:ofClass:, - connectorsForDestination:.

connectorsForSource:ofClass:

- (NSArray*)connectorsForSource:(id)source
    ofClass:(id)classObject

Places the connector objects of class classObject whose sources are source in an array and returns the array.

A source can have multiple connections, so the connectors are returned in an array. Each connector in the array conforms to the IBConnectors protocol and contains the connection information for one connection.

Do not free the connection objects ; the array will autorelease. See also - connectorsForSource:, - connectorsForDestination:.

containsObject:

- (BOOL)containsObject:(id)object

Returns YES if object is a part of the document's object hierarchy; NO otherwise. You might send a containsObject: message to the document object before attempting to open a subeditor for object.

containsObjectWithName:forParent

- (BOOL)containsObjectWithName:(NSString *)name
forParent:(id)parent

Returns YES if the document contains an object named name that has the parent parent.

copyObject:type:toPasteboard:

- (BOOL)copyObject:(id)object
type:(NSString*)type
toPasteboard:(NSPasteboard *)pasteboard

Copies object to the specified pasteboard. The type argument can be one of the following:

IBObjectPboardType
IBCellPboardType
IBMenuPboardType
IBMenuCellPboardType
IBViewPboardType
IBWindowPboardType

An editor should send the active document object a

copyObject:type:toPasteboard: or
copyObjects:type:toPasteboard: message as part of its implementation
of its copySelection method. See also
- copyObjects:type:toPasteboard:.

copyObjects:type:toPasteboard:

- (BOOL)copyObjects:(NSArray*)objects
type:(NSString*)type
toPasteboard:(NSPasteboard *)pasteboard

Copies the objects in objects to the specified pasteboard. The type argument can be one of the following:

IBObjectPboardType
IBCellPboardType
IBMenuPboardType

IBMenuCellPboardType
IBViewPboardType
IBWindowPboardType

An editor should send the document object a

copyObject:type:toPasteboard: or
copyObjects:type:toPasteboard: message as part of its implementation
of its copySelection method. See also
- copyObject:type:toPasteboard:.

detachObject:

- (void)detachObject:(id)object

Removes object from the document's object hierarchy. An editor should send the document object a detachObject: or detachObjects: message as part of its implementation of the deleteSelection method. If any connections are associated with the object, they are deleted as well. See also

- detachObjects:.

detachObjects:

- (void)detachObjects:(NSArray *)objects

Removes the objects in objects from the document's object hierarchy. An editor should send the document object a detachObject: or detachObjects: message as part of its implementation of the deleteSelection method. If any connections are associated with the object, they are deleted as well. See also - detachObject:.

documentPath

- (NSString *)documentPath

Returns the path name for the document's directory wrapper. The path is displayed as the title of Interface Builder's File window.

drawObject:

- (void)drawObject:(id)object

Redraws the selected object by opening its editor, the editor for its parent object, and so on up the object hierarchy. Each editor is also sent a resetObject: message.

editor:didCloseForObject:

- (void)editor:(id<IBEditors>)editor didCloseForObject:(id)object

Informs the document object that anEditor is no longer active. By sending this message to the document object when an editor is closed, Interface Builder's record of the active editor is kept up to date. Interface Builder itself invokes this method whenever an editor is closed because of a user action, such as the closing of a window.

editorForObject:create:

- (id<IBEditors>)editorForObject:(id)object create:(BOOL)createIt:

Returns the editor object for object. If createIt is YES and the editor has not been instantiated, it is instantiated and returned. If createIt is NO, the editor is returned only if it has already been instantiated. If createIt is NO and the editor has not been instantiated, this method returns nil.

nameForObject:

- (NString*)nameForObject:(id)object

Returns the name associated with object. See also - setName:forObject:.

objects:

- (NSArray*)objects:

Returns the objects from the document's object hierarchy in an array. The objects are not arranged in any particular order.

openEditorForObject:

- (id<IBEditors>))openEditorForObject:(id)object

Opens the editor object for object. This method ensures that editors for all the objects above object in the object hierarchy are open before opening object's editor.

parentOfObject:

- (id)parentOfObject:(id)object

Returns the object above object in the document's object hierarchy. The top object is the File's owner. Returns nil if object is the File's owner.

pasteType:fromPasteboard:parent:

- (NSArray*)pasteType:(NSString *)type
    fromPasteboard:(NSPasteboard *)pasteboard
    parent:(id)parent

Returns an array containing the objects that are in the pasteboard. The pasteboard and the type being pasted are identified by pasteboard and type.

The implementation of this method invokes attachObjects:toParent: and touch. The returned array object provides your code with access to pasted objects so you can add them to your code's data structures. The array will autorelease.

removeConnector:

- (void)removeConnector:(id<IBConnectors>)connector

Removes connector from the list of connectors maintained by the document. (See "IBConnectors" on page D-3 for more information on connectors.) A custom connection inspector sends the document object this message to break a connection.

Interface Builder does not free connector; it is your responsibility to do so. See also - addConnector:.

replaceObject:withObject:

- (void)replaceObject:(id)oldObject withObject:(id)newObject

Implement to update a connector by replacing its old source or destination object (oldObject) with a new object (newObject). For example, this is used by Interface Builder when a user Alt-drags a resize handle on an NSButton object causing the NSButton to be replaced by an NSMatrix of NSButtonCells. Assuming that the NSButton was connected, the connection information must be updated to reflect that fact that the NSButton has been replaced by an NSButtonCell. Interface Builder updates this information by sending the appropriate connector object a replaceObject:withObject: message with the NSButton as oldObject and the NSButtonCell as newObject.

resignSelectionForEditor:

- (void)resignSelectionForEditor:(id <IBEditors>)editor

Unregisters editor as the editor that owns the selection. See also - setSelectionFromEditor:.

setName:forObject:

- (BOOL)setName:(NSString*)name forObject:(id)object

Sets the name associated with object. For objects in the File window, this is the name displayed below the object's image. Except for objects in the File window, setting an object's name is generally not needed. See also

 - nameForObject:.

setSelectionFromEditor:

- (void)setSelectionFromEditor:(id<IBEditors>)editor

Registers editor as the editor that owns the selection.

When you activate an editor or change the selection, make sure you send this message to the document object to keep Interface Builder informed of the selection's owner. In this way, when the user switches from one window to another, or from one document to another, Interface Builder can inform the proper editor to display its selection. Also, Interface Builder uses the selection information to determine which inspector to display in its Inspector panel.

touch

- (void)touch

Marks the document as edited. When you deactivate an editor, the nib file window's close box displays a broken "X" to indicate the edited status.

IBEditors

Characteristic	Description
Adopted By:	no OpenStep classes
Incorporates:	IBSelectionOwners
Declared In:	include/InterfaceBuilder/IBEditors.h

Protocol Description

IBEditors, and the IBSelectionOwners protocol that it incorporates, define the required programmatic interface to an editor object in Interface Builder. When a user double-clicks on a custom object, Interface Builder instantiates the object's editor (using initWithObject:inDocument:). (Interface Builder would have previously determined the editor's class by sending the custom object a getEditorClassName message. See "NSObject Additions" on page C-11 for more information.) The editor presents its window, allowing the user to make alterations to the displayed data.

For example, assume that a custom palette provides an AddressBook object. Once instantiated in the File window, the AddressBook object can be double-clicked to activate the editor. The editor presents the user with a window that permits the entry of names and addresses. As data is entered, the editor can update the AddressBook object with the new information.

Besides letting users edit an object's state, an editor intercedes in copy and paste operations. When the user chooses the Cut or Copy command, Interface Builder sends a deleteSelection or copySelection message to the editor. The editor takes the appropriate action and then alerts Interface Builder's document object that the cut or copy operation has occurred. This keeps the document object up-to-date with the actual state of the document.

When a paste operation is attempted, Interface Builder sends the active editor an acceptsTypeFromArray: message to determine if it will accept any of the types on the pasteboard. If the editor refuses the offered types, Interface Builder sends the same message to the next higher editor in the object hierarchy, and so on until it reaches the top. This explains why, if a paste operation is attempted when an NSButton object is on the pasteboard and the Pop-up list editor is open, nothing is pasted in the selected NSPopUpList; instead, the NSButton is pasted in the window that contains the NSPopUpList. The NSPopUpList refused the pasteboard type, but the view editor accepted it.

If the editor accepts one of the offered types, the editor receives a pasteInSelection message. The editor then replaces the selection with the pasted data and alerts Interface Builder of the change by sending the document object a pasteType:fromPasteboard:parent: message.

Editors also control the opening and closing of subeditors.

Method Types

Activity	Class Methods
Editing objects	- initWithObject:inDocument: - close:
Identifying objects	- document - editedObject - window
Displaying objects	- resetObject:
Managing the selection	- wantsSelection - selectObjects: - makeSelectionVisible:
Copying and pasting objects	- copySelection - deleteSelection - pasteInSelection - acceptsTypeFromArray:
Opening and closing editors	- openSubeditorForObject: - closeSubeditors
Activating the editor	- orderFront - activate - validateEditing:

Instance Methods

acceptsTypeFromArray:

- (BOOL)acceptsTypeFromArray:(NSArray*)types

Implement to return the pasteboard types your editor accepts. types is an array of strings holding the type names. If your editor does not accept any of the supplied types, it should return nil.

For example, if an editor only accepts the type IBObjectPboardType, it could implement this method in the following way:

- (BOOL)acceptsTypeFromArray:(NSArray*)types
{
    int i = 0;
    if (!types) {
    return nil;
    }
    for (i=0; i<[types count];i++){
    if ([[types objectAtIndex:i] isEqual:IBObjectPoardType]){
             return IBObjectPboardType;
             }
        }
    return nil;
}

activate

- (BOOL)activate

Implement to activate the editor. Typically, an editor activates itself by making its window key, displaying its selection, and advising the document object that it owns the selection:

- (BOOL)activate
{
    [window makeKeyAndOrderFront:self];
    [self makeSelectionVisible:YES];
    [document setSelectionFrom:self];
    return YES;
}

Your implementation of this method should return YES if the editor activates itself and NO otherwise.

When a user double-clicks on an object controlled by an editor, the editor receives an orderFront and then an activate message. See also - orderFront.

close

- (void)close

Implement to close the editor and free its resources. This method can be invoked for a number of reasons. For example, Interface Builder invokes this method when the user closes the document. Or, your editor might send itself a close message when the user closes the editor's window.

As part of the implementation of this method, send an editorDidClose:forObject: message to the active document to inform IB that the editor has closed:

[[NSApp activeDocument] editorDidClose:self
forObject:editedObject];

See also - editorDidClose:forObject: (IBDocuments protocol).

closeSubeditors

- (void)closeSubeditors

Implement to close all subeditors. See also - openSubeditorForObject:.

copySelection

- (BOOL)copySelection

Implement to copy the selected object(s) to the pasteboard. When the user chooses the Cut or Copy commands in Interface Builder, the editor that owns the selection receives a copySelection message.

In your implementation of this method, you should send the document object a

copyObject:type:inPasteboard: or a
copyObjects:type:inPasteboard: message, as declared in the

IBDocuments protocol. Return YES if the selection was copied to the pasteboard; NO otherwise. See also - deleteSelection.

deleteSelection

- (BOOL)deleteSelection

Implement to delete the selected object(s). This method is invoked when the user deletes the selection by using the Delete key, the Delete command, or as part of the Cut command (after the selection has been copied using the copySelection method).

In your implementation of this method, you should send the document object a detachObject: or a detachObjects: message, as declared in the IBDocuments protocol. Return YES if the selection was deleted; NO otherwise. See also - copySelection.

document

- (id<IBDocuments>)document

Implement this method to return the document to which the object being edited belongs.

editedObject

- (id)editedObject

Implement to return the object that is being edited. This is generally the object on which the user double-clicked to open the editor.

initWithObject:inDocument:

- (id)initWithObject:(id)object
inDocument:(id/*<IBDocuments>*/)document

Implement this method to initialize a newly allocated editor. object is the object that is being edited (for example, the object on which the user has double-clicked). document is the currently active document, as would be returned by sending an activeDocument message to NSApp. Typically, an editor object caches the document object in one of its instance variables, since editors must frequently communicate with the document object.

makeSelectionVisible:

- (void)makeSelectionVisible:(BOOL)showIt

Implement to add or remove the selection markings from the current selection. An editor receives a makeSelectionVisible: message whenever Interface Builder wants to ensure that the selection is properly marked. For example, when a window becomes key, the editor that owns the selection in the window receives a makeSelectionVisible:YES message. When the window loses its key window status, the editor that owns the selection receives a makeSelectionVisible:NO message.

openSubeditorForObject:

- (id<IBEditors>)openSubeditorForObject:(id)object

Implement to open the subeditor for anObject. An editor receives this message when the user double-clicks in the editor's selection. For the return value of this method, the editor should return nil if there is no subeditor; otherwise, it should return of the subeditor object.

orderFront

- (void)orderFront

Implement to bring the editor's window to the front. When a user double-clicks on an object, the controlling editor receives an orderFront and then an activate message. See also - activate.

pasteInSelection

- (BOOL)pasteInSelection

Implement to paste the object(s) from the pasteboard into the current selection. When the user chooses the Paste command in Interface Builder, the editor that owns the selection receives a pasteInSelection message. The implementation of the corresponding method should invoke the document object's pasteType:fromPasteboard:parent: method.

This method should return YES if the paste operation was successful; NO otherwise. See also - pasteType:fromPasteboard:parent: (IBDocuments protocol).

resetObject:

- (void)resetObject:(id)object

This method should redraw object. When the document object receives a drawObject: message, it makes sure that the editor for that object--and for each of its parent objects--is open. It then sends resetObject: messages to each of the editors in this object hierarchy.

selectObjects:

- (void)selectObjects:(NSArray *)objects

Implement to draw the objects for the array to indicate that they are all selected.

validateEditing

- (void)validateEditing

Causes the value of the selection to be set to the value of the field being edited, if any. "Being edited" does not necessarily mean a user is typing. If a field (for example, an NSTextField object) has Interface Builder's global NSText object in its place as first responder, then the field is considered as being edited.

wantsSelection

- (BOOL)wantsSelection

Implement to return YES if the editor is willing to become the selection owner; NO if not.

window

- (NSWindow*)window

Implement to return the editor's window.

IBSelectionOwners

Characteristic	Description
Adopted By:	no OpenStep classes
Declared In:	include/InterfaceBuilder/IBEditors.h

Protocol Description

All editors must conform to the IBSelectionOwners protocol. By implementing this protocol, an editor advertises its selection to other objects in Interface Builder. (The selection is that object or objects that would be copied if the user chose the Copy command.)

For example, Interface Builder invokes an editor's selectionCount and getSelectionInto: methods to determine how to update the Inspector panel. If the selection count is more than one, the Inspector panel displays the message "Multiple Selection". If there is only one object in the selection, Interface Builder invokes the editor's getSelectionInto: method to access the object and then determines the appropriate inspector to display in the Inspector panel.

Instance Methods

drawSelection

- (void)drawSelection

Implement this method to redraw the objects in the selection.

selection:

- (NSArray*)selection

Implement this method to place the currently selected objects into an array object. If the editor does not have a selection, it should return an empty array. See also - selectionCount.

selectionCount

- (unsigned int)selectionCount

Implement to return the number of objects in your editor's selection. See also - selection:.