AlFunctionHandle

Class for creating the OpenAlias interface to Alias

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    setToolTitle( const char* );
statusCode setCustomIcon( const char* );
statusCode setOptionBox( const char*, const char* );
statusCode    addToMenu( const char * );
statusCode    appendToMenu( const char * );
statusCode    installOnSubmenu( const char * );
statusCode    addSeparator( const char * );
statusCode    removeSeparator( const char * );
statusCode    removeFromMenu();
statusCode    deleteObject();

class AlSubmenu
    AlSubmenu();
    ~AlSubmenu();
statusCode createSubmenu( const char *, const char * );
statusCode removeSubmenu( );

class AlMainMenu
    AlMainMenu();
    ~AlMainMenu();
statusCode create( const char * );
statusCode remove( );

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.

The class AlMainMenu is used for adding menus to the main menu in Alias.

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::setToolTitle( const char* )

Description

This method sets the string which will appear in the GUI as the tool title. For example, it will appear in Tooltips and menus in list mode.

Arguments

< str - The string to appear in the GUI.

Return Codes:

sInvalidArgument - str was NULL

sInvalidObject - The function handle has not been initialized.

sSuccess - The string was successfully set.

statusCode AlFunctionHandle::setOptionBox( const char* title, const char* functionName )

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 AlEditor described by the title does not exist.

Arguments

< title - name of the AlEditor

< functionName - the name of the AlFunciton

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::addSeparator( const char *menuName )

Description

This method allows the installation of separators on menus.

Note: items are always added to the end of a menu.

Arguments

< menuName - the name of the menu to attach on

Return Codes

sInvalidArgument - menuName was NULL

sFailure - Failed to attach

sSuccess - it worked

statusCode AlFunctionHandle::removeSeparator( const char *menuName )

Description

This method allows the removal of separators on menu.

Note: When executed, the bottom-most separator on the specified menu will be removed.

Arguments

< menuName - the name of the menu to remove from

Return Codes

sInvalidArgument - menuName was NULL

sFailure - Failed to remove

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

AlMainMenu::AlMainMenu()

Description

Constructor for the AlMainMenu class.

AlMainMenu::~AlMainMenu()

Description

Destructor for the AlMainMenu class.

statusCode AlMainMenu::create( const char *menuname )

Description

This method creates a menu on the main menu.

Arguments

< menuname - the name of the menu

Return Codes

sInvalidArgument - NULL parameter

sAlreadyCreated - the submenu has already been created

sSuccess - the menu was created

sFailure - the creation of the menu failed

statusCode AlMainMenu::remove( )

Description

Removes plug-in created menu.

Return Codes

sInvalidObject - the menu has not been created

sSuccess - the remove worked

sFailure - the remove failed

Parent page: AlDagNode – AlLocator