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

IBConnectors

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

Protocol Description

This protocol declares Interface Builder's link to a connector object.  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 begins executing and it loads a nib file, the connector objects in the nib file are unarchived and are sent the establishConnection message.  It is at this point that the connector can establish its type of connection between the source and destination.  For example, Interface Builder's outlet connector sets the named outlet to point to the destination object. Since connector objects are guaranteed to be archived in the nib file and are guaranteed to receive an establishConnection message at run time, they provide a mechanism for you to store other application-specific information in a nib file. Your Connection inspector must set the source and destination in each of its connectors (for example, with setSource: and setDestination: methods).  This protocol doesn't include methods to set these outlets, only to query them.

Instance Methods

destination

destination

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

establishConnection

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.

free

free

Implement to release the storage for the connector object.

nibInstantiate

nibInstantiate

Implement to verify the identities of the connector's source and destination objects. Interface Builder sends a nibInstantiate message to a connector object to give it an opportunity to verify that its source and destination instance variables point to the intended objects.  For example, consider the case in which a user puts a CustomView in a window and then reassigns the CustomView's class to MyView.  The MyView class has a textfield outlet that the user connects to a neighboring TextField object.  This action causes Interface Builder to create a connector object and set its destination to the TextField and its source to the CustomView.  (The source can't be set to the MyView object since that class doesn't exist in InterfaceBuilder--that's why the CustomView was used in the first place.) When the resulting nib file is loaded in the finished application, the connector object is unarchived and sent a nibInstantiate message.  It's at this point that the connector must reset its source instance variable from the CustomView object to the MyView object. The Application Kit, in a category of Object, provides a default implementation of this method.  This implementation returns self.  (Please note that the method isn't publically declared, a problem that will be remedied in a later release.)  Consequently, all objects can respond to a nibInstantiate message.  Your connector, therefore, should minimally implement this method to send nibInstantiate messages to its source and destination objects.  For example, assuming the outlets are named theSource and theDestination, the implementation is:

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

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

read:

read:(NXTypedStream *)stream

Implement to unarchive the connector object from stream.  The connector should read in its instance variables and do any other initialization it requires. See also:  write

renewObject:to:

renewObject:old to:new

Implement to update a connector by replacing its old source or destination object (old) with a new object (new).  This is used by Interface Builder, for example, when a user drags a Button object into a Matrix of ButtonCells.  Assuming that the Button was connected, the connection information must be updated to reflect that fact that the Button has been replaced by a ButtonCell. Interface Builder updates this information by sending the appropriate connector object a renewObject:to: message with the Button as old and the ButtonCell as new.

source

source

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

write:

write:(NXTypedStream *)stream

Implement to archive the connector object to stream. See also:  read