IBInspector

Characteristic	Description
Inherits From:	NSObject
Declared In:	include/InterfaceBuilder/IBInspector.h

Class Description

The IBInspector class defines the interface between an inspector for a loadable module and the Interface Builder application. When you build a new inspector for Interface Builder, you create a subclass of IBInspector.

The inspector you define must load its interface (that is, the nib file containing the interface), and it must override the ok:, revert:, and wantsButtons methods. The nib file is generally loaded as part of the inspector's init method. The wantsButtons method controls whether the inspector displays OK and Revert button. (As with Interface Builder's standard inspectors, most custom inspectors do not need these buttons--instead, the user's actions in the Inspector panel are registered immediately by the inspected object.) The ok: and revert: methods control the synchronization of the Inspector panel's state with that of the inspected object. Interface Builder sends the inspector a

revert: message to make the inspector reflect the current state of the inspected object. The ok: message should cause the inspector to set the state of the inspected object to that displayed in the Inspector panel.

An inspector should send itself a touch: message when the user begins modifying the data it displays. This message displays a broken "X" in the panel's close box and enables the inspector's OK and Revert buttons, if present. (See "textDidBeginEditing:" on page C-5 for alternate way to achieve this result.)

Instance Variables

id object;
NSWindow* window;
id manager;
NSButton* okButton;
NSButton* revertButton;

Variable	Description
object	The object that is being inspected
window	The Panel that contains the inspector's user interface
manager	private
okButton	The Inspector panel's OK button, if present
revertButton	The Inspector panel's Revert button, if present

Method Types

Activity	Class Methods
Accessing objects	- object - okButton - revertButton - textDidBeginEditing - wantsButtons - window
Managing changes	- ok: - revert - textDidBeginEditing - touch

Instance Methods

object

- (id)object

Returns the object that is being inspected.

ok:

- (void)ok:(id)sender

Implement in your subclass of IBInspector to commit the changes that the user makes in the Inspector panel. The OK button in the Inspector panel--if present--sends an ok: message when the user clicks on it.

Your implementation of this method must send the same message to super as follows:

