AlEditor

Synopsis

#include <AlEditor.h>
class AlEditor 
AlEditor( void ); 
~AlEditor( void );
statusCode create( const char *title ); 
statusCode deleteEditor( void );
statusCode open( void ); 
statusCode close( void ); 
statusCode update( void ); 
statusCode toggle( void ); 
statusCode enableItem( ComponentId itemId, boolean enable );
boolean isEnabled( ComponentId itemId ); 
boolean isOpen( void );
statusCode addSeparator( ComponentDescriptor *descriptor ); 
statusCode addGrouping( ComponentDescriptor *descriptor );
statusCode addString( ComponentDescriptor *descriptor, const char *value, IdStringCallback callback ); 
statusCode addInt( ComponentDescriptor *descriptor, int &reference, IntComponentData *data, IdCallback callback = NULL ); 
statusCode addFloat( ComponentDescriptor *descriptor, float &reference, FloatComponentData *data, IdCallback callback = NULL ); 
statusCode add3Floats( ComponentDescriptor *descriptor, float (&reference)[3], IdCallback callback = NULL );
statusCode addCheckBox( ComponentDescriptor *descriptor, int &reference, IdCallback callback = NULL ); 
statusCode addCheckBoxes( ComponentDescriptor *descriptor, int &reference, ComponentDescriptor *descriptor2, int &reference2, IdCallback callback = NULL );
statusCode addButton( ComponentDescriptor *descriptor, IdCallback callback );
statusCode addRadioGroup( ComponentDescriptor *descriptor, AlEditorRadioGroupStyle style, ComponentDescriptor *subComponentDescriptorList, IdCallback callback ); 
statusCode addPulldownMenu( ComponentDescriptor *descriptor, ComponentDescriptor *subComponentDescriptorList, IdCallback callback );
class ComponentDescriptor
ComponentDescriptor( const char *label ); 
~ComponentDescriptor( void );
ComponentId id( void ); 
const char *label( void ); 
void setLabel( const char *label ); 
void setId( ComponentId id );
ComponentDescriptor *next( void ); 
void setNext( ComponentDescriptor *descriptor );
ComponentDescriptorType type( void );
class IntComponentData
IntComponentData( int minValue, int maxValue ); 
~IntComponentData( void );
int minValue( void ); 
int maxValue( void );
private: 
int fMinValue; 
int fMaxValue; 
class FloatComponentData 
FloatComponentData( float minValue, float maxValue ); 
~FloatComponentData( void );
float minValue( void ); 
float maxValue( void );

Description

This class provides an interface to Alias user interface. It allows the building of dynamic editors within a plug-in. Standard operations are supported, such as open, close, toggle, and a basic set of user interface components.

A reference variable is used as a parameter in a number of the user interface components. This reference maintains the state of the component and must be in permanent storage. If you allocate this variable on the stack, program errors will occur. In some cases, a user interface component will contain multiple parts. In this situation, a list of component descriptors will be used to describe this object to the class.

Descriptors are used to describe the components to be created. A label is set in the descriptor object as input. The AlEditor class will dynamically allocate a component ID and set it in the descriptor. Individual components of an editor cannot be deleted. Instead, the entire editor must be de-allocated all at once.

Description

Constructor for a new AlEditor object.

AlEditor::AlEditor( void )

Description

Destruct an AlEditor object.

AlEditor::~AlEditor( void )

Description

Create a new editor. First create an editor, then add components to it and then call the open method.

Arguments

< title - title of the editor

Return Codes

sFailure - the method failed

sAlreadyCreated - the editor is already created

sSuccess - the create worked

statusCode AlEditor::create( const char *title )

Description

De-allocate the storage for the editor once it has been closed. All components will be de-allocated and callbacks will be removed.

Return Codes

sFailure - the method failed

sSuccess - the delete worked

statusCode AlEditor::deleteEditor( void )

Description

Open/display the editor window. The editor should already be created and have had components added to it.

Return Codes

sFailure - no components added or the method failed

sSuccess - the open worked

statusCode AlEditor::open( void )

Description

Close/remove the editor window. The editor will need to be deleted to properly clean up its storage.

Return Codes

sFailure - the method failed

sSuccess - the close worked

statusCode AlEditor::close( void )

Description

Returns TRUE if the editor is open. FALSE is returned otherwise.

boolean AlEditor::isOpen( void )

Description

Force the editor window to update/redraw itself. This call should be made if a reference variable is modified by the plug-in's code.

Return Codes

sFailure - the method failed

sSuccess - the update worked

statusCode AlEditor::update( void )

Description

Toggle the editor window. If the window is open, it will be closed. If the window is closed, it will be opened. Toggle can be used to temporarily close the window, if the plug-in will need to re-open it.

