Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

IBDocuments

	Adopted By:	no NEXTSTEP classes
	Declared In:	apps/InterfaceBuilder.h

Protocol Description

This 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 Application an activeDocument message:

theActiveDoc = [NXApp activeDocument];

The document object maintains the 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:to: message.  Interface Builder won't 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

Managing the document

touch

getDocumentPathIn:

Managing the object hierarchy

attachObject:to:

attachObjects:to: deleteObject: deleteObjects: copyObject:type:inPasteboard: copyObjects:type:inPasteboard: pasteType:fromPasteboard:parent: objectIsMember: getObjects: getParentForObject:

Setting object names

setName:for:

getNameIn:for:

Managing connectors

addConnector:

removeConnector: listConnectors:forSource: listConnectors:forDestination: listConnectors:forSource:filterClass: listConnectors:forDestination:filterClass:

Managing editors

setSelectionFrom:

editorDidClose:for: getEditor:for: openEditorFor:

Updating the display

redrawObject:

Instance Methods

addConnector:

addConnector:aConnector

Adds a connector object to the list maintained by Interface Builder.  (See the IBConnectors protocol for more information.)  This is the message a custom connection inspector sends Interface Builder's document object to register a connection. See also:  addConnector:

attachObject:to:

attachObject:anObject to:parent

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

attachObjects:to:

attachObjects:(List *)objectList to:parent

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

copyObject:type:inPasteboard:

copyObject:anObject

type:(NXAtom)type inPasteboard:(Pasteboard *)aPasteboard

Copies anObject 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:inPasteboard: or copyObjects:type:inPasteboard: message as part of its implementation of its copySelection method. See also:  copyObjects:type:inPasteboard:

copyObjects:type:inPasteboard:

copyObjects:(List *)objectList

type:(NXAtom)type inPasteboard:(Pasteboard *)aPasteboard

Copies the objects in objectList 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:inPasteboard: or copyObjects:type:inPasteboard: message as part of its implementation of its copySelection method. See also:  copyObject:type:inPasteboard:

deleteObject:

deleteObject:anObject

Removes anObject from the document's object hierarchy.  An editor should send the document object a deleteObject: or deleteObjects: message as part of its implementation of the deleteSelection method.  This will keep the document's accounting of the objects in the nib document in agreement with the actual state of the document. See also:  deleteObjects:

deleteObjects:

deleteObjects:(List *)objectList

Removes the objects in objectList from the document's object hierarchy.  An editor should send the document object a deleteObject: or deleteObjects: message as part of its implementation of the deleteSelection method.  This will keep the document's accounting of the objects in the nib document in agreement with the actual state of the document. See also:  deleteObject:

editorDidClose:for:

editorDidClose:anEditor for:anObject

Informs the document object that anEditor is no longer active.  By sending this message to the document object when you close an editor, you keep Interface Builder's record of the active editor 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.

getDocumentPathIn:

getDocumentPathIn:(char *)buffer

Places the document's path in buffer.  This is the path displayed as the title of Interface Builder's File window.  Make sure that buffer is sufficiently larger to hold the path.  Returns the document object.

getEditor:for:

getEditor:(BOOL)createIt for:anObject

Returns the editor object for anObject.  If createIt is YES and the editor hasn't been instantiated, it will be 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 hasn't been instantiated, this method returns nil.

getNameIn:for:

getNameIn:(char *)buffer for:anObject

Places the name associated with anObject in buffer.  Make sure the buffer you pass in is sufficiently large to accommodate the name.  Returns the document object. See also:  setName:for:

getObjects:

getObjects:(List *)objectList

Places the objects from the document's object hierarchy into objectList.  The object's are not arranged in any particular order.

getParentForObject:

getParentForObject:anObject

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

listConnectors:forDestination:

listConnectors:(List *)aList forDestination:aDestination

Places in aList all connector objects whose destinations are aDestination.  Returns aList. Since a given object can be the destination of multiple connections, the connection information is returned as a list of objects. Each object in the list conforms to the IBConnectors protocol and contains the information for one connection. aList is a List object that you provide.  When you're done with aList, free it but don't free the connection objects within it since they're managed by Interface Builder. See also:  listConnectors:forDestination:filterClass:, listConnectors:forSource:

listConnectors:forDestination:filterClass:

listConnectors:(List *)aList

forDestination:aDestination filterClass:aClass

Places in aList the connector objects of class aClass whose destinations are aDestination.  Returns aList. Since a given object can be the destination of multiple connections, the connection information is returned as a list of objects. Each object in the list conforms to the IBConnectors protocol and contains the information for one connection. aList is a List object that you provide.  When you're done with aList, free it but don't free the connection objects within it since they're managed by Interface Builder. See also:  listConnectors:forDestination:, listConnectors:forSource:

listConnectors:forSource:

listConnectors:(List *)aList forSource:aSource

Places in aList all connector objects whose sources are aSource.  Returns aList. Since a given source can have multiple connections, the connection information is returned as a list of objects.  Each object in the list conforms to the IBConnectors protocol and contains the connection information for one connection. aList is a List object that you provide.  When you're done with aList, free it but don't free the connection objects within it since they're managed by Interface Builder. See also:  listConnectors:forSource:filterClass:, listConnectors:forDestination:

listConnectors:forSource:filterClass:

listConnectors:(List *)aList

forSource:aSource filterClass:aClass

Places in aList the connector objects of class aClass whose sources are aSource.  Returns aList. Since a given source can have multiple connections, the connection information is returned as a list of objects.  Each object in the list conforms to the IBConnectors protocol and contains the connection information for one connection. aList is a List object that you provide.  When you're done with aList, free it but don't free the connection objects within it since they're managed by Interface Builder. See also:  listConnectors:forSource:, listConnectors:forDestination:

objectIsMember:

(BOOL)objectIsMember:anObject

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

openEditorFor:

(BOOL)openEditorFor:anObject

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

pasteType:fromPasteboard:parent:

(List

*)pasteType:(NXAtom)type

fromPasteboard:(Pasteboard *)thePasteboard parent:theParent

Alerts the document object that one or more objects were pasted.  Returns a List containing the ids of the objects that were pasted.  The pasteboard and the type being pasted are identified by thePasteboard and type. An editor uses this method to keep Interface Builder's document object up to date.  The implementation of this method invokes attachObjects:to: and touch for you.  The List object that's returned lets you add the objects to your data structures.  It is your responsibility to free the returned List.

redrawObject:

redrawObject:anObject

Redraws the selected object by opening its editor--and the editor for its parent object, and so on up the object hierarchy--and sending each editor a resetObject: message.

removeConnector:

removeConnector:aConnector

Removes aConnector from the list of connectors maintained by Interface Builder.  (See the IBConnectors protocol for more information on connectors.)  This is the message a custom connection inspector sends Interface Builder's document object to break a connection. Interface Builder doesn't free aConnector; it's your responsibility to do so. See also:  addConnector:

setName:for:

(BOOL)setName:(const char *)name for:anObject

Sets the name associated with the anObject.  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:  getNameIn:for:

setSelectionFrom:

setSelectionFrom:anEditor

Registers anEditor 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.  This keeps 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

touch

Marks the document as edited by causing the File window's close box to display a broken "X".  Returns the document object.