(void)ok:(id)sender
{
    /* your code to commit changes */
    [super (ok:sender];
    return self;
}

The message to super replaces the broken "X" in the panel's close box with the standard "X", indicating that the changes have been committed. See also - revert:, - touch:.

okButton:

- (NSButton *)okButton

Returns the Inspector's OK button object. This can be useful if you want to alter its title, for example. See also - revertButton.

revert:

- (void)revert:(id)sender

Implement in your subclass of IBInspector to synchronize the inspector's display with the state of the object being inspected. Interface Builder sends this message to the inspector object whenever the inspector's display might need to be updated, for example, when the user opens the Inspector panel and the selected object in Interface Builder is of the type associated with this inspector. The Revert button in the Inspector panel--if present--also sends a revert: message when the user clicks on it.

Your subclass must implement this method, and it must send the same message to super as part of its implementation, as follows:

revert:sender
{
    /* your code to inspect selected object */
    [super revert:sender];
    return self;
}

This message to super replaces the broken "X" in the panel's close box with the standard "X", indicating that the changes have been discarded. See also - ok:, - touch.

revertButton:

- (NSButton *)revertButton

Returns the Inspector's Revert button object. This can be useful if you want to alter its title, for example. See also - okButton.

textDidBeginEditing:

- textDidBeginEditing:sender

Sends the IBInspector a touch: message on behalf of some NSText object in the Inspector panel.

By making your inspector object the delegate of any NSText object in the Inspector panel, the panel will be updated appropriately as the user alters the panel's contents. See also - touch:.

touch:

- (void)touch:(id)sender

Changes the image in the Inspector panel's close box to a broken "X" to indicate that the contents have been edited. Also, enables the buttons that allow the user to commit or abandon changes. See also - textDidBeginEditing:.

wantsButtons

- (BOOL)wantsButtons

Returns a boolean value indicating whether the inspector object requires Interface Builder to display the OK and Revert buttons in the Inspector panel.

window

- (NSWindow *)window

Returns the NSWindow object that contains the user interface for the inspector.

IBPalette

Characteristic	Description
Inherits From:	NSObject
Declared In:	include/InterfaceBuilder/IBPalette.h

Class Description

The IBPalette class defines Interface Builder's link to a dynamically loaded palette. Interface Builder uses the facilities of this class to load a custom palette's interface and executable code.

Each loadable palette must contain a subclass of IBPalette, and this class must be identified in the palette's palette.table file. Interface Builder creates an instance of this subclass when it loads the palette. In its init method, the subclass must load the nib file containing the classes of objects on the palette. Interface Builder then sends the palette object an originalWindow message to access the window that contains the views to be displayed in the Palette window.

If a palette contains non-NSView objects (NSMenuCells, NSWindows, or objects that will be deposited in the nib file window), the subclass must implement the finishInstantiate method to associate each NSView object that is displayed in the Palette window with the non-NSView object that should be created when the user instantiates the object by dragging it from the palette.

For example, consider a custom palette that provides an AddressBook object that manages people's names and addresses. This object, a subclass of NSObject, is to be dragged into the nib file window. Further, imagine that the subclass of IBPalette for this custom palette, AddressBookPalette, has two outlets: addressBookObject and addressBookView. When the palette's nib file was created, the outlets were connected to the AddressBook object and to an NSView object that will represent it in the Palette window. Within the AddressBookPalette class implementation file, the finishInstantiate method would look like this:

- (void)finishInstantiate
{
    [self associateObject:addressBookObject

        type:IBObjectPboardType with:addressBookView];
    return self;
}

Notice that the subclass establishes an association by sending itself an associateObject:ofType:withView: message. IBPalette implements this method. The second argument is a type string defined in IBPalette.h that controls where the palette image may be deposited:

Type	Usage
IBObjectPboardType	For objects that the user must deposit in the File window
IBMenuCellPboardType	For NSMenuCells without submenus; must be deposited in a menu
IBMenuPboardType	For NSMenuCells that have submenus; must be deposited in a menu
IBWindowPboardType	For NSWindows and NSPanels; must be deposited in the workspace

Instance Variables

id <IBDocuments> _paletteDocument;
NSWindow *_originalWindow;
IBPaletteView *_paletteView;
NSView *_draggedView;
id _paletteBundle;

Variable	Description
paletteDocument	An object conforming to the IBDocuments protocol that represents the dynamically loaded palette
originalWindow	The window containing the interface objects that will be loaded into Interface Builder's Palettes window
paletteView	private
draggedView	private
paletteBundle	private

Method Types

Activity	Class Methods
Associating NSViews and NSObjects	- associateObject:ofType:withView:
Initializing the palette	- finishInstantiate
Accessing related objects	- paletteDocument - originalWindow - imageNamed:

Instance Methods

associateObject:ofType:withView:

- (void)associateObject:(id)object ofType:(NSString *)type
withView:(NSView *)view

Establishes an association between an NSView in a palette (view) and the object that should be instantiated when the user drags the NSView from the palette (object). The type argument controls where the palette object may be deposited. (See "Class Description" on page C-6 for more information.)

If your custom palette provides non-NSView objects, override IBPalette's finishInstantiate method with an implementation that sends associateObject:ofType:withView: messages to associate each NSView object in the palette with the non-NSView object that it represents.

imageNamed:

- (NSImage *)imageNamed:(NSString *)name

Returns the NSImage instance associated with name. If no such image can be found, this method returns nil.

Use this method to refer to images in your custom palette. This method first tries to find the image by invoking NSImage's version of findImageNamed:. If that is unsuccessful, it uses the facilities of the NSBundle class to check the .palette directory for this resource. See getPath:forResource:ofType: for a description of NSBundle's search path. See also

- pathForResource:ofType: (NSBundle common class).

finishInstantiate

- (void)finishInstantiate

Implement to complete the initialization of your IBPalette object. Interface Builder sends a finishInstantiate message to the IBPalette object after it has been unarchived from the palette file. A typical use of this method is to associate an NSView object within the custom palette with a non-NSView object that is meant to represent it in the Palette window. See "Class Description" on page C-6 for more information. See also - associateObject:type:with:.

originalWindow

- (NSWindow *)originalWindow

Returns the NSWindow that contains the NSView objects to be loaded into Interface Builder's Palette window. When it loads a custom palette, Interface Builder sends the IBPalette subclass an originalWindow message. In your custom palette, you must connect the originalWindow outlet of your subclass of IBPalette to the NSWindow that contains the NSViews that represent your palette objects.

paletteDocument

- (id<IBDocuments>)paletteDocument

Returns an object that represents the dynamically loaded palette. This object is of unspecified class; however, it conforms to the IBDocuments protocol.

NSApplication Additions

Characteristic	Description
Category Of:	NSApplication
Declared In:	include/InterfaceBuilder/IBConnectors.h

Category Description

Interface Builder adds these methods to the definition of the NSApplication class for managing connections. They may be useful when implementing your own Connections inspector.

Instance Methods

connectDestination

- (id)connectDestination

Returns the object that is the destination of the connection; that is, the object to which the user has dragged a connection line. See also - connectSource.

connectSource

- (id)connectSource

Returns the object that is the source of the connection; that is, the object from which the user has dragged a connection line. See also

- connectDestination.

displayConnectionBetween:and:

- (void)displayConnectionBetween:(id)source and:(id)destination

Causes Interface Builder to draw connection lines between source and destination. For example, when the user clicks on an entry in the Connections list in the Connections inspector, Interface Builder uses this method to display the corresponding connection.

The act of displaying a connection between these two objects does not require that a connection really exist, and does not create a connection. It is the Connection inspector's responsibility to establish the programmatic connection. This method simply draws lines between two objects and attempts to make both objects visible. See also - stopConnecting.

isConnecting

- (BOOL)isConnecting

Returns YES if connection lines are being displayed in Interface Builder. You can use this information to control how your object is drawn during the connection process. For example, when you drag a connection line from a button, the button's black border and text are redrawn in gray. See also

- stopConnecting.

stopConnecting

- (void)stopConnecting;

Causes Interface Builder to remove any connection lines from the screen. Interface Builder uses this method to remove connection lines when the user drags a window. See also - isConnecting.

NSObject Additions

Characteristic	Description
Category Of:	NSObject
Declared In:	include/InterfaceBuilder/IBDocuments.h include/InterfaceBuilder/IBEditors.h include/InterfaceBuilder/IBInspector.h include/ InterfaceBuilder/IBObjectAdditions.h

Category Description

Interface Builder adds these methods to the definition of the NSObject class so that any palette object can be queried for its inspectors, for its editor, and for an image to represent the object when it is instantiated in the File window.

The methods described in "Instance Methods" on page C-12 return the class name for the object that will own the Inspector panel's display. Interface Builder caches this information so that when the user attempts to inspect an object, Interface Builder knows what type of inspector to instantiate (if it has not yet been instantiated). The inspector object provides the interface that Interface Builder displays in the Inspector panel.

Interface Builder supplies default implementations of these methods; you only override them if your custom palette object requires it. For example, if you create an NSTextField palette object that validates its input, you would probably provide an Attributes inspector that lets the user specify the acceptable input values. Thus, you would override the inspectorClassName method to return the class name for the Attributes inspector object. However, you would probably not have to override the other inspector methods since the standard inspectors would be satisfactory.

By default, these methods return the empty string "", except for imageforViewer, which returns nil.

Override the editorClassName method to return the class name of the editor to use for this object. The editor is invoked when the user double-clicks on the object. NSView objects inherit Interface Builder's standard NSView editor.

You only need to override the imageForViewer method if you want a special image to represent your custom palette object when it is dragged into the nib file window. If you do not supply such an image, Interface Builder uses the standard cube image.

Instance Methods

awakeFromDocument:

- (void)awakeFromDocument:(id<IBDocuments>)document

Allows special behavior after the nib document has been loaded.

canSubstituteFor Class:

+ (BOOL)canSubstituteForClass:(Class)originalObjectClass

Implement to have custom class not be displayed in the inspector of its superclass. Returns YES if self is a valid replacement class for originalObjectClass; NO otherwise.

connectInspectorClassName

- (NSString *)connectInspectorClassName

Returns the class name of the receiver's Connection inspector. Interface Builder uses this information to instantiate the Inspector object for the currently selected object. You should rarely need to override the standard Connection inspector.

editorClassName

- (NSString *)editorClassName

Returns the class name of the receiver's editor. Interface Builder uses this information to instantiate the editor object for the currently selected object.

helpInspectorClassName

- (NSString *)helpInspectorClassName

Returns the class name of the receiver's Help inspector. Interface Builder uses this information to instantiate the help inspector object for the currently selected object. You should rarely need to override the standard Help inspector.

imageForViewer:

- (NSImage *)imageForViewer

Returns the image that is displayed in the File window when an instance of this class is created. By default, Interface Builder provides an image of a cube. If you want to provide a different image, implement this method in your custom class.

inspectorClassName

- (NSString *)inspectorClassName

Returns the class name of the receiver's Attributes inspector. Interface Builder uses this information to instantiate the attributes inspector object for the currently selected object.

sizeInspectorClassName

- (NSString *)sizeInspectorClassName

Returns the class name of the receiver's size inspector. Interface Builder uses this information to instantiate the size inspector object for the currently selected object.

NSCellAdditions

Characteristic	Description
Category Of:	NSCell
Declared In:	include/InterfaceBuilder/IBViewAdditions.h

Category Description

Interface Builder adds three methods to the definition of the NSCell class so that an NSCell that is dragged from the Palette window can control its size and make other adjustments as a consequence of resizing.

Instance Methods

cellWillAltDragWithSize:

- (void)cellWillAltDragWithSize:(NSSize)cellSize

Allows the cell to set up the necessary state before Alt-dragging.

maximumSizeForCellSize:

- (NSSize)maximumSizeForCellSize:(NSSize)cellSize
knobPosition:(IBKnobPosition)knobPosition

Implement this method to control the maximum dimensions of your NSCell.

The knobPosition argument specifies which control point the user is dragging to resize the object. It can have these values:

IBBottomLeftKnobPosition
IBMiddleLeftKnobPosition
IBTopLeftKnobPosition
IBMiddleTopKnobPosition
IBTopRightKnobPosition
IBMiddleRightKnobPosition
IBBottomRightKnobPosition
IBMiddleBottonKnobPosition

You can use the knobPosition argument to determine how the NSCell will resize.

minimumSizeForCellSize:

- (NSSize)minimumSizeForCellSize:(NSSize)cellSize
knobPosition:(IBKnobPosition)knobPosition

Implement this method to control the minimum dimensions of your NSCell.

The knobPosition argument specifies which control point the user is dragging to resize the object. It can have these values:

IBBottomLeftKnobPosition
IBMiddleLeftKnobPosition
IBTopLeftKnobPosition
IBMiddleTopKnobPosition
IBTopRightKnobPosition
IBMiddleRightKnobPosition
IBBottomRightKnobPosition
IBMiddleBottonKnobPosition

You can use the knobPosition argument to determine how the NSCell will resize.

NSView Additions

Characteristic	Description
Category Of:	NSView
Declared In:	include/InterfaceBuilde/IBViewAdditions.h

Category Description

Interface Builder adds four methods to the definition of the NSView class so that an NSView that is dragged from the Palette window can control its size and make other adjustments as a consequence of resizing. As the user begins to drag one of the NSView's control points, Interface Builder sends it a maximumSizeFromKnobPosition: or minimumSizeFromKnobPosition: message. When the user releases the mouse button, the View receives a placeView: message.

Instance Methods

allowsAltDragging:

- (BOOL)allowsAltDragging

Return YES to allow your NSView subclass to be Alt-dragged to create a matrix. The NSView must provide a cell for the resulting matrix.

maximumSizeFromKnobPosition:

- (NSSize)maximumSizeFromKnobPosition:(IBKnobPosition)knobPosition

Implement this method to control the maximum dimensions of your NSView.

The knobPosition argument specifies which control point the user is dragging to resize the object. It can have these values:

IBBottomLeftKnobPosition
IBMiddleLeftKnobPosition
IBTopLeftKnobPosition
IBMiddleTopKnobPosition
IBTopRightKnobPosition
IBMiddleRightKnobPosition
IBBottomRightKnobPosition
IBMiddleBottonKnobPosition

You can use the knobPosition argument to determine how the NSView will resize.

minimumSizeFromKnobPosition:

- (NSSize)minimumSizeFromKnobPosition:(IBKnobPosition)knobPosition

Implement this method to control the minimum dimensions of your NSView.

The knobPosition argument specifies which control point the user is dragging to resize the object. It can have these values:

IBBottomLeftKnobPosition
IBMiddleLeftKnobPosition
IBTopLeftKnobPosition
IBMiddleTopKnobPosition

IBTopRightKnobPosition
IBMiddleRightKnobPosition
IBBottomRightKnobPosition
IBMiddleBottonKnobPosition

You can use the knobPosition argument to determine how the NSView will resize. For example, an NSBox determines which control point is being dragged and then lets the user shrink its size from that point only to the degree that no subview (NSButton, NSTextField) would be obscured.

placeView:

- (void)placeView:(NSRect)newFrame

Notifies an NSView of a change in its frame size. Interface Builder's implementation of this method is to send a setFrame: message to the receiver, using newFrame as the argument.

You can implement this method, for example, to resize the NSView's subviews. In your implementation, you should also send a setFrame: message to self to set the NSView's new size.