AlMessage

Synopsis

#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 );

Description

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.

AlMessageTypeHandle::AlMessageTypeHandle( void )

Description

Default constructor.

AlMessageTypeHandle::AlMessageTypeHandle( const AlMessageTypeHandle& h )

Description

Copy constructor.

AlMessageTypeHandle::~AlMessageTypeHandle()

Description

Destructor.

AlMessageTypeHandle& AlMessageTypeHandle::operator =(const AlMessageTypeHandle& h )

Description

Assignment operator.

int AlMessageTypeHandle::type( void ) const

Description

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.

boolean AlMessageTypeHandle::isValid( void ) const

Description

Determines whether the given AlMessageTypeHandle represents a valid message type. This function should be called to verify that a call to AlMessage::addMessageType succeeded.

statusCode AlMessageTypeHandle::setPrologue( int (*func)( int, void * ) )

Description

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.

Arguments

< func - A pointer to the function to use as the prologue, or NULL to turn off the prologue

statusCode AlMessageTypeHandle::setEpilogue( int (*func)( int, void * ) )

Description

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.

statusCode AlMessageTypeHandle::addLock( boolean& b )

Description

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.

statusCode AlMessageTypeHandle::setAddLock( boolean b )

Description

Sets the add lock for this message type.

statusCode AlMessageTypeHandle::sendLock( boolean& b )

Description

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.

statusCode AlMessageTypeHandle::setSendLock( boolean b )

Description

Sets the send lock for this message type.

statusCode AlMessage::addMessageHandler( int msg, void * func )

Description

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.

Arguments

< 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!

Return Codes

sSuccess - handler installed successfully

sFailure - invalid message type, or installation of a duplicate handler

sInsufficientMemory - not enough memory

Comments

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.

Notes

(*) not currently available

(1) see the AlNotifyDagNode class for documentation

statusCode AlMessage::removeMessageHandler( int msg, void * func )

Description

Removes the callback handler corresponding to func, if it exists.

Arguments

< 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

Return Codes

sSuccess - handler removed successfully

sInvalidArgument - invalid message type, or handler does not exist

AlMessageTypeHandle AlMessage::addMessageType( const char * name )

Description

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).

int AlMessage::getMessageType( const char * name )

Description

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.

statusCode AlMessage::sendMessage( int type, void *data,AlMessage::AlPriorityType p )

Description

Sends a message.

Arguments

< 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.