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.
statusCode AlMessageTypeHandle::setPrologue( int (*func)( int, void * ) )
statusCode AlMessage::addMessageHandler( int msg, void * func )
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.
statusCode AlMessage::removeMessageHandler( int msg, void * func )
< 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
AlMessageTypeHandle AlMessage::addMessageType( const char * name )
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).
statusCode AlMessage::sendMessage( int type, void *data,AlMessage::AlPriorityType p )
< 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.