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 addMultilineString( const char* title,
const char* defaultValue,
APICharCallback func,
bool readonly = false,
size_t maxLength = 32767,
const char* symbolName = nullptr );
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 addGoButton();
statusCode addCancelButton();
statusCode addNextButton();
statusCode addResetButton();
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 addDoubleSlider( const char* title,
double defaultValue,
double sliderMin,
double sliderMax,
APIDoubleCallback func,
int precision = -1,
const char* symbolName = nullptr );
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 );
statusCode setImage( const char* symbolName, const char* fileName );
statusCode setImage( const char* symbolName,
int imgWidth,
int imgHeight,
const unsigned char* image );
statusCode setGroupExpanded( const char* uniqueTitle, bool expanded );
statusCode setTitle( const char* symbolName, const char* title );
statusCode setPopupItems( const char* symbolName,
const char* items,
int value );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::addMultilineString( const char* title, const char* defaultValue, APICharCallback func, bool readonly = false, size_t maxLength = 32767, const char* symbolName = nullptr );
Description
Add a text field to show or input of multiple lines of text. The text cannot
changed if readonly = true. Whenever the text is changed, the callback
function func is called. Not having func == nullptr && readonly == false
will lead to sInvalidArgument being returned. The maximum size of the entered
text must not exceed
maxLength.
Arguments
< title - title of the text field
< defaultValue - default value of the text field
< func - will be called when the shown text is changed
< readonly - if set to true the shown text cannot be changed
< maxLength - the text shown cannot exceend this many characters
< symbolName - name of the string symbol; if nullptr the title will be used
Return codes
sInvalidArgument -
readonly == false && func == nullptrgivensSuccess - 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::addGoButton();
Description
Add a 'Go' button in the bottom of the editor. Pressing this button will close the editor and execute the plugin function. Useful for momentary functions.
Default for momentary functions.
Return Codes
sAlreadyCreated - a button 'Go' already exists.
sSuccess - the add succeeded
statusCode addCancelButton();
Description
Add a 'Cancel' button in the bottom of the editor. Pressing this button will close the editor. Useful for momentary functions.
Default for momentary functions.
Return Codes
sAlreadyCreated - a button 'Go' already exists.
sSuccess - the add succeeded
statusCode addNextButton();
Description
Add a 'Next' button in the bottom of the editor. Pressing this button restart the function, resetting the selection and all intermediate state. Useful for continuous functions.
Default for continuous functions.
Return Codes
sAlreadyCreated - a button 'Go' already exists.
sSuccess - the add succeeded
statusCode addResetButton()
Add a reset button in the bottom of the editor. Pressing this button will reset the function.
Default for momentary and continuous functions.
Return Codes
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 drop down menu 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 double input and slider widget to the editor.
Arguments
< title - title of the widget
< defaultValue - the default value of the widget
< sliderMin - lowest value for the slider
< sliderMax - highest value for the slider
< 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, int precision = -1, const char* symbolName = nullptr );
Description
Add a double input and slider widget to the editor.
Arguments
< title - title of the widget
< defaultValue - the default value of the widget
< sliderMin - lowest value for the slider
< sliderMax - highest value for the slider
< func - the functin to call when the widget is modified
< precision - number of decimal places to show; use -1 for the default.
< symbolName - name of the double symbol for this widged; title is used if nullptr
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 image 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 image symbol
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
statusCode AlEditor::setImage( const char* symbolName, const char* fileName );
Description
Change an existing image widget to show the image from given file.
Arguments
< symbolName - symbol of the image widget to change
< fileName - path to file containing the image data
Return Codes
sFailure - if the image widget could not be found using symbolName
sSuccess - the image was changed
statusCode setImage( const char* symbolName, int imgWidth, int imgHeight, const unsigned char* image );
Description
Change an existing image widget to show the given image data.
Arguments
< symbolName - Name of the symbol
< imgWidth - Image width
< imgHeight - Image height
< image - array of unsigned chars containing RGBA values (imgWidth x imgHeight x 4)
Return Codes
sFailure - if the image widget could not be found using symbolName
sSuccess - the image was changed
statusCode setGroupExpanded( const char* uniqueTitle, bool expanded );
Description
Expand or collapse an existing group.
Arguments
< uniqueTitle - title of the group
< expanded - weather to expand (true) or collapse (false) the group
Return Codes
sFailure - if no group of the given uniqueTitle could be found
sSuccess - the state of the group was changed
statusCode AlEditor::setTitle( const char* symbolName, const char* title );
Description
Changes the title (or label) of a widget.
The function will fail if symbolName == nullptr, or not referring to a known
widget. While title must not be nullptr, passing an empty string is
accepted. This will lead to the widget having not title.
Arguments
< symbolName - Name of the string symbol (must not be null)
< visible - New title to be used for the widget (must not be null)
Return Codes
sFailure - the method failed
sSuccess - the method succeeded
statusCode AlEditor::setPopupItems( const char* symbolName, const char* items, int value );
Description
Change the items of an existing popup widget.
The items need to follow the format of "title:value" pairs, separated by comma (eg "OptionA:0,OptionB:1,OptionC:2"). Some sanity checking of the format is done.
Make use of the value parameter to ensure one of the new items is selected.
Setting value == -1 keeps the value of the underlying symbol unchanged. The
selection field will remain empty if no option matching the symbol value exists.
Arguments
< symbolName - name of the symbol used by the popup widget
< items - comma separated list of "title:value" pairs (eg "OptionA:0,OptionB:1,OptionC:2")
< value - value to set the popup to (and the associated symbol)
Return Codes
sFailure - the format check of items failed or the items string is empty or
nullptr
sSuccess - the items and optionally the value was changed