This is IKAnnouncer.rtf in view mode; [Download] [Up]
Release 1.2 Copyright ©1994 by H. Scott Roy All Rights Reserved.
IKAnnouncer
Inherits From: Object
Conforms To: IKDependency
Declared In: iconkit/IKAnnouncer.h
Class Description
IKAnnouncer is the principle IconKit class that conforms to the IKDependency protocol. Every other class in IconKit that conforms to the protocol does so by forwarding messsages to an IKAnnouncer object. More details can be found in the documentation for IKList, IKFolder, and IKShelf.
The IKAnnouncer class provides a simple announcement service for an object to broadcast messages to its users and listeners. It also provides a polling mechanism to ensure that users approve of a pending action.
For example, when the name of an IKFolder changes, it sends its personal IKAnnouncer object an announce: message with the argument @selector(didChangeName:). The IKAnnouncer broadcasts this message to all the users and listeners that can respond so that they can take appropriate action.
Instance Variables
id owner;
id usersAndListeners;
int numUsers;
BOOL sendAnnouncements;
owner The object from which announcements and polling messages appear to originate.
usersAndListeners The list of all users and listeners.
numUsers The number of users.
sendAnnouncements True if the IKAnnouncer should send out announcements.
Method Types
Initialization and freeing - initOwner:
- free
Users and listeners - addUser:
- addListener:
- removeUser:
- removeListener:
- numUsers
- usersAndListeners
Announcements - announce:
- announce:with:
- poll:
- poll:with:
- sendAnnouncements
- setSendAnnouncements:
Instance Methods
addUser:
- addUser: who
Adds a new user to the IKAnnouncer. Users will receive notification of changes to the IKAnnouncer's owner via the announce: methods. If IconKit has been compiled with the DEBUG macro defined, then this method prints out an acknowledgement to stderr.
See also: - removeUser:, - addUser: (IKDependency)
addListener:
- addListener: who
Adds a new listener to the IKAnnouncer. Listeners will receive notification of changes to the IKAnnouncer's owner via the announce: methods. If IconKit has been compiled with the DEBUG macro defined, then this method prints out an acknowledgement to stderr.
See also: - removeListener:, - addListener: (IKDependency)
announce:
- announce:(SEL)theMessage
Broadcasts theMessage to all users and listeners of the IKAnnouncer that can respond to it; users and listeners that do not implement theMessage do not receive it. The broadcast message should take exactly one argument, e.g. didChangeName:, which will contain the owner of the IKAnnouncer.
Announcements are only sent if the sendAnnouncements variable is True.
Here is a skeletal example that illustrates how announcements work. The IKFolder and IKSuitcase classes both implement the following method to change their name:
- setName: (const char *) theName
{
if (name != NULL) free(name);
name = theName ? NXCopyStringBuffer(theName) : NULL;
[users announce: @selector(didChangeName:)];
return self;
}
If an object needs to do something when an IKFolder changes its name, it should register with either an addUser: or addListener: message and implement the following:
- didChangeName: sender
{
/* sender, an IKFolder, just changed its name */
return self;
}
The IconKit classes all document the announcement messages they send out. Users only need to implement methods for the particular messages they care about.
See also: - announce:with:, - poll:, - addUser:, - addListener:
announce:with:
- announce:(SEL)theMessage
with: theArgument
Like announce:, except that it provides an additional argument to go along with theMessage. For example, an IKList sends out the announcement list:didAdd: after it inserts an object. Receiving objects should implement something like,
- list: sender didAdd: anObject
{
/* sender, an IKList, just added anObject */
return self;
}
Announcements are only sent out if the sendAnnouncements variable is True.
See also: - announce:, - poll:with:, - addUser:, - addListener:
free
- free
Frees the IKAnnouncer. This method does not send out any announcements. Classes like IKFolder and IKList that make use of IKAnnouncer are responsible for sending out willFree: messages before they commence freeing themselves.
initOwner:
- initOwner: theOwner
Initializes a new IKAnnouncer with the given owner. This method is the only way to set an IKAnnouncer's owner.
numUsers
- (int)numUsers
Returns the current number of users registered with the IKAnnouncer. This number will be less than the length of usersAndListeners if any objects have registered as listeners.
See also: - usersAndListeners
poll:
- (BOOL)poll:(SEL)theMessage
Conducts a poll of all users and listeners that can respond to theMessage. The result is the logical AND of all their responses. Just like C code, the AND evaluation terminates as soon as a single object responds NO, so some objects might never see the polling message.
Polling messages are always sent out, regardless of the current state of sendAnnouncements.
The syntax and usage is identical to announce:, with the one exception that theMessage should be declared to return a BOOL instead of an id.
See also: - poll:with:, - announce:
poll:with:
- (BOOL)poll:(SEL)theMessage
with: theArgument
Like poll:, except that it provides an additional argument to go along with theMessage. The syntax and usage are identical to announce:with:, with the one exception that theMessage should be declared to return a BOOL instead of an id.
See also: - poll:, - announce:with:
removeUser:
- removeUser: who
Removes a user from the IKAnnouncer. If IconKit has been compiled with the DEBUG macro defined, then this method prints out an acknowledgement to stderr. Classes like IKFolder and IKList that use IKAnnouncer intercept this message to do reference counting garbage collection.
See also: - addUser:, - removeUser: (IKDependency)
removeListener:
- removeListener: who
Removes a listener from the IKAnnouncer. If IconKit has been compiled with the DEBUG macro defined, then this method prints out an acknowledgement to stderr.
See also: - addListener:, - removeListener: (IKDependency)
sendAnnouncements
- (BOOL)sendAnnouncements
Returns YES if announcements are enabled, NO otherwise.
See also: - setSendAnnouncements:
setSendAnnouncements:
- setSendAnnouncements:(BOOL)flag
Enables or disables announcements. Returns self.
See also: - sendAnnouncements
usersAndListeners
- usersAndListeners
Returns the list of users and listeners for the IKAnnouncer.
See also: - numUsers
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.