Return Codes

sFailure - the method failed

sSuccess - the toggle worked

statusCode AlEditor::toggle( void )

Description

Enables or disables the component that is described by itemId.

Note

This call will always fail on subcomponents of default style radio group buttons.

Arguments

< itemId - unique id associated with a component

< enable - TRUE or FALSE

Return Codes

sInvalidArgument - itemId cannot be found

sFailure - method failed

sSuccess - the item's enable state was changed

statusCode AlEditor::enableItem( ComponentId itemId, boolean enable )

Description

Returns TRUE if the item described by itemId is enabled. FALSE is returned otherwise.

Note

See the documentation in AlEditor::enableItem() for information on how this method can fail.

Arguments

< itemId - unique id associated with a component

boolean AlEditor::isEnabled( ComponentId itemId )

Description

Adds a separator to the editor. Separators can be used to provide a logical grouping of components.

Arguments

< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label setting is not required in the descriptor parameter class.

Return Codes

sInvalidArgument - descriptor is NULL or descriptor id is already in use

sFailure - method failed

sSuccess - the separator was created

statusCode AlEditor::addSeparator( ComponentDescriptor *descriptor )

Description

Adds a grouping to the editor. All components added after this call will be placed under this grouping until another grouping is added.

Arguments

< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class.

Return Codes

sInvalidArgument - descriptor or its label is NULL or descriptor id is already in use

sFailure - method failed

sSuccess - the grouping was created

statusCode AlEditor::addGrouping( ComponentDescriptor *descriptor )

Description

Adds a float component to the editor.

Arguments

< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class.

< reference - variable that tracks the state of the float. This variable must be in permanent storage for the life of the plug-in.

< data - currently used to specify min and max ranges for component

< callback - optional function to be called when the float is modified

Return Codes

sInvalidArgument - descriptor or its label is NULL or descriptor id

is already in use or data is NULL

sFailure - method failed

sSuccess - the float was created

statusCode AlEditor::addFloat( ComponentDescriptor *descriptor, float &value, FloatComponentData *data, IdCallback callback )

Description

Adds an string entry component to the editor.

Arguments

< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class.

< callback - optional function to be called when the float is modified

Return Codes

sInvalidArgument - descriptor or its label is NULL or descriptor id is already in use

sFailure - method failed

sSuccess - the float was created

statusCode AlEditor::addString( ComponentDescriptor *descriptor, const char *value, IdStringCallback callback )

Description

Adds an integer component to the editor.

Arguments

< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class.

< reference - variable that tracks the state of the integer. This variable must be in permanent storage for the life of the plug-in.

< data - currently used to specify min and max ranges for component

< callback - optional function to be called when the integer is modified

Return Codes

sInvalidArgument - descriptor or its label is NULL or descriptor id is already in use or data is NULL

sFailure - method failed

sSuccess - the integer was created

statusCode AlEditor::addInt( ComponentDescriptor *descriptor, int &value, IntComponentData *data, IdCallback callback )

Description

Adds a float triple to the editor.

Arguments

< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class.

< reference - variable that tracks the state of the float triple. This variable must be in permanent storage for the life of the plug-in.

< callback - optional function to be called when the float triple is modified

Return Codes

sInvalidArgument - descriptor or its label is NULL or descriptor id is already in use

sFailure - method failed

sSuccess - the float triple was created

statusCode AlEditor::add3Floats( ComponentDescriptor *descriptor, float (&reference)[3], IdCallback callback )

Description

Adds a check box to the editor.

Arguments

< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class.

< reference - variable that tracks the state of the check box.

This variable must be in permanent storage for the life of the plug-in.

< callback - optional function to be called when the check is pressed

Return Codes

sInvalidArgument - descriptor or its label is NULL or descriptor id

is already in use

sFailure - method failed

sSuccess - the check box was created

statusCode AlEditor::addCheckBox( ComponentDescriptor *descriptor, int &reference, IdCallback callback )

Description

Adds two check boxes to the editor.

Arguments

< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class.

< reference - variable that tracks the state of the check box associated with itemId

This variable must be in permanent storage for the life of the plug-in.

< descriptor2 - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class.

< reference2 - variable that tracks the state of the check box associated with itemId2

This variable must be in permanent storage for the life of the plug-in.

< callback - optional function to be called when one of the checks is pressed

Return Codes

sInvalidArgument - descriptor or its label is NULL or

descriptor2 or its label2 is NULL

sFailure - method failed

sSuccess - the check boxes were created

statusCode AlEditor::addCheckBoxes( ComponentDescriptor *descriptor, int &reference, ComponentDescriptor *descriptor2, int &reference2, IdCallback callback )

Description

