AlFunctionHandle

Synopsis

#include <AlFunctionHandle.h>
class AlFunctionHandle
AlFunctionHandle();
virtual	~AlFunctionHandle();
statusCode	create( const char*, const char* );
statusCode	create( const char*, AlFunction * );
AlFunctionHandle&	operator =( const AlFunctionHandle& );
int	operator !() const;
statusCode	setAttributeString( const char * );
statusCode	setOptionBox( const char *, const char *, const char * = NULL );
statusCode	setIconPath( const char* );
statusCode	setHelpFile( const char* );
statusCode	addToMenu( const char * );
statusCode	appendToMenu( const char * );
statusCode	installOnSubmenu( const char * );
statusCode	removeFromMenu();
statusCode	deleteObject();
class AlSubmenu
	AlSubmenu();
	~AlSubmenu();
statusCode createSubmenu( const char *, const char * );
statusCode removeSubmenu( );

Description

This class provides a means to interface the OpenAlias application to the Alias user interface. An AlFunction class or one of its derivatives (AlMomentaryFunction, AlContinuousFunction) is required by the create method. Note that the string name of an Al*Function could also be specified in the create() method.

The class AlSubmenu is used for creating submenus in Alias. Create a new submenu on an existing Alias menu and then use the AlFunctionHandle::installOnSubmenu() method to add a new item.

Note: avoid attaching submenu items to submenus created by other plug-ins since your submenu item will disappear when the other plug-in is unloaded.

AlFunctionHandle::AlFunctionHandle()

Description

Constructor for the AlFunctionHandle class.

AlFunctionHandle::~AlFunctionHandle()

Description

Destructor for the AlFunctionHandle class.

AlFunctionHandle& AlFunctionHandle::operator =( const AlFunctionHandle& f )

Description

Assignment operator for the AlFunctionHandle class.

int AlFunctionHandle::operator !() const

Description

Allows you to use statements to check the validity of the handle, such as

if( functionhandle ) ....

statusCode AlFunctionHandle::create( const char * popupLabel, const char * command )

Description

Initializes the function handle given a popupLabel and a momentary function name (command).

Arguments

< popupLabel - the string that will appear on the menu pop-up for this plug-in

< command - a character string which is the name of the momentary command. It must be unique.

Return Codes

sInvalidArgument - name or command was NULL

sAlreadyCreated - the handle has already been created

sSuccess - the handle was created

sFailure - the handle could not be created

sObjectInSet - a command with name ’command’ already exists

statusCode AlFunctionHandle::create( const char * popupLabel, AlFunction *func )

Description

Initializes the function handle given a name and a momentary function name (command).

Arguments

< popupLabel - the string that will appear on the menu pop-up for this plug-in

< func - the set of functions (momentary or continuous)

Return Codes

sInvalidArgument - name or command was NULL

sAlreadyCreated - the handle has already been created

sSuccess - the handle was created

sFailure - the handle could not be created

statusCode AlFunctionHandle::setAttributeString( const char * str )

Description

Sets the string that will appear on the attribute line below the prompt line when the plug-in is selected from the menu.

Arguments

< str - the string to appear in the attribute line

Return Codes

sInvalidArgument - str was NULL

sInvalidObject - the function handle has not been initialized

sSuccess - the attribute string was set successfully

statusCode AlFunctionHandle::setOptionBox( const char * schemeFileName, const char * editorName, const char * schemeFileNamePrefix )

Description

Sets the option box for the plug-in. If the plug-in has no option box, then do not call this method. This method will fail if the scheme file described by the name and prefix does not exist. Normally, the ’schemeFileName’ is the name of the file which defines the option box.

If the ’schemeFileNamePrefix’ parameter is NULL, then the ’schemeFileName’ will be loaded relative to the path defined by the environment variable ALIAS_WORKENV.
If the ’schemeFileNamePrefix’ parameter is not NULL, then it will be added to the start of the ’schemeFileName’.

The string formed by concatenating ’schemeFileName’ to ’schemeFileNamePrefix’ will be used as the filename that will be loaded, that is, the actual scheme file that is loaded will be equivalent to schemeFileNamePrefix/schemeFileName.

Arguments

< schemeFileName - name of the Scheme file which defined the option box

< editorName - the name given to the ui-editor function in the Scheme file

