Class for creating the OpenAlias interface to Alias.
#include <AlFunction.h>
class AlFunction
virtual ~AlFunction();
statusCode deleteObject();
virtual AlContinuousFunction* asContinuousFunctionPtr();
const char * name();
class AlMomentaryFunction : public AlFunction
virtual AlMomentaryFunction* asMomentaryFunctionPtr();
statusCode create( const char *, void (*)( void ));
statusCode create( void (*)(void) );
class AlContinuousFunction : public AlFunction
virtual AlContinuousFunction* asContinuousFunctionPtr();
statusCode create( void (*)( void ), AlMouseButtonFunction *, AlMouseButtonFunction *, AlMouseButtonFunction *, void (*)( void ), boolean = FALSE );
statusCode create( const char *, void (*)( void ), AlMouseButtonFunction *, AlMouseButtonFunction *, AlMouseButtonFunction *, void (*)( void ), boolean = FALSE );
statusCode setPreInitFunction( void (*)() );
statusCode setPostCleanupFunction( void (*)() );
statusCode setPrompt( const char *, char *, AlFilterType );
statusCode setPrompt( const char *(*)(), char *, AlFilterType );
statusCode setBehaviour( AlBehaviourType );
statusCode setMouseCoordinateType( AlCoordinateType );
AlBehaviourType behaviour() const;
static statusCode createGoButton( void (*)( void ) );
static statusCode clearGoButton( boolean );
static AlCoordinateType keyboardCoordinateMode();
static AlInputType translateInput( int, int & );
static int inputModifierMask(); // see kModifier_xxxx
statusCode finished();
This class provides a means to interface the OpenAlias application to the Alias user interface.
The UI interacts with the plug-in through the use of callback functions. The plug-in supplies pointers to functions that are called whenever a menu button is pressed or the mouse moves. There are two classes of UI functions (the set of callbacks associated with a menu button): momentary functions and continuous functions.
A true momentary function just executes an operation and then returns to the previous function. Momentary functions are used for 'one shot' type operations. The function does not require any user input, and simply returns after it is done. An example of a momentary function is Xform->undo.
A continuous function is a set of 5 callback functions that correspond to the stages involved in a mouse interaction. They are the 'init' function, the mouse down function, the mouse move function, the mouse up function and the cleanup function.
The init function is called when you first switch to the UI function by clicking on the menu item. It does not take any arguments, and is intended for setting up any data required for the operation (e.g. reading option box values, making a list of picked items etc.).
The cleanup function is called when the user leaves this UI function by selecting another menu item. You will usually clean up the data structures that are set up in the init function.
The mouse down function is called when the user depresses the mouse button. The mouse move function is called each time the mouse is moved from its current position. Note that this function will be called immediately after the init function. A mouse 'session' will always contain one call to the down function, one or more calls to the move function followed by a call to the mouse up function.
The mouse up function is called when the mouse button is released. The mouse down/move/up functions are passed by three arguments: the event information (a packed value containing information about the mouse buttons, keyboard keys etc.) and the x/y position of the mouse when the event occurred (use AlContinousFunction::translateInput to extract the values). If a keyboard event is read, then use scanf() to process the values read from the command line. Otherwise, the mouse was clicked down on the screen. The button in question can be determined by examining the Modifier masks on the value returned by translateInput.
By definition, a momentary function just performs an action and then returns to the previous function. No user input (mouse or keyboard) should be processed in a momentary function.
A continuous function performs the action, and that function stays current until you select another function. These types of functions can have mouse or keyboard input.
There are circumstances which require a momentary style function but we want to also provide mouse or keyboard input. For example 'set keyframe' requires keyboard input, so it should be continuous.
However, it can become cumbersome for the user to use. Consider the following sequence of events to set the keyframe while Xform->move is selected.
This is the purpose behind the AlFunction::setBehaviour method. It makes a continuous function behave as a momentary function, but also allows the users to provide us with keyboard or mouse input. After the function has been executed, it switches back to the previous function.
Instead of declaring the 'set keyframe' function using ..
AlMomentaryFunction::create( do_set_keyframe );
AlContinuousFunction::create( NULL, // init.
down_set_keyframe, // reads the keyboard input
NULL,
up_set_keyframe,
NULL // cleanup );
AlContinuousFunction::setPrompt( "Enter frame: %f", frame_buff, kFilterNone );
AlContinousFunction::setBehaviour( kBehaviourMomentary );
There are also settable 'pre-init' and 'post-cleanup' routines. The pre-init is called before the init but it is only called on the initial selection of the function and not when you 'bounce' back to the function after selecting a function (e.g. another momentary style function).
Note: Due to the original design of the UI, there is no way to pass a user data pointer to the five functions without using globals.
Deletes a function wrapper object.
Type casts the given object to a momentary function.
Type casts the given object to a continuous function.
Type casts the given object to a momentary function.
Type casts the given object to a continuous function.
Returns the name of the function.
Frees the memory used by the given function.
sSuccess - the function was removed
sFailure - the function could not be removed
sObjectInvalid - this function is not valid
Creates a momentary function by creating an association of the given name with the given function.
NOTE - to get an icon to load with your function, the name of the icon file must be the same as the function name with a '.S' or '.M' appended. If the return code sNameChangedToUniqueOne is returned, then your function name will be altered slightly, to prevent a collision. As a result, it is possible that it does not match your icon filename so the icon may not appear.
i.e. If you name your function 'fuzzyNavel', then the icon file should be called 'fuzzyNavel.S'
< funcName - the name for the function
< action - the action function to attach the name to
sInvalidArgument - name or function was NULL
sSuccess - the momentary function was created
sFailure - the momentary function could not be created
sNameChangedToUniqueOne - the given function name was changed to a unique name. Use name() to find out what.
Creates a momentary function from the given function. (No icon will be shown by default).
< name - the name of the function
sInvalidArgument - name or function was NULL
sSuccess - the momentary function was created
sFailure - the momentary function could not be created
Creates a continuous function. Action functions may be NULL. If this continuous function will modify the pick list, then set the 'manipulatesPickList' parameter to TRUE. This will turn off the triggering of unwanted internal Alias events when the picklist is modified and will make the continuous function safer.
< init - the routine to be called when the function is invoked
< down - the routine to be called when the mouse button is depressed
< move - the routine to be called when the mouse is moved with the button depressed
< up - the routine to be called when the mouse button is released
< cleanup - the routine called when the interaction is completed
< manipulatesPickList - TRUE or FALSE
sInvalidArgument - one of the parameters was null
sFailure - the function could not be created
sNameChangedToUniqueOne - success but the name was altered
sSuccess - the function was created
Creates a continuous function. Action functions may be NULL. If this continuous function will modify the pick list, then set the 'manipulatesPickList' parameter to TRUE. This will turn off the triggering of unwanted internal Alias events when the picklist is modified and will make the continuous function safer.
See the note in AlMomentaryFunction::create() on naming functions.
< name - the name of the function
< init - the routine to be called when the function is invoked
< down - the routine to be called when the mouse button is depressed
< move - the routine to be called when the mouse is moved with the button depressed
< up - the routine to be called when the mouse button is released
< cleanup - the routine called when the interaction is completed
< manipulatesPickList - TRUE or FALSE
sInvalidArgument - one of the parameters was null
sFailure - the function could not be created
sNameChangedToUniqueOne - success but the name was altered
sSuccess - function was created
Selects relative or absolute mouse coordinate types.
< type - kCoordinateAbsolute or kCoordinateRelative
sInvalidArgument - type was not a valid coordinate type
sFailure - coordinate type could not be set
sSuccess - coordinate type was set
sInvalidObject - the function was not created
Used in conjunction with the setBehaviour() method to allow a continuous function to act like a momentary function. Calling this function will pop the current function back to which function was set before this function was invoked.
sFailure - function could not be set
Selects the continuous behaviour type (either continuous or pseudo momentary). This function makes it possible to have a continuous function act like a momentary function. A call to setBehaviour() would be made setting the type to be kBehaviourMomentary and when the continuous function operation is completed (mouse up or after go pressed ), the finished() method would need to be called.
< type - kBehaviourContinuous or kBehaviourMomentary
sInvalidArgument - type was not a valid behaviour type
sFailure - behaviour type could not be set
sSuccess - behaviour type was set
sInvalidObject - the function was not created
Returns the function's behaviour types.
Sets the function that is called when this function is selected. It behaves as a 'pre-init' function.
< preInit- the function to call when this function is selected
sInvalidArgument - a parameter was NULL
sSuccess - the set call worked
sInvalidObject - the continuous function was invalid
Sets the function that is called when this function is unselected. It behaves as a 'post-cleanup' function. Post-cleanup functions are not called during momentary function interruptions
< postCleanup - the function to call when this function is selected
sInvalidArgument - a parameter was NULL
sSuccess - the set call worked
sInvalidObject - the continuous function was invalid
Sets the function to create the string that will be placed into the prompt line. It is also used to determine how data is retrieved from the prompt line. The text up to the first '%' is printed to the prompt line. The remaining text is used to control the input. For example, if the outputStringFunc() returns the string, "Enter the coordinate: %f %f %f", then "Enter the coordinate:" is printed to the prompt line, and three doubles are read in from the user. inputString is a pointer to a character buffer that is filled when the user types information into the prompt line. For example,
char *outputStringFunc()
{
return "Enter coordinate: %f %f %f";
}
char inputBuffer[200]; /* accepts the 'coordinate' */
< outputStringFunc - a function which returns the string to be printed on the command line
< inputBuffer - buffer to be used for input
< filter - the units filter for the input
sInvalidArgument - a parameter is null
sInvalidObject - the continuous function is invalid
Sets a static prompt instead of a computable prompt.
< staticPrompt - the static string to display in the prompt line
< inputBuffer - buffer to be used for input
< filter - the unit filter for the string
sInvalidArgument - a parameter is null
sInvalidObject - the continuous function is invalid
Interprets an input event. This method translates the raw event information into API input types. In addition, if the input type was a button then the button pressed would be returned via the reference parameter. Keyboard input is handled by using sscanf() on your inputDataBuffer. The input buffer is installed by using the AlContinuousFunction::setPrompt() method.
< event - input event(first parameter) of the continuous function callbacks.
> button - if the event type is kInputButton, then the button reference is a bitwise OR of the following values:
Example code:
AlContinuousFunction hFunc;
hFunc.setPrompt( my_prompt, inbuf, kFilterNone );
......
char dataBuffer[200];
promptInfo( "Input offset %f", dataBuffer );
case kInputKeyboard
sscanf( dataBuffer, "%lf", &newOffset );
break;
kInputAbort - the abort key was hit
kInputKeyboard - keyboard input was detected (see the above source example)
kInputButton - input was from a button.
Examines the current state of the modifier keys and button states. Note that this value is only updated between X events, hence it cannot be polled.
A bitwise OR of the following values
kModifierButton1 - button 1 was depressed
kModifierButton2 - button 2 was depressed
kModifierButton3 - button 3 was depressed
kModifierButton4 - button 4 was depressed
kModifierButton5 - button 5 was depressed
kModifierControl - the Control key was depressed
kModifierShift - the Shift key was depressed
kModifierAlt - the Alt key was depressed
Returns the coordinate type of the user's numerical input (either kCoordinateAbsolute or kCoordinateRelative).
Creates a 'Go' button for the user to press. The given function is called when the button is pressed.
pressed - the callback to call
sInvalidArgument - pressed was NULL
sSuccess - a 'Go' button is now displayed
Clears the 'Go' button if it is displayed.
do_redraw - a redraw should be performed to update the display
sSuccess - the 'Go' button was cleared