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