AlEditor
+ 
An interface allowing the construction of editing boxes for attaching to plug-ins.
Synopsis
#include <AlEditor.h>
class AlEditor
AlEditor( const char* title, const char* functionName );
~AlEditor( void );
statusCode create();
statusCode addSeparator();
statusCode addGroup( const char* uniqueTitle );
static statusCode endGroup();
statusCode addString( const char* title,
const char* defaultValue,
APICharCallback func );
statusCode addReadOnlyString( const char* title,
const char* defaultValue,
const char* symbolName );
statusCode setReadOnlyString( const char* title, const char* newValue );
statusCode addButton( const char* title, APIVoidCallback func );
statusCode addButton( const char* title,
APIVoidCallback func,
bool autoClose );
statusCode addTextButton( const char* title, APIVoidCallback func );
statusCode addCheckbox( const char* title,
bool defaultValue,
APIBoolCallback func );
statusCode addPopup( const char* title,
const char* items,
int defaultValue,
APIIntCallback func );
statusCode addRadio( const char* title,
const char* items,
int defaultValue,
APIIntCallback func );
statusCode addIntSlider( const char* title,
int defaultValue,
int sliderMin,
int sliderMax,
APIIntCallback func );
statusCode addDoubleSlider( const char* title,
double defaultValue,
double sliderMin,
double sliderMax,
APIDoubleCallback func );
statusCode addColor( const char* title,
APIColor defaultValue,
APIColorCallback func );
statusCode addImage( const char* fileName,
const char* symbolName );
statusCode addImage( int imgWidth,
int imgHeight,
const unsigned char* image,
const char* symbolName );
statusCode setEnabled( const char* title,
bool enabled );
statusCode setVisible( const char* title,
bool enabled );Description
The AlEditor class allows developers to attach custom editors to the tools (plug-ins) they have created and added to the Alias user interface. These editors are intended to be governed by the same rules that govern the editors of native tools in Alias.
As the AlEditor class is intended to mimic the behavior of the native tools, their behaviors (eg modal vs non modal) depend on whether you attach the editor to an AlMomentaryFunction or AlContinuousFunction (using AlFunctionHandle::setOptionBox()).
An example of simple editor construction involves allocating the editor, populating the widgets, and then calling the create() method. For example:
// The editor must be named the same as the tool/plugin
hEditor = new AlEditor( "Editor Title", "Plugin Function Name" );
hEditor->addRadio( "Radio Title",
"Option0:0,Option1:1",
data.radioInt,
radioCallback );
hEditor->addCheckbox( "Checkbox Title",
data.checkboxInt,
checkboxCallback );
hEditor->create();
// Set the option box -> names must match AlEditor construction
functionHandle.setOptionBox( "Editor Title", "Plugin Function Name" );Description
Constructor for a new AlEditor object.
Arguments
< title - title of the editor < functionName - name of the tool (plug-in function) to associate with the editor.
AlEditor::AlEditor( const char* title, const char* functionName )
Description
Destruct an AlEditor object.
AlEditor::~AlEditor( void )
Description
Create the new editor. This routine should be called after all the widgets have been added to the editor.
Return Codes
sFailure - the method failed
sAlreadyCreated - the editor is already created
sSuccess - the create worked
statusCode AlEditor::create()
Description
Adds a separator to the editor.
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addSeparator()
Description
Adds a separator to the editor.
Arguments
< none
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addGroup( const char* uniqueTitle );
Description
Adds a collapsible group widget to the editor. Subsequent added widgets will be added to this group. If another addGroup() is called, another group for widgets is added until an endGroup() is called.
Arguments
< title - title of the group
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::endGroup();
Description
Ends the current widget group. Subsequent widgets will be added to the parent group. If a addGroup() is called before endGroup(), the added group becomes a collapsible child of the current group.
Arguments
< none
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addString( const char* title, const char* defaultValue, APICharCallback func );
Description
Adds an editable string to the bottom of the editor.
Arguments
< title - title of the button
< func - the function to call when the string is modified
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addReadOnlyString( const char* title, const char* defaultValue, const char* symbolName );
Description
Adds an read only string to the bottom of the editor.
Arguments
< title - title of the button
< symbolName - Name of the string symbol (can be null)
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::setReadOnlyString( const char* title, const char* newValue );
Description
Sets a read only string to the passed in value.
Arguments
< title - title of the widget < newValue - Name of the string symbol (can be null)
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addButton( const char* title, APIVoidCallback func );
Description
Adds a button to the bottom of the editor.
Arguments
< title - title of the button
< func - the function to call when the button is pressed
< autoClose - specify if the editor should close when the button is pressed
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addTextButton( const char* title, APIVoidCallback func );
Description
Adds a button widget into the editor, which will execute the callback function when selected.
Arguments
< title - text in button < func - the function to call when the widget is selected
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addButton( const char* title, APIVoidCallback func, bool autoClose );
Description
Adds a checkbox input widget to the editor.
Arguments
< title - title of the widget
< defaultValue - the default value of the widget
< func - the function to call when the widget is modified
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addCheckbox( const char* title, bool defaultValue, APIBoolCallback func );
Description
Adds a popup (drop-down) input widget to the editor.
Arguments
< title - title of the widget
< items - Comma separated list of "title:value" pairs (eg "OptionA:0,OptionB:1,OptionC:2")
< defaultValue - the default value of the widget
< func - the function to call when the widget is modified
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addPopup( const char* title, const char* items, int defaultValue, APIIntCallback func );
Description
Adds a radio button input widget to the editor.
Arguments
< title - title of the widget
< items - Comma separated list of "title:value" pairs (eg "OptionA:0,OptionB:1,OptionC:2")
< defaultValue - the default value of the widget
< func - the function to call when the widget is modified
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addRadio( const char* title, const char* items, int defaultValue, APIIntCallback func );
Description
Adds an integer precision slider input widget to the editor.
Arguments
< title - title of the widget
< defaultValue - the default value of the widget
< sliderMin - the min value of the slider widget
< sliderMax - the max value of the slider widget
< func - the function to call when the widget is modified
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addIntSlider( const char* title, int defaultValue, int sliderMin, int sliderMax, APIIntCallback func );
Description
Adds a double precision slider input widget to the editor.
Arguments
< title - title of the widget
< defaultValue - the default value of the widget
< sliderMin - the min value of the slider widget
< sliderMax - the max value of the slider widget
< func - the function to call when the widget is modified
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addDoubleSlider( const char* title, double defaultValue, double sliderMin, double sliderMax, APIDoubleCallback func );
Description
Adds a color widget to the editor.
Arguments
< title - title of the widget
< defaultValue - the default color value of the widget
< func - the function to call when the widget is modified
Return Codes
sFailure - the method failed
sSuccess - the add succeeded
statusCode AlEditor::addColor( const char* title, APIColor defaultValue, APIColorCallback func );
Description
Allows for a widget to be enabled/disabled (greyed out) in the interface.
Arguments
< title - title of the editor
< enabled - should the widget be enabled or disabled
Return Codes
sFailure - the method failed
sSuccess - the method succeeded
statusCode AlEditor::addImage( const char* fileName, const char* symbolName );
Description
Adds an image widget to the editor. This can be used as a preview of something.
Arguments
< fileName - Absolute path to an image file
< symbolName - Name of the fileName symbol
Return Codes
sFailure - the method failed
sSuccess - the method succeeded
statusCode AlEditor::addImage( int imgWidth, int imgHeight, const char* image, symbolName );
Description
Adds an image widget to the editor. This can be used as a preview image in the editor.
Arguments
< imgWidth - Image width
< imgHeight - Image height
< image - array of unsigned chars containg RGBA values (imgWidth x imgHeight x 4)
< symbolName - Name of the fileName symbol (can be null)
Return Codes
sFailure - the method failed
sSuccess - the method succeeded
statusCode AlEditor::setEnabled( const char* title, bool enabled );
Description
Allows for a widget to be enbled the interface.
Arguments
< title - title of the editor
< enabled - should the widget be enables or disabled
Return Codes
sFailure - the method failed
sSuccess - the method succeeded
statusCode AlEditor::setVisible( const char* title, bool visible );
Description
Allows for a widget to be made visible/invisible in the interface.
Arguments
< title - title of the editor
< visible - should the widget be visible or invisible
Return Codes
sFailure - the method failed
sSuccess - the method succeeded