< schemeFileNamePrefix - the name of the directory to prefix to schemeFileName

Return Codes

sInvalidObject - function handle is invalid

sInvalidArgument - one of the arguments was NULL or the file does not exist

sFailure - the function handle is already attached to a menu

sSuccess - the option box was successfully set for the plug-in

statusCode AlFunctionHandle::addToMenu( const char * menuname )

Description

Adds a plug-in to the bottom of the menu.

Arguments

< menuname - the name of the menu the plug-ins will be added to

Return Codes

sInvalidArgument - menuname was NULL

sAlreadyCreated - the function handle is already attached to a menu

sObjectNotAMember - the menu name was not valid

sFailure - failed to attach the plug-in to the menu

statusCode AlFunctionHandle::appendToMenu( const char * menuname )

Description

Adds a plug-in to the top of the menu.

Arguments

< menuname - the name of the menu the plug-ins will be added to

Return Codes

sInvalidArgument - menuname was NULL

sAlreadyCreated - the function handle is already attached to a menu

sObjectNotAMember - the menu name was not valid

sFailure - failed to attach the plug-in to the menu

statusCode AlFunctionHandle::installOnMenu( const char * menuname, boolean topOfMenu )

Description

This method installs a plug-in on a menu.

Arguments

< menuname - the name of the menu the plugins will be placed on.

< topOfMenu - if TRUE, the plug-in is placed at the top of the menu. If FALSE, the plug-in is placed at the bottom of the menu.

Return Codes

sInvalidArgument - menuname was NULL

sAlreadyCreated - The function handle is already attached to a menu.

sObjectNotAMember - The menu name was not valid.

sFailure - Failed to attach the plugin to the menu.

sSuccess - it worked

statusCode AlFunctionHandle::installOnSubmenu( const char *subMenuName )

Description

This method allows the installation of plug-ins on submenus. The submenu may already exist in Alias or could have been created by the plug-in with the AlSubmenu class.

NOTE: items are always added to the end of a submenu.

Arguments

< subMenuName - the name of the submenu to attach on

Return Codes

sInvalidArgument - subMenuName was NULL

sAlreadyCreated - The function handle is already attached to a menu

sFailure - Failed to attach the plugin to a submenu

sSuccess - it worked

statusCode AlFunctionHandle::removeFromMenu()

Description

Removes the function handle from its previously attached menu.

Return Codes

sFailure - the handle is not attached to a menu

sSuccess - the handle was removed from the menu

statusCode AlFunctionHandle::setIconPath( const char* path )

Description

Sets the pathname to load the icon files from. Normally icons are loaded from ALIAS_BITMAP_LOCATION. In the specified path, there should be two directories:

small  medium

In the small/ directory, there should be an icon file ending in the function name followed by ’.S’ In the medium/ directory, there should be an icon file ending in the function name followed by ’.M’ For example, if the function name is ’MySphere’ and the icon path is ’/usr/myicons’, then the following files should exist:

/usr/myicons/small/MySphere.S  /usr/myicons/medium/MySphere.M

Return Codes

sFailure - the path could not be set

sSuccess - the path was set for this function handle

statusCode AlFunctionHandle::setHelpFile( const char* file )

Description

Sets the filename to load the help file from.

Return Codes

sFailure - the file could not be set

sSuccess - the file was set for this function handle

statusCode AlFunctionHandle::deleteObject()

Description

Removes the function handle from the menu and invalidates it.

Return Codes

sFailure - the handle could not be removed from the menu

sSuccess - the handle was successfully removed

AlSubmenu::AlSubmenu()

Description

Constructor for the AlSubmenu class.

AlSubmenu::~AlSubmenu()

Description

Destructor for the AlSubmenu class.

statusCode AlSubmenu::createSubmenu( const char *menuname, const char *submenuname )

Description

This method creates a submenu on an existing menu.

Arguments

< menuname - the name of the menu the submenu will be added to

< submenuname - the name of the submenu to create

Return Codes

sInvalidArgument - NULL parameter

sAlreadyCreated - the submenu has already been created

sSuccess - the submenu was created

sFailure - the creation of the submenu failed

statusCode AlSubmenu::removeSubmenu( )

Description

Removes plug-in created submenus.

Return Codes

sInvalidObject - the submenu has not been created

sSuccess - the remove worked

sFailure - the remove failed