Class for creating the OpenAlias interface to Alias.
#include <AlFunction.h> class AlFunction virtual ~AlFunction(); statusCode deleteObject(); virtual AlMomentaryFunction* asMomentaryFunctionPtr(); 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 createGoButton( int (*pressed)( void ), boolean persistence, const char *button1, const char *button2 = NULL, const char *button3 = NULL, const char *button4 = NULL, const char *button5 = NULL ); static statusCode clearGoButton( boolean ); static const char * goButtonPressed( void ); static statusCode setUndoFunction( AlUndoCallbackType ); static AlUndoCallbackType undoFunction( void ); boolean isActiveContinuousFunction(); 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 Transform->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 (for example, reading option box values, making a list of picked items and so on).
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 and so on) 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.
Hybrid functions: Pseudo-momentary
By definition, a momentary function just does 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 does 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 Transform->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 );
Pre-init and post-cleanup callbacks:
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 (for example, 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.
statusCode AlMomentaryFunction::create( const char *funcName, void (*action)(void))
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.
that is, If you name your function ’fuzzyNavel’, then the icon file should be called ’fuzzyNavel.S’
statusCode AlMomentaryFunction::create( void (*action)(void) )
statusCode AlContinuousFunction::create( void (*init)( void ), AlMouseButtonFunction *down, AlMouseButtonFunction *move, AlMouseButtonFunction *up, void (*cleanup)( void ), boolean manipulatesPickList )
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
statusCode AlContinuousFunction::create( const char *name, void (*init)( void ), AlMouseButtonFunction *down, AlMouseButtonFunction *move, AlMouseButtonFunction *up, void (*cleanup)( void ), boolean manipulatesPickList )
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
statusCode AlContinuousFunction::setBehaviour( AlBehaviourType type )
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.
statusCode AlContinuousFunction::setPreInitFunction( void (*preInit)() )
statusCode AlContinuousFunction::setPostCleanupFunction( void (*postCleanup)() )
statusCode AlContinuousFunction::setPrompt( const char *(*outputStringFunc)(), char *inputBuffer, AlFilterType filter )
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’ */
statusCode AlContinuousFunction::setPrompt( const char *staticPrompt, char *inputBuffer, AlFilterType filter )
AlInputType AlContinuousFunction::translateInput( int event, int &button )
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;
int AlContinuousFunction::inputModifierMask()
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
statusCode AlContinuousFunction::createGoButton( void (*pressed)( void ) )
Creates a ’Go’ button for the user to press. The given function is called when the button is pressed.
sInvalidArgument - pressed was NULL
sSuccess - a ’Go’ button is now displayed
statusCode AlContinuousFunction::createGoButton( int (*pressed)( void ), boolean persistence,
const char *button1, const char *button2,
const char *button3, const char *button4, const char *button5 )
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
statusCode AlContinuousFunction::setUndoFunction( AlUndoCallbackType funcPtr )
This method sets an undo function for the plug-in and will only work if called when a continuous plug-in is active. With a non-null funcPtr, the Undo menu item will be enabled and funcPtr will be called when the menu it is invoked. Calling this function with a NULL funcPtr will disable the undo menu entry. The plug-in must keep track of its private undo stack in order to determine when the undo entry should be disabled.
Note: funcPtr is defined to return an int. This return value is currently unused in Alias.