Attaching a Plug-in to a Menu

The first step in attaching plug-in functionality to a menu is to create an AlFunction object. The AlFunction class encapsulates information about what actions to perform when your plug-in is selected. It represents the `back end' of a menu item. In particular, a plug-in would create an AlMomentaryFunction or an AlContinuousFunction to describe its operation.

To actually define the menu item which will invoke that AlFunction, use the AlFunctionHandle class, which provides a C++ interface to Scheme.

The file AlFunctionHandle.h must be included by the plug-in to use AlFunctionHandle. AlFunction.h must be included to use either AlMomentaryFunction or AlContinuousFunction.

In the plugin_init() function of the plug-in the various methods of the AlFunctionHandle are used to define the menu item (or menu items) that will be added to OpenAlias, and the AlFunction classes are used to register the functions which make up the functionality of the plug-in. In the case of using Scheme instead of AlFunctionHandle, plugin_init() would at some point invoke a Scheme file that performs the necessary UI initialization.

AlFunctionHandle

Any instance of this class must be defined in the file scope so that it is available to the plugin_init() and plugin_exit() functions.

AlFunctionHandle::create()

Prototype:

statusCode AlFunctionHandle::create( const char * name, const char * command );
statusCode AlFunctionHandle::create( const char * name, AlFunction *func );

Description:

These methods are used to create the function handle and set some of its attributes. (It is also possible to use the constructor to create the function handle.)

Arguments:

• < name - This is the string that will appear on the menu popup for this plug-in.
• < func - This is a pointer to an actual AlFunction object, specifically the object corresponding to the functionality that executes when this menu item is invoked.
• < command - As an alternative to using the func argument this is a character string which matches the name of the main entry point for the plug-in. This name can be defined explicitly by calling the appropriate create method in one of the AlFunction classes.

Return codes:

• sInvalidArgument - One of the arguments was NULL.
• sAlreadyCreated - The function handle is already attached to a menu.
• sSuccess - The function handle was successfully created.
• sFailure - The function handle was unsuccessfully created.

AlFunctionHandle::setAttributeString

Prototype:

statusCode AlFunctionHandle::setAttributeString( const char * str );

Description:

This method sets the attribute string. It currently does not appear in the UI but should still be set for future use.

Arguments:

• < str - The string to appear in the attribute line.

Return codes:

• sInvalidArgument - The argument was NULL.
• sFailure - The function handle is already attached to a menu.
• sSuccess - The attribute string was successfully set for the function handle.

AlFunctionHandle::setOptionBox

Prototype:

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

Description:

This method sets the option box for the plug-in. If the plug-in has no option box, this method need not be used. This method will fail if the scheme file described by the name and prefix does not exist.

Arguments:

• < schemeFileName - name of the Scheme file that defines 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:

• sInvalidArgument - One of the arguments was NULL.
• sFailure - The function handle is already attached to a menu.
• sSuccess - The option box was successfully set for the plug-in.

AlFunctionHandle::setIconPath

Prototype:

statusCode AlFunctionHandle::setIconPath( const char * iconPath );

Description:

This method sets the pathname to load the icon images from. If the path is not set, then the icon image will be loaded from the standard bitmap locations ($ALIAS_BITMAP_LOCATION or $ALIAS_LOCATION/bitmaps). Currently the icon path must contain two directories: `small' and `medium'. Each directory contains an image of the icon to be displayed. The small image must have the suffix `.S', and the medium sized image must have the suffix `.M'.

For example, if the function name is `myFunc', then the directory would be setup as:

..../small/myFunc.S
..../medium/myFunc.M

Arguments:

• < iconPath - The path to the two directories.

Return codes:

• sInvalidArgument - The arguments was NULL.
• sFailure, sSuccess - The result.

AlFunctionHandle::addToMenu and AlFunctionHandle::appendToMenu

Prototype:

statusCode AlFunctionHandle::addToMenu( const char * menuname );
statusCode AlFunctionHandle::appendToMenu(const char * menuname);

Description:

These methods add the plug-in to the menu. addToMenu() adds the plug-in to the bottom of the menu, while appendToMenu() will add it to the top of the menu.

Arguments:

• < menuname - The name of the menu the plug-in will be added to.

Return codes:

• sInvalidArgument - The argument 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.
• sSuccess - The plug-in was successfully attached to the menu.

Available Menus

Plug-ins can be attached to the following menus.

Table 1: Available Menus
Menu Name	OpenAlias Menu Identifier
Animation Menu	ap_animwinds
Animation Palette	ap_timetools
Cameras	mp_views
Curves	al_curvetoolbox
Curve Edit	mp_crvtools
Clouds	al_cloudtoolbox
Delete	al_delete
Display	mp_display
Edit	al_edit
Evaluate	mp_evaltool
File	al_file
Help	al_help
Grids	mp_grid
Layers	ma_layers
Layouts	mp_window
Locators	al_locate
Objects	al_object_create
ObjectDisplay	mp_objdisplay
Object Edit	mp_objtools
Pick	mp_pick
Polygons	al_polytools
Polygon Edit	al_polyedit
Polygon Shading	al_polydisp_edit
Preferences	al_envtools
Render	rp_render
Surfaces	mp_buildsurf
Surface Edit	mp_srftools
Utilities	al_goto
Windows	mp_windows_menu
Xform	mp_xform

AlFunctionHandle::removeFromMenu

Prototype:

statusCode AlFunctionHandle::removeFromMenu();

Description:

This method removes the function handle from the menu.

Return codes:

• sFailure - The function handle is not attached to a menu.
• sSuccess - The function handle was successfully removed from the menu.

AlFunctionHandle::deleteObject

Prototype:

statusCode AlFunctionHandle::deleteObject();

Description:

This method deletes the function handle from the menu and completely invalidates it.

Return codes:

• sFailure - The function handle is not attached to a menu.
• sSuccess - The function handle was successfully removed
  from the menu and deleted.

AlFunctionHandle::operator =

Prototype:

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

Description:

This defines the assignment operator for the AlFunctionHandle class.

Arguments:

• < f - An existing function handle.

AlFunctionHandle::operator!

Prototype:

int AlFunctionHandle::operator !() const

Description:

This method allows us to check the validity of a function handle.

ex.

		if ( functionhandle ) ...