IBEditors

IBEditors

Adopted By: no NEXTSTEP classes

Incorporates: IBSelectionOwners

Declared In: apps/InterfaceBuilder.h

Protocol Description

This protocol, and the IBSelectionOwners protocol that it incorporates, define the required programmatic interface to an editor object in Interface Builder. When a user double-clicks a custom object, Interface Builder instantiates the object's editor (using initWith: inDocument:). (Interface Builder would have previously determined the editor's class by sending the custom object a getEditorClassName message. See the Object Additions specification 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 acceptsTypeFrom: 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 a Button object is on the pasteboard and the Pop-up list editor is open, nothing is pasted in the selected PopUpList; instead, the Button is pasted in the window that contains the PopUpList. The PopUpList 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. Imagine that an AddressBook object can contain not only addresses, but other AddressBooks. For example, an AddressBook for a university could contain AddressBooks for each department of the university. When the AddressBook for the Spanish department is double-clicked, a subeditor must be opened to allow the editing of this nested AddressBook.

Method Types

Initializing initWith:inDocument:

Identifying objects document

editedObject
window

Displaying objects resetObject:

Managing the selection wantsSelection

selectObjects:
makeSelectionVisible:

Copying and pasting objects copySelection

deleteSelection
pasteInSelection
acceptsTypeFrom:

Opening and closing editors close

openSubeditorFor:
closeSubeditors

Activating the editor orderFront

activate

Instance Methods

acceptsTypeFrom:

(NXAtom)acceptsTypeFrom:(const NXAtom *)typeList

Implement to return the pasteboard types your editor accepts. typeList is an array of character pointers holding the type names, with the last pointer being NULL. Each of the pointers is of the type NXAtom, meaning that the type name is a unique string. If your editor doesn't accept any of the supplied types, it should return NULL.
For example, if an editor only accepts the type IBObjectPboardType, it could implement this method in this way:

(NXAtom)acceptsTypeFrom:(const NXAtom *)typeList
{
int i = 0;
if (!typeList) return NULL;
while (typeList[i]) {
if (IBObjectPboardType == typeList[i])
return IBObjectPboardType;
i++;
}
return NULL;
}

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 an object controlled by an editor, the editor receives an orderFront and then an activate message.
See also: orderFront

close

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:for: message to the active document to inform IB that this editor has closed:

[[NXApp activeDocument] editorDidClose:self for:editedObject];

See also: editorDidClose:for: (IBDocuments protocol)

closeSubeditors

closeSubeditors

Implement to close all subeditors.
See also: openSubeditorFor:

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 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 deleteObject: or a deleteObjects: message, as declared in the IBDocuments protocol. Return YES if the selection was deleted; NO otherwise.
See also: copySelection

document

document

Implement this method to return the currently active document, as would be returned by sending an activeDocument message to NXApp.

editedObject

editedObject

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

initWith:inDocument:

initWith:anObject inDocument:aDocument

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

makeSelectionVisible:

makeSelectionVisible:(BOOL)flag

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.

openSubeditorFor:

openSubeditorFor:anObject

Implement to open the subeditor for anObject. An editor receives this message when the user double-clicks within 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 the id of the subeditor.

orderFront

orderFront

Implement to bring the editor's window to the front. When a user double-clicks 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:

resetObject:anObject

This method should redraw anObject. When the document object receives a redrawObject: 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:

selectObjects:(List *)objectList

Implement to draw the objects in objectList in a way that indicates that they are selected.

wantsSelection

(BOOL)wantsSelection

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

window

window

Implement to return the editor window.

	Adopted By:	no NEXTSTEP classes

	Incorporates:	IBSelectionOwners

	Declared In:	apps/InterfaceBuilder.h

	Displaying objects	resetObject:

	Managing the selection	wantsSelection