Alias API Version 9.0 Documentation

Creating an Option Box

Option boxes are created with a call to the ui-editor primitive. There are several arguments that apply to option boxes in general. The remaining arguments specify the widgets (editor tools) that make up the option box.

General Option Box Attributes

The following attributes describe the general behavior of an option box.

(list 'title '<symbol>) - a previously defined ui-string that defines the title of the option box.

Example: (list 'title "View Frame Options")

(list 'symbols '<symbol> '<symbol> ...) - a list of all the ui-symbols referenced by this option box. These should correspond to the names of all the widgets that appear in the option box.

Example: (list 'symbols  'nothing.intval 'nothing.doubval 'nothing.boolean )

(list 'init_option_function "<func>") - the name of a momentary function to invoke before the option box gets opened. This can be used, for instance, to set the values of ui-symbols based on the current state of Alias.

Example:

Scheme file:
(ui-editor 'control.options
        (list 'symbols  'control.pos_x)

        (list 'init_option_function "control.init_func" )
        (list 'title "Control Options")

        (ui-double-widget 'control.pos_x
                (list 'range -10.0 10.0)
                (list 'precision "%f4.6")
        )
	)
)

Scheme init file:
(ui-symbol 'control.pos_x                                       0.0)
(ui-string 'control.pos_x                                       "X")

Plug-in:
static void option_box_init_func( void )
{
    AlSetDouble( "control.pos_x", 45 );
}

AlMomentaryFunction function;
AlFunctionHandle handle;

extern "C"
int plugin_init( const char* dirName )
{
    AlUniverse::initialize();
    function.create( "control.init_func", option_box_init_func );
	// other code goes here
}

(list 'reset_option_function "<func>"), (list 'save_option_function "<func>"), (list 'go_option_function "<func>") - used to specify momentary functions that get invoked in addition to the standard behaviors of these buttons.

Note:  Allocating memory in the init_option_function will result in memory leaks if 
the Exit button is selected. There is no corresponding exit_option_function where 
allocated memory can be released.

This function follows the same programming principles as the example in the previous 
bullet except that 3 functions will be needed.

Option Box Widgets

An option box can specify any number of ui-widgets, a set of editor tools like sliders, ticks, and buttons that can be used to set ui-symbols.

Radio and popup widgets are collectively called selector widgets. The order of the elements of the widget is unimportant with the exceptions that the variable is the first item and the choices will appear in the order specified. The following apply to both popup widgets and radio widgets. The columns property only applies to ui-radio-widget. It is ignored if specified in a popup widget.

A simple radio widget

; Define the label strings.
(ui-string 'title_symbol_1 "First Choice")
(ui-string 'title_symbol_2 "Second Choice")
(ui-string 'title_symbol_3 "Third Choice")

(ui-radio-widget 'variable
 	(ui-choice				'title_symbol_1					'VALUE1)
 	(ui-choice				'title_symbol_2					'VALUE2)
 	(ui-choice				'title_symbol_3					'VALUE3)
)


A simple popup widget

(ui-popup-widget 'variable
 	(ui-choice				'title_symbol_1					'VALUE1)
 	(ui-choice				'title_symbol_2					'VALUE2)
 	(ui-choice				'title_symbol_3					'VALUE3)
)


Slider widgets allow the entry of data either by keyboard or with the slider.  Below is a double slider.

(ui-string 'ao_set_device_offset            "Offset")

(list 'symbols  'ao_set_device_offset )

(ui-double-widget 'ao_set_device_offset
	list 'precision "%f6.3")
	(list 'slider_range 1 10)
)


A simple tick widget.

(list 'symbols  'nothing.boolean )

(ui-tick-widget     'nothing.boolean)


Tickleft/right

Left:
(list 'symbols 'mo_bevel_front_cap)
(ui-tick-left-widget							'mo_bevel_front_cap)
Right:
(list 'symbols 'mo_bevel_front_cap)
(ui-tick-right-widget							'mo_bevel_back_cap)
If there is a whole group with a tick-left at the end,use the regular ui-tick-widget 
for the last one,otherwise there will be a hole on the right.

Rebuilding Selectors

If a rebuild is desired when a change of value occurs we add the rebuild property.

(ui-radio-widget 'variable
 	(list 'rebuild)
 	(ui-choice				'title_symbol_1					'VALUE1)
 	(ui-choice				'title_symbol_2					'VALUE2)
 	(ui-choice				'title_symbol_3					'VALUE3)
)

Selectively Enabling Selectors

Sometimes the selector should only be displayed under certain conditions.

The enabled property is used to specify this condition. The expression is built from the relational primitives ui-eq (equal), ui-ne (not equal), ui-lt (less than), ui-le (less than or equal), ui-gt (greater than), ui-ge (greater than or equal). The relational primitives can be combined using the logical primitives ui-and, ui-or, and ui-not.

(ui-radio-widget 'variable
 	(list 'enabled (ui-eq 'other_variable 'SOME_VALUE))
 	(list 'rebuild)
 	(ui-choice				'title_symbol_1					'VALUE1)
 	(ui-choice				'title_symbol_2					'VALUE2)
 	(ui-choice				'title_symbol_3					'VALUE3)
)

Changing Number of Columns

The default for radio widgets is two columns. To specify the number of columns use the columns property. The value range is 1, 2 or 3.

(ui-radio-widget 'variable
 	(list 'columns 3)
 	(list 'enabled (ui-eq 'other_variable 'SOME_VALUE))
 	(list 'rebuild)
 	(ui-choice				'title_symbol_1					'VALUE1)
 	(ui-choice				'title_symbol_2					'VALUE2)
 	(ui-choice				'title_symbol_3					'VALUE3)
)

Making Assignments to Variables

When a choice is selected you may assign a value to another variable. For example in the primitives option box the number of caps is set when cylinders or cones are specified.

(ui-radio-widget 'mo_prim_type
 		(list 'rebuild #t)
 		(ui-choice 'prim.type.cube										'MO_CUBE)
 		(ui-choice 'prim.type.plane										'MO_PLANE)
 		(ui-choice 'prim.type.circle										'MO_CIRCLE)
 		(ui-choice 'prim.type.cylinder										'MO_CYLINDER
 			(list 'assign 'mo_prim_caps 2)
 		)
 		(ui-choice 'prim.type.cone										'MO_CONE
 			(list 'assign 'mo_prim_caps 1)
 		)
 		(ui-choice 'prim.type.sphere										'MO_SPHERE)
)

These assignments may be made conditionally. If for example the number of caps for a cone should be set to one only if it was two then we could specify this as

		(ui-choice 'prim.type.cone										'MO_CONE
 			(list 'assign (ui-eq 'mo_prim_caps 2) 'mo_prim_caps 1)
 		)

This way if it was set to zero then it wouldn't change.

Additional Widgets

Separator widget

	(ui-separator-widget)

Note that if the ui-radio-widget has an "enabled" bit to it, the separator widget has to have the same.

[email protected]