AlFunction
 
 
 

Class for creating the OpenAlias interface to Alias.

Synopsis

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

Description

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.

  1. Transform->move is used to move a sphere
  2. set keyframe is selected and becomes the ’current’ function
  3. a value is entered into set keyframe
  4. the user must now click on Transform->move again to move the sphere.

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

We would use:

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

Then call:

     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.

AlFunction::~AlFunction()

Description

Deletes a function wrapper object.

AlMomentaryFunction* AlFunction::asMomentaryFunctionPtr()

Description

Type casts the given object to a momentary function.

AlContinuousFunction* AlFunction::asContinuousFunctionPtr()

Description

Type casts the given object to a continuous function.

const char *AlFunction::name()

Description

Returns the name of the function.

statusCode AlFunction::deleteObject()

Description

Frees the memory used by the given function.

Return Codes

sSuccess - the function was removed

sFailure - the function could not be removed

sObjectInvalid - this function is not valid

AlMomentaryFunction* AlMomentaryFunction::asMomentaryFunctionPtr()

Description

Type casts the given object to a momentary function.

statusCode AlMomentaryFunction::create( const char *funcName, void (*action)(void))

Description

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’

Arguments

< funcName - the name for the function

< action - the action function to attach the name to

Return Codes

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.

statusCode AlMomentaryFunction::create( void (*action)(void) )

Description

Creates a momentary function from the given function. (No icon will be shown by default).

Arguments

< name - the name of the function

Return Codes

sInvalidArgument - name or function was NULL

sSuccess - the momentary function was created

sFailure - the momentary function could not be created

AlContinuousFunction* AlContinuousFunction::asContinuousFunctionPtr()

Description

Type casts the given object to a continuous function.

statusCode AlContinuousFunction::create( void (*init)( void ), AlMouseButtonFunction *down, AlMouseButtonFunction *move, AlMouseButtonFunction *up, void (*cleanup)( void ), boolean manipulatesPickList )

Description

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.

Arguments

< 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

Return Codes

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

statusCode AlContinuousFunction::create( const char *name, void (*init)( void ), AlMouseButtonFunction *down, AlMouseButtonFunction *move, AlMouseButtonFunction *up, void (*cleanup)( void ), boolean manipulatesPickList )

Description

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.

Arguments

< 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

Return Codes

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

statusCode AlContinuousFunction::setMouseCoordinateType( AlCoordinateType type )

Description

Selects relative or absolute mouse coordinate types.

Arguments

< type - kCoordinateAbsolute or kCoordinateRelative

Return Codes

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

statusCode AlContinuousFunction::finished( )

Description

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.

Return Codes

sFailure - function could not be set

sSuccess - function was set

statusCode AlContinuousFunction::setBehaviour( AlBehaviourType type )

Description

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.

Arguments

< type - kBehaviourContinuous or kBehaviourMomentary

Return Codes

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

AlBehaviourType AlContinuousFunction::behaviour() const

Description

Returns the function’s behaviour types.

statusCode AlContinuousFunction::setPreInitFunction( void (*preInit)() )

Description

Sets the function that is called when this function is selected. It behaves as a ’pre-init’ function.

Arguments

< preInit- the function to call when this function is selected

Return Codes

sInvalidArgument - a parameter was NULL

sSuccess - the set call worked

sFailure - the method failed

sInvalidObject - the continuous function was invalid

statusCode AlContinuousFunction::setPostCleanupFunction( void (*postCleanup)() )

Description

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

Arguments

< postCleanup - the function to call when this function is selected

Return Codes

sInvalidArgument - a parameter was NULL

sSuccess - the set call worked

sFailure - the method failed

sInvalidObject - the continuous function was invalid

statusCode AlContinuousFunction::setPrompt( const char *(*outputStringFunc)(), char *inputBuffer, AlFilterType filter )

Description

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’ */

Arguments

< 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

Return Codes

sInvalidArgument - a parameter is null

sInvalidObject - the continuous function is invalid

sSuccess - the method worked

statusCode AlContinuousFunction::setPrompt( const char *staticPrompt, char *inputBuffer, AlFilterType filter )

Description

Sets a static prompt instead of a computable prompt.

Arguments

< staticPrompt - the static string to display in the prompt line

< inputBuffer - buffer to be used for input

< filter - the unit filter for the string

Return Codes

sInvalidArgument - a parameter is null

sInvalidObject - the continuous function is invalid

sSuccess - the method worked

AlInputType AlContinuousFunction::translateInput( int event, int &button )

Description

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.

Arguments

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

  • 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
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;

Return Values

kInputAbort - the abort key was hit

kInputKeyboard - keyboard input was detected (see the above source example)

kInputButton - input was from a button.

int AlContinuousFunction::inputModifierMask()

Description

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.

Return Values

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

AlCoordinateType AlContinuousFunction::keyboardCoordinateMode()

Description

Returns the coordinate type of the user’s numerical input (either kCoordinateAbsolute or kCoordinateRelative).

statusCode AlContinuousFunction::createGoButton( void (*pressed)( void ) )

Description

Creates a ’Go’ button for the user to press. The given function is called when the button is pressed.

Arguments

pressed - the callback to call

Return Codes

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 )

Description:

Creates a ’Go’ button for the user to press. The given function is called when the button is pressed.

Arguments:

pressed - the callback to call

Return codes:

sInvalidArgument - pressed was NULL

sSuccess - a ’Go’ button is now displayed

const char *AlContinuousFunction::goButtonPressed( void )

Description

Return the label name of the go button that was pressed.

statusCode AlContinuousFunction::clearGoButton( boolean do_redraw )

Description

Clears the ’Go’ button if it is displayed.

Arguments

do_redraw - a redraw should be done to update the display

Return Codes

sSuccess - the ’Go’ button was cleared

statusCode AlContinuousFunction::setUndoFunction( AlUndoCallbackType funcPtr )

Description

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.

Arguments

< funcPtr - callback for undo function

Return Codes

sFailure - could not set the undo callback. This could be due to not being in an active continuous plug-in

sSuccess - the method succeeded

AlUndoCallbackType AlContinuousFunction::undoFunction( )

Description

Returns the current undo function. This method should be used in conjunction with setUndoFunction() in order to preserve any existing undo function pointers.

boolean AlContinuousFunction::isActiveContinuousFunction()

Description

Returns true if this continuous function is currently active. False is returned otherwise.