Adds a button to the bottom of the editor. Note that an editor can either have a pull down menu or buttons on the bottom of the editor. Both cannot be created at the same time.

Arguments

< descriptor - the component id is dynamically created by the class and returned in this parameter class.

The label of the component is required to be set in the descriptor parameter class.

< callback - function to be called when the button is selected

Return Codes

sInvalidArgument - descriptor or its label is NULL or callback is NULL

sFailure - pulldown menu already created or method failed or the editor

already has a maximum of 4 buttons

sSuccess - the button was created

statusCode AlEditor::addButton( ComponentDescriptor *descriptor, IdCallback callback )

Description

Adds a radio group selector. Radio group selectors allow a user to pick a single item out of a list.

Arguments

< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class.

< style - the style of the radio group

< subComponentDescriptorList - list of descriptors( currently label and an id that is returned by the class ) that describes the subcomponent

< callback - function to be called when the radio group item is selected

Return Codes

sInvalidArgument - descriptor or its label is NULL or

subComponentDescriptorList is NULL or callback is NULL

sFailure - method failed

sSuccess - the radio group was created

statusCode AlEditor::addRadioGroup( ComponentDescriptor *descriptor, AlEditorRadioGroupStyle style, ComponentDescriptor *subComponentDescriptorList, IdCallback callback )

Description

Adds a pull down menu to the editor. Pull down menus are added at the top of the editor window. Note that an editor can either have a pull down menu or buttons on the bottom of the editor. Both cannot be created at the same time.

Arguments

< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class.

< subComponentDescriptorList - list of descriptors( currently label and an id that is returned by the class ) that describes the subcomponent

< callback - function to be called when a menu item is selected

Return Codes

sInvalidArgument - descriptor or its label is NULL or

subComponentDescriptorList is NULL

or callback is NULL

sFailure - buttons already created or method failed

sSuccess - the pull down menu was created

statusCode AlEditor::addPulldownMenu( ComponentDescriptor *descriptor, ComponentDescriptor *subComponentDescriptorList, IdCallback callback )

Description

Adds a pull down menu to the editor. Pull down menus are added at the top of the editor window. Note that an editor can either have a pull down menu or buttons on the bottom of the editor. Both cannot be created at the same time.

Arguments

< descriptor - the component id is dynamically created by the class and returned in this parameter class. The label of the component is required to be set in the descriptor parameter class.

< subComponentDescriptorList - list of descriptors( currently

label and an id that is returned by the class ) that describes the subcomponent

< callback - function to be called when a menu item is selected

Return Codes

sInvalidArgument - descriptor or its label is NULL or subComponentDescriptorList is NULL or callback is NULL

sFailure - buttons already created or method failed

sSuccess - the pull down menu was created

ComponentDescriptor::ComponentDescriptor( const char *label )

Description

Constructs a ComponentDescriptor.

Argument

The name label of the component descriptor.

ComponentDescriptor::~ComponentDescriptor( void )

Description

Destruct a component descriptor.

void ComponentDescriptor::setLabel( const char *label )

Description

Set the label name of the component descriptor.

Argument

< label - label name

void ComponentDescriptor::setId( ComponentId id )

Description

Set the component identifier of the descriptor. Alias is most cases will automatically assign an identifier to the descriptor.

Argument

< id - the component id

ComponentId ComponentDescriptor::id( void )

Description

Returns the current identifier for the component.

const char *ComponentDescriptor::label( void )

Description

Returns the current label name for the descriptor.

ComponentDescriptor *ComponentDescriptor::next( void )

Description

Returns the next component descriptor.

void ComponentDescriptor::setNext( ComponentDescriptor *descriptor )

Description

Add a component descriptor to the end of the descriptor list.

Argument

< descriptor - the new descriptor to add to the list

ComponentDescriptorType ComponentDescriptor::type( void )

Description

Return the type of the descriptor.

IntComponentData::IntComponentData( int minValue, int maxValue )

Description

Construct a similar Int data class to hold on to minimum and maximum values.

Argument

< minValue - the minimum integer to keep track of

< maxValue - the maximum integer to keep track of

IntComponentData::~IntComponentData( void )

Description

Destroy the Int data class

int IntComponentData::minValue( void )

Description

Return the min value.

int IntComponentData::maxValue( void )

Description

Return the max value.

FloatComponentData::FloatComponentData( float minValue, float maxValue )

Description

Construct a simple Float class that tracks minimum and maximum values.

Argument

< minValue - the minimum float value to track

< maxValue - the maximum float value to track

FloatComponentData::~FloatComponentData( void )

Description

Destroy the float class object.

float FloatComponentData::minValue( void )

Description

Return the minimum float value.

float FloatComponentData::maxValue( void )

Description

Return the maximum float value.