messiah_command.h


Provides support for messiah commands and expression evaluation.

Version:
1.1
Date:
6/07/03
Topics
Description
In addition to providing functionality related to Command Modules, COMMAND also allows you to evaluate expressions on the fly. For example if you wanted to call an Function Module through the API and were interested in the return value from it, you could use one of the fxExpCompute* functions.
As an example suppose you wanted to create a Null object as a child of the currently selected object. You might choose to use the CreateTool Function Module. In order to execute this function and get it's return value (which is an FXobject) you would use fxExpComputeObj() as follows:

FXobject object = FX_NULLID;
fxExpComputeObj("CreateTool(\"Null\", \"Test_Obj\", 0, 1 )", &object);
The CreateTool Function Module and it's parameters are passed as the expression string and the result of the evaluation will be stored in object.
It is up to you to make sure that you pass a valid expression string to the fxExpCompute* functions, and to be sure that the expression evaluates to the type of function you are using. For example if you use fxExpComputeImage() with an expression that evaluates to a FXvecd4 the results will be undefined.


Command Classification Macros

These macros are used to classify commands as they are registered. You should choose a classification that best describes the behavior of the command you are registering. Inside of messiah in the Customize->KeyCommandManager module all commands are listed in a list box grouped under these classifications.

#define FX_COMCLASS_GENERAL
 General Command Classification.

#define FX_COMCLASS_FILE
 Commands are related to File mode.

#define FX_COMCLASS_MOTION
 Commands affect object's motions.

#define FX_COMCLASS_IK
 Commands affect object's IK properties.

#define FX_COMCLASS_OBJECT
 Commands relate to object manipulation.

#define FX_COMCLASS_TOOL
 Commands relate to tool creation and manipulation.

#define FX_COMCLASS_EFFECT
 Commands relate to Effects.

#define FX_COMCLASS_SHADER
 Commands relate to Shaders.

#define FX_COMCLASS_SETUP
 Commands are related to Setup mode.

#define FX_COMCLASS_RENDER
 Commands are related to Render mode.

#define FX_COMCLASS_PLAY
 Commands are related to Play mode.

#define FX_COMCLASS_COMMAND
 Commands are related to Command mode.

#define FX_COMCLASS_COMPOSE
 Commands are related to Compose mode.

#define FX_COMCLASS_INTERFACE
 Commands relate to user interface manipulation.

#define FX_COMCLASS_ARMATURE
 Commands relate to Armatures or Actions.


Command Registration and Execution



FXcommand fxCommandRegister (FXchar *name, FXchar *command_class, FXchar *command, FXint flags)
 Register a command module.

FXint fxCommandExecute (FXcommand command, FXchar *command_name, FXint flags)
 Execute an existing command either by name or command ID.


Expression Evaluation Functions

These functions are used to evaluate any valid messiah expression. These expressions may call messiah function or commands and may be as complex as you choose. Several variants of these functions exist for differnt data types. evaluates to. For instance, if you know the expression will evaluate to an int, then you would use the fxExpComputeInt() function. If you are not concerned with the value of the expression you can use the fxExpressionCompute() function.
Parameters:
exp [in] String representation of the expression to be evaluated
var [out] Storage for the value that the expression evaluates to (type varies by function)
buffer_length [in] In the case of fxExpComputeString(), this is the length of var
Return values:
FX_TRUE on success
FX_FALSE on failure


FXint fxExpressionCompute (FXchar *exp, FXint flags)
 Evaluate an expression without regard to it's return value.

FXint fxExpComputeInt (FXchar *exp, FXint *var)
 Compute an expression that evaluates to an FXint.

FXint fxExpComputeDouble (FXchar *exp, FXdouble *var)
 Compute an expression that evaluates to an FXdouble.

FXint fxExpComputeFloat (FXchar *exp, FXfloat *var)
 Compute an expression that evaluates to an FXfloat.

FXint fxExpComputeVeci3 (FXchar *exp, FXveci var)
 Compute an expression that evaluates to an FXveci.

FXint fxExpComputeVecd3 (FXchar *exp, FXvecd var)
 Compute an expression that evaluates to an FXvecd.

FXint fxExpComputeVecf3 (FXchar *exp, FXvecf var)
 Compute an expression that evaluates to an FXvecf.

FXint fxExpComputeVeci4 (FXchar *exp, FXveci4 var)
 Compute an expression that evaluates to an FXveci4.

FXint fxExpComputeVecd4 (FXchar *exp, FXvecd4 var)
 Compute an expression that evaluates to an FXvecd4.

FXint fxExpComputeVecf4 (FXchar *exp, FXvecf4 var)
 Compute an expression that evaluates to an FXvecf4.

FXint fxExpComputeCharRGB (FXchar *exp, FXchar *var)
 Compute an expression that evaluates to an FXchar.

FXint fxExpComputeCharRGBA (FXchar *exp, FXchar *var)
 Compute an expression that evaluates to an FXchar.

FXint fxExpComputeChar (FXchar *exp, FXchar *var)
 Compute an expression that evaluates to an FXchar.

FXint fxExpComputeString (FXchar *exp, FXchar *var, FXint buffer_length)
 Compute an expression that evaluates to an FXchar *.

FXint fxExpComputeObj (FXchar *exp, FXobject *var)
 Compute an expression that evaluates to an FXobject.

FXint fxExpComputeImage (FXchar *exp, FXimage *var)
 Compute an expression that evaluates to an FXimage.

FXint fxExpComputeVoid (FXchar *exp, FXvoid **var)
 Compute an expression that evaluates to an FXvoid *.

FXint fxExpComputeInt64 (FXchar *exp, FXint64 *var)
 Compute an expression that evaluates to an FXint64.


Function Documentation

FXint fxCommandExecute FXcommand    command,
FXchar   command_name,
FXint    flags
 

Execute an existing command either by name or command ID.

Parameters:
command [in] An existing FXcommand (returned by fxCommandRegister())
command_name [in] Name of an existing command
flags [in] Reserved for furure use
Return values:
FX_TRUE on success
FX_FALSE on failure
This function will execute a previously registered command. If you have a valid FXcommand, you can use it as the command argument and pass NULL as the command_name argument. Conversely if you only have a command's name then you would pass it as command_name and pass FX_NULLID as command. It is more efficent to execute a command by FXcommand ID rather than by name since no string comparisons will need to take place.

FXcommand fxCommandRegister FXchar   name,
FXchar   command_class,
FXchar   command,
FXint    flags
 

Register a command module.

Parameters:
name [in] The name of this command, by which it will be identified to the user
command_class [in] Command classification, one of: Command Classification Macros
flags [in] Reserved for furure use
Return values:
FXcommand that uniquely identifies this command.
FX_NULLID on failure
Use this function to register your command with messiah in your messiahEntry() function.


© 2003 pmG WorldWide, LLC.


www.projectmessiah.com

groups.yahoo.com/pmGmessiah

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