messiah_action.h


Provides Action related information and manipulation.

Version:
1.1
Date:
6/07/03
Topics


Action Module Types

These macros identify how an Action will execute, whether it will be a one time operation such as in response to a mouse click, or continuous as in response to a mouse drag. You can set the Action Module Type of your Action by calling fxInitAction() in response to S_MODULE_INIT().

#define FX_ACTMODULE_ONETIME
 Executes once based on mouse click or other one-time operation.

#define FX_ACTMODULE_FULLTIME
 Executes based on mouse drag or other interactive/real-time operation.

#define FX_ACTMODULE_CLICK
 Synonym for FX_ACTMODULE_ONETIME().

#define FX_ACTMODULE_DRAG
 Synonym for FX_ACTMODULE_FULLTIME().


Action Module Data Classes

There are three ways an action can process, one is by executing a Command Module, another is by running an "action script", and the last is by notifying an Action to process (ACT_PROCESS()). All Actions created with messiahAPI are FX_ACTCLASS_MODULE() types. All Actions created with scripts are FX_ACTCLASS_SCRIPT() types.

#define FX_ACTCLASS_COMMAND
 Built in Command action.

#define FX_ACTCLASS_SCRIPT
 Action created with a script.

#define FX_ACTCLASS_MODULE
 Action created through messiahAPI.


Action Types

These macros represent the types of events that can cause an Action to process. You can retrieve the current Action Type of an Action by calling fxActionType(), to change the type you would call fxActionTypeSet().

#define FX_ACTTYPE_DRAG
 Mouse is dragging a handle.

#define FX_ACTTYPE_MOUSEDOWN
 Mouse button down over handle.

#define FX_ACTTYPE_DOUBLECLICK
 Double click on handle.

#define FX_ACTTYPE_MOUSEIN
 Mouse has entered the bounding box of the handle's icon.

#define FX_ACTTYPE_MOUSEOUT
 Mouse has left the bounding box of the handle's icon.

#define FX_ACTTYPE_MOUSEUP
 Mouse button released over handle.

#define FX_ACTTYPE_LOSEFOCUS
 Handle has lost focus (another handle was selected).


Initialization and Creation Functions



FXint fxInitAction (FXint action_module)
 Initialized an Action in response to S_MODULE_INIT().

FXhandle fxActionCreate (FXentity target, FXint action_class, FXint action_type, FXchar *action_name, FXint flags)
 Creates a new Action instance.


Action Info Functions



FXvoidfxActionFormatData (FXaction, FXint flags)
 UNKNOWN.

FXint fxActionType (FXaction action, FXint *a_type)
 Retrieves the Action Type of the Action.

FXint fxActionTypeSet (FXaction action, FXint a_type)
 Sets the Action Type of the Action.

FXint fxActionClass (FXaction action, FXint *a_class)
 Retrieves the Action Module Data Class of the Action.


Action Hierarchy Functions



FXaction fxActionFirst (FXentity target, FXint flags)
 Returns the first Action attached to the target.

FXaction fxActionNext (FXaction action, FXint flags)
 Returns the next Action after action.

FXaction fxActionPrev (FXaction action, FXint flags)
 Returns the next Action before action.

FXint fxActionSetSibling (FXaction action, FXaction sibID, FXint flags)
 Re-orders action so that it is the sibling of sibID.


Action Handle Functions



FXhandle fxActionHandle (FXaction action, FXint flags)
 Retrieve the FXhandle to which action is attached.

FXint fxActionSetHandle (FXaction action, FXhandle handle, FXint flags)
 Set the handle to which action is attached.


Action Mouse Functions



FXint fxActionMouse (FXaction action, FXint button, FXint *channel, FXint *coord_sys, FXint *mouse_flags, FXint *flags)
 Gets the current mouse related settings for the specified action.

FXint fxActionMouseSet (FXaction, FXint button, FXint channel, FXint coord_sys, FXint mouse_flags, FXint flags)
 Gets the current mouse related settings for the specified action.

FXint fxActionMouseButton (FXint flags)
 DESC.


Action Options Functions



FXint fxActionOptions (FXaction action, FXint *opt, FXint flags)
 DESC.

FXint fxActionOptionsSet (FXaction action, FXint opt, FXint flags)
 DESC.

FXint fxActionOptionsClear (FXaction action, FXint opt, FXint flags)
 DESC.


Function Documentation

FXint fxActionClass FXaction    action,
FXint   a_class
 

Retrieves the Action Module Data Class of the Action.

Parameters:
action [in] The Action to get info from
a_type [out] Storage for variable to hold Action Module Data Class value
Return values:
FX_TRUE on success
FX_FALSE on failure

FXhandle fxActionCreate FXentity    target,
FXint    action_class,
FXint    action_type,
FXchar   action_name,
FXint    flags
 

Creates a new Action instance.

Parameters:
target [in] Entity that you want the action attached to (e.g. Armature handle)
action_class [in] Action Module Data Class
action_type [in] Action Type
action_name [in] Name of the action you are creating
flags [in] Reserved for future use
Returns:
The ID of the newly created Action instance. Upon failure FX_NULLID is returned.
To create a new Action instance you must first specify which Entity the action is to be attached to (currently only FXhandle type Entities are supported).
Next you must pass the Action Module Data Class the instance belongs to as action_class. If the action you want to create an instance of was written with a script then you should pass FX_ACTCLASS_SCRIPT(). If the action was written with messiahAPI then you would pass FX_ACTCLASS_MODULE(). Finally if the action you want to create an instance of is the builtin Command action then you would pass FX_ACTCLASS_COMMAND().
The action_type indicates which event you want to trigger the action instance.
The action_name param is the name of the Action you want to create the instance of (not the name of the instance). So if you had written an Action with messiahAPI called "MyAction" and wanted to create an instance of it, then you would use the following:

FXaction act = fxActionCreate( handle, FX_ACTCLASS_MODULE, FX_ACTTYPE_CLICK, "MyAction", FX_NOFLAG );
If the Action Module Data Class is FX_ACTCLASS_COMMAND(), then action_name is the name of the command that you want executed when the instance is triggered.

FXint fxActionMouse FXaction    action,
FXint    button,
FXint   channel,
FXint   coord_sys,
FXint   mouse_flags,
FXint   flags
 

Gets the current mouse related settings for the specified action.

Parameters:
action [in]
button [in] value that indicates the desired mouse button to get settings from, See Flag Values Below
channel [out] User Allocated FXint to hold single channel identifier (e.g. FX_CHAN_0, FX_X_POSITION etc. )
coord_sys [out] User Allocated FXint to hold coordinate system setting, See Flag Values Below
mouse_flags [out] User Allocated FXint to hold mouse flags (e.g. motion group), See Flag Values Below
flags [out] User Allocated FXint to hold flags (e.g. mute setting), See Flag Values Below
Return values:
FX_TRUE on success
FX_FALSE on failure
ActionMouseDiagram.gif
Flag Values: button
FX_HANMBUTTON_LEFT() left mouse button
FX_HANMBUTTON_MIDDLE() middle mouse button
FX_HANMBUTTON_RIGHT() right mouse button
Flag Values: coord_sys
(Flags currently not available)
Flag Values: mouse_flags
(Flags currently not available)
Flag Values: flags
FX_ARMDATA_MUTE() If this bit is set then the action is muted on button
TODO: add example when coord_sys, and mouse_flags macros are added.

FXint fxActionMouseButton FXint    flags
 

DESC.

Parameters:
NAME [in] DESC
NAME [in] DESC
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure
DETAILS

FXint fxActionMouseSet FXaction   ,
FXint    button,
FXint    channel,
FXint    coord_sys,
FXint    mouse_flags,
FXint    flags
 

Gets the current mouse related settings for the specified action.

Parameters:
action [in]
button [in] value that indicates the desired mouse button to get settings from, See Flag Values Below
channel [in] single channel identifier (e.g. FX_CHAN_0, FX_X_POSITION etc. )
coord_sys [in] coordinate system setting, See Flag Values Below
mouse_flags [in] mouse flags (e.g. motion group), See Flag Values Below
flags [in] flags (e.g. mute setting), See Flag Values Below
Return values:
FX_TRUE on success
FX_FALSE on failure
ActionMouseDiagram.gif
Flag Values: button
FX_HANMBUTTON_LEFT() left mouse button
FX_HANMBUTTON_MIDDLE() middle mouse button
FX_HANMBUTTON_RIGHT() right mouse button
Flag Values: coord_sys
(Flags currently not available)
Flag Values: mouse_flags
(Flags currently not available)
Flag Values: flags
FX_ARMDATA_MUTE() If this bit is set then the action is muted on button
TODO: add example when coord_sys, and mouse_flags macros are added.

FXint fxActionOptions FXaction    action,
FXint   opt,
FXint    flags
 

DESC.

Parameters:
NAME [in] DESC
NAME [in] DESC
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure
DETAILS

FXint fxActionOptionsClear FXaction    action,
FXint    opt,
FXint    flags
 

DESC.

Parameters:
NAME [in] DESC
NAME [in] DESC
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure
DETAILS

FXint fxActionOptionsSet FXaction    action,
FXint    opt,
FXint    flags
 

DESC.

Parameters:
NAME [in] DESC
NAME [in] DESC
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure
DETAILS

FXint fxActionType FXaction    action,
FXint   a_type
 

Retrieves the Action Type of the Action.

Parameters:
action [in] The Action to get info from
a_type [out] Storage for variable to hold Action Type value
Return values:
FX_TRUE on success
FX_FALSE on failure

FXint fxActionTypeSet FXaction    action,
FXint    a_type
 

Sets the Action Type of the Action.

Parameters:
action [in] The Action to set
a_type [in] The new Action Type value
Return values:
FX_TRUE on success
FX_FALSE on failure

FXint fxInitAction FXint    action_module
 

Initialized an Action in response to S_MODULE_INIT().

Parameters:
action_module [in] Action Module Type
Return values:
FX_TRUE on success
FX_FALSE on failure
Call this function only while processing the S_MODULE_INIT() AN. You will use this to setup how your module will process. If it should only recieve ACT_PROCESS() messages once when a one-time event occurs such as a handle being clicked on or the mouse passing over a handle, then you should pass FX_ACTMODULE_ONETIME() as action_module. If however you want your module to recieve continuous ACT_PROCESS() messages when an interactive event is occuring, such as the handle being dragged, then you would pass FX_ACTMODULE_FULLTIME() as action_module.


© 2003 pmG WorldWide, LLC.


www.projectmessiah.com

groups.yahoo.com/pmGmessiah

Last Updated on Thu Jul 10 04:49:36 2003