Encapsulates the handling of object messages.
#include <AlMessage.h>
class AlMessageTypeHandle
AlMessageTypeHandle( void );
AlMessageTypeHandle( const AlMessageTypeHandle& );
~AlMessageTypeHandle();
AlMessageTypeHandle& operator =( const AlMessageTypeHandle& );
boolean isValid( void ) const;
int type( void ) const;
statusCode setPrologue( int (*)( int, void * ) );
statusCode setEpilogue( int (*)( int, void * ) );
statusCode addLock( boolean& );
statusCode setAddLock( boolean );
statusCode sendLock( boolean& );
statusCode setSendLock( boolean );
class AlMessage
enum AlPriorityType {
kImmediate,
kQueue,
kIdleQueue
};
static statusCode addMessageHandler( int, void * );
static statusCode removeMessageHandler( int, void * );
static AlMessageTypeHandle addMessageType( const char * );
static int getMessageType( const char * );
static statusCode sendMessage( int, void*, AlPriorityType = kImmediate );
This file contains the definitions required to handle object messages for Alias objects. A message handler is a user supplied function that is called when an event occurs.
A message handler is installed using the AlMessage::addMessageHandler() function. Below is a sample message handler to handle the deleting of DagNodes:
void myDagNodeDeleteHandler( int msgtype, AlDagNode *dagnode )
{
do_something_before_its_deleted( dagnode );
}
To install the handler into the universe, the following function call would be made in the application’s initialization code:
AlMessage::addMessageHandler( kMessageDagNodeDeleted, myDagNodeDeleteHandler );
If either Alias or the application deletes a DAG node by using AlDagNode.deleteObject(), the message handler will be called with a pointer to the dagnode before the dagnode is removed.
In addition to being able to receive standard messages from inside Alias, it is possible to define custom message types that extend the default set. Of course, Alias has no prior knowledge of these new types, so hooks cannot be added into existing code to send new messages, but plug-ins can define messages that can then be received by either the same plug-in, or different plug-ins altogether.This allows a collaborative paradigm between plug-ins, such as sharing code or data.
To create a custom message type, call AlMessage::addMessageType. You must supply a name for this type, which is then used by others to find the type. You are returned an AlMessageTypeHandle, a receipt which the creator of the message type can then use to define specific properties of the message type. In particular, the owner can lock a message type against the addition of handlers, lock the type against the sending of messages, and set prologue and epilogue functions, which get called before and after the sending of a message. See the documentation for the individual member functions for more details.
Note that while a method is supplied to send a message, this method applies only to user-defined messages. Predefined Alias messages cannot be sent.
Default constructor.
Copy constructor.
Destructor.
Assignment operator.
Returns the integer type associated with this message type. This is the equivalent of calling AlMessage::getMessageType with the name of the message type. This type can then be used to send messages.
Determines whether the given AlMessageTypeHandle represents a valid message type. This function should be called to verify that a call to AlMessage::addMessageType succeeded.
Sets the prologue function for this message type. The holder of the AlMessageTypeHandle is allowed to define a function which gets called before any of the message handlers are called. If the prologue returns a non-zero value, the message handlers will not be called at all.
< func - A pointer to the function to use as the prologue, or NULL to turn off the prologue
Like the setPrologue, this allows the creator of the message type to set a function that gets called after the message handlers are all called.
Message types can be locked by the creator against the adding of handlers. This allows the creator to control who is able to receive the given message type. This function places the current state of the add lock into the passed-in argument.
Sets the add lock for this message type.
Message types can be locked by the creator against the sending of messages. This allows the creator to control who is able to send a message of the given type. This function places the current state of the send lock into the passed-in argument.
Sets the send lock for this message type.
Adds a message handler for the given message type. Only certain message types will actually be recognized and allowed for external use. Some message types simply do not make sense in OpenModel.
< msg - The type of the message for which to install a handler. For a list of types, see the AlMessage type enumerated type.
< func - A pointer to the function to install as a handler. Ensure the argument list of the handler matches this message type!
sSuccess - handler installed successfully
sFailure - invalid message type, or installation of a duplicate handler
sInsufficientMemory - not enough memory
Below is a list of prototypes to use for the handler function for the various message types.
Message |
Handler prototype (see AlMessage.h) |
kMessageAnimPlayback |
AlCallbackInt |
kMessageAttributesDelete |
AlCallbackAttributes |
kMessageCameraModified |
AlCallbackOneCamera |
kMessageClMemberModified |
AlCallbackOneDagNode |
kMessageCloudDeleted |
AlCallbackOneCloud |
kMessageCnetDeleted |
--- (*) |
kMessageCommandFree |
--- (*) |
kMessageCommandInstall |
--- (*) |
kMessageCommandUnInstall |
--- (*) |
kMessageCosDeleted |
AlCallbackCurveOnSurface |
kMessageCosModified |
AlCallbackCurveOnSurface |
kMessageCosVisible |
AlCallbackCurveOnSurface |
kMessageTextureModified |
AlCallbackOneTexture |
kMessageTextureAdded |
AlCallbackOneTexture |
kMessageTextureDeleted |
AlCallbackOneTexture |
kMessageShaderAdded |
AlCallbackOneShader |
kMessageShaderDeleted |
AlCallbackOneShader |
kMessageDagInserted |
AlCallbackOneDagNode |
kMessageDagNameModified |
AlCallbackOneDagNode |
kMessageDagNodeApplyTransformation |
AlCallbackDagNodeAndMatrix |
kMessageDagNodeDeleted |
AlCallbackOneDagNode |
kMessageDagNodeInstanced |
AlCallbackTwoDagNodes |
kMessageDagNodeModified |
AlCallbackOneDagNode |
kMessageDagNodeModifiedConstraint |
AlCallbackOneDagNode |
kMessageDagNodeModifiedGeometry |
AlCallbackOneDagNode |
kMessageDagNodePreReplaceGeometry |
AlCallbackOneDagNode |
kMessageDagNodeReplaceGeometry |
AlCallbackOneDagNode |
kMessageDagNodeVisible |
AlCallbackOneDagNode |
kMessageDeleteAll |
AlCallbackInt |
kMessageExprModified |
AlCallbackOneDagNode |
kMessageHierarchyModified |
AlCallbackOneDagNode |
kMessageJointModified |
AlCallbackOneDagNode |
kMessageLightModified |
AlCallbackOneLight |
kMessageListModifiedNodes |
AlCallbackPickListModified (1) |
kMessagePickListModified |
AlCallbackVoid |
kMessagePlotRefresh |
--- (*) |
kMessagePostRetrieve |
AlCallbackVoid |
kMessagePostStore |
AlCallbackVoid |
kMessagePostUpdate |
AlCallbackInt |
kMessagePreRefresh |
AlCallbackVoid |
kMessagePreRetrieve |
AlCallbackString |
kMessagePreStore |
AlCallbackStringInt |
kMessagePreUpdate |
AlCallbackInt |
kMessageQuit |
AlCallbackVoid |
kMessageRefresh |
--- (*) |
kMessageStageActive |
AlCallbackVoid |
kMessageStageCreated |
AlCallbackVoid |
kMessageStageDeleted |
AlCallbackVoid |
kMessageStageMerged |
AlCallbackVoid |
kMessageTrimSurface |
AlCallbackSurface |
kMessageUntrimSurface |
AlCallbackSurface |
kMessageUpdate |
AlCallbackUpdate |
For custom message types, the type of the function is always the same
void (*)( int type, void * data )
where type is the type of the message and data is the data to send with the message.
Removes the callback handler corresponding to func, if it exists.
< msg - the type of the message for which func was installed.
For a list of types, see the AlMessageType enumerated type.
< func - a pointer to the function to attempt to remove
sSuccess - handler removed successfully
sInvalidArgument - invalid message type, or handler does not exist
Creates a custom message type. Calling this function introduces a new message type of the given name into Alias, provided a message type of that name does not already exist. The caller is returned a ’receipt’ which can then be used to fine-tune the message-passing capabilities of this message type (see AlMessageTypeHandle).
Searches the list of existing custom named message types for the given name. If a message type of that name is found, its number is returned, which can then be used to send and receive messages of that type. Otherwise, this function returns -1.
Sends a message.
< type - The type of the message to send. The type must correspond to a custom message type.
< data - The data to send with the message. All the message handlers in the message type’s list will receive a pointer to this data when the message is sent.
< p - The priority of the message. Messages marked kImmediate will be sent immediately - that is, through function call.
kQueue messages go into Alias’s internal event queue, and the message handlers will all be queued when the event corresponding to sending the message is processed. kIdleQueue messages go into Alias’s internal idle queue. Messages in the idle queue get processed when Alias is waiting for events.
Note that only kImmediate is available in OpenModel.