Most reusable components need to be customized when reused in a particular application. Although underlying mechanisms may vary (e.g., inheritance), the component is typically customized by modifying it's properties.
In MiceOnABeam, the main structural component is the State and it's properties are represented by it's State Variables. To customize the way a state works, you can change the initial values of one or more of it's state variables.
When reusing a state, instead of having to manually modify the LSL code that sets these values, you can designate a state variable as configurable by setting the Configure flag in the State Variables & Functions editor. By doing so the state will be able to be customized through the Component Configuration Wizard, which will create a convenient form containing all the configurable variables of a state that can be simply filled in by the user of that reusable state component.
For example, the following shows the state variables for the ShowMenu reusable state component. Several of it's variables have been designated as configurable.
If a state has one or more configurable state variables then a special icon will be placed on the state as follows:
The Component Configuration Wizard can then be opened for the state by selecting Configure Component from it's context menu.
The top pane of the Component Configuration Wizard provides a description of the state component and instructions on it's usage. This information is taken from the comment that has been assigned to the state through the Edit Comment menu item of the state's context menu.
After the initialization code has been entered the OK button is selected to save the changes and close the wizard.
There are a number of options associated with setting a state variable as configurable. Clicking the Configure checkbox for the variable in the State Variable & Functions editor will bring up the State Variable Configure Options dialog.
The following Configuration Modes are available:
Not Configured: The state variable is not configurable and will be set to it's initial value only once upon script startup (script is reset). This is the default option for a standard state variable.
Configured: Init On Startup: The state variable is configurable and will be set to it's Initial Value only once upon script startup. An unassigned Initial Value will be set from the Default field. Due to LSL restrictions on global variables, these values may only be simple constants; no complex expressions are permitted. As a result, entering in a complex LSL expression here will flag a parsing error.
Configured: Init On State Entry: The state variable is configurable and will be set to it's Initial Value each time the state is entered. An unassigned Initial Value will be set from the Default field. As the variable will be re-initialized on state entry, any valid LSL expression may be used here.
Configured: Replacement Code: The state variable is configurable. The LSL code entered here will be the initialization value set for the state variable each time the state is entered. This mode can also be used when the initialization value for the variable will be computed based on the values of other state variables.
Use %%Value to refer to the value entered by the user during configuration. Use %% as a prefix before any variable name to reference the expanded value of that variable. See Using Replacement Code below for further details.
Configured: Choices: The state variable is configurable. Select this mode to restrict the initialization value for the state variable to one of the values in the Choices table each time the state is entered. If Replacement Code is entered for a Choice, it will replace the value of the Choice name as the initialization value for the state variable.
►Note: For flexibility, during configuration a user can always override the provided choices and enter in their own LSL code. This capability is controlled by option, and is set true by default.
If more than one choice can be selected at the same time, select a connector which will be used to join the selected choices.
If the corresponding state variable type is specified as an LSL list, then the Choice Replacement Code value can be of any type and will be automatically enclosed within the list brackets [ and ], unless the value specified is already enclosed in list brackets.
The following shows the configure options for the UserID variable.
When configuring the state the user will be then be provided with two choices to select from in the Component Configuration Wizard. Note also that the comment entered for the choice is used for it's pop-up help.
Replacement Code is a powerful feature that can be used when setting the configure options for a state variable. It can be used as one of the Configuration Modes or as part of a choice's definition when several choices are specified for a state variable.
The replacement code consists of LSL code that can include the following references:
The value entered by the user during component configuration, represented by "%%Value";
Other state variables, represented by the variable name prefixed with "%%";
During code generation all references are fully expanded and the net result will form the initialization code for the variable.
►Note: As state variable initialization specifications may reference each other, transitive self-references must be avoided. MiceOnABeam will detect such occurrences and flag them during code generation.