===== Dialog programming with finenv.UserValueInput() =====
The dialog object that can be obtained from ''finenv.UserValueInput()'' provides an easy way to add a user interface to the plug-in script. The dialog box automatically reshapes according to the number of required fields, and the number of fields that can be used in the dialog box are virtually unlimited.
The dialog boxes can be input boxes or just contain text information, or a mix of information and user input.
If there are 4 or less fields in a dialog box, each field is displayed as its own control. If there are more than 4 field, the fields are handled in the style of a property list.
==== Create a dialog object ====
To create a dialog object, call the ''finenv.UserValueInput()'' constructor. The return value will be the dialog object. Each time ''finenv.UserValueInput()'' is called, a new object is returned. The dialog will not be displayed directly at construction.
Example:
local dialog = finenv.UserValueInput()
==== Title property ====
The ''Title'' property sets the dialog caption string. This property is **optional**. If this property isn't set, the text //User Value Input// will appear as the dialog box caption text.
Example:
local mydialog = finenv.UserValueInput()
mydialog.Title = "My Input Dialog Box"
==== (FUTURE_VERSION) ReadOnly property ====
The ''ReadOnly'' boolean property can set all the fields in the dialog box to information fields only and remove the Close button from the dialog box. The ''ReadOnly'' property defaults to false. Setting the ''ReadOnly'' property to ''true'' has a higher priority than using the ''SetReadOnlyFields()'' method.
local mydialog = finenv.UserValueInput()
mydialog.ReadOnly = true
==== Defining the dialog fields ====
Setting the information for each field are made with these setter methods:
^ Method Name ^ Description ^
| ''SetTypes'' | Defines the types for the fields (required). |
| ''SetDescriptions'' | Defines the description text for the fields (required). |
| ''SetInitValues'' | Sets the default values for the fields (optional). |
| ''SetLists'' | Sets the available list items for the fields (optional, but required for the "Set" and "NumberedList" types). |
| (FUTURE_VERSION) ''SetReadOnlyFields'' | Defines some fields to read-only information (optional). |
Each field is represented as a parameter to the setter method. If a small number of fields are used, each field can be represented as a separate parameter to the method, such as:
mydialog = finenv.UserValueInput()
mydialog:SetTypes("String", "Boolean", "String")
However, if a **large number of fields** are used (let's say above 6 fields), a table **must** be used a single parameter to the setter, such as:
mydialog = finenv.UserValueInput()
types = {"String", "Boolean", "String", "Number", "Boolean", "Boolean", "Number"}
mydialog:SetTypes(types)
==== SetTypes() method ====
The ''SetTypes()'' method defines:
- How many input values the dialog box should contain.
- What type each input value should have.
A call to ''SetTypes()'' is **required** prior to displaying the dialog box with ''Execute()''.
The type definitions for each field are case-sensitive strings. These types can be used:
^ Type Name ^ Description ^
| ''"String"'' | Any string value, such as "", "My Name", etc |
| ''"Number"'' | Any number (intereger ) value, such as 0, 1.75, 1000, etc. |
| ''"Boolean"'' | A value that can be either ''true'' or ''false''. |
| ''"Measurement"'' | An EVPU number, that is displayed to the user in the preferred measurement unit. |
| (FUTURE_VERSION) ''"Set"'' | A set of options where each one can be toggled ON/OFF, such as {true, false, true} |
| ''"NumberedList"'' | A set options, where one could be selected. Value is a 1-based index number. |
If a large number of fields should be used, always use a table for all the types.
Example:
local thedialog = finenv.UserValueInput()
thedialog:SetTypes("String", "Boolean", "Number")
or:
local thedialog = finenv.UserValueInput()
local types = {"String", "Boolean", "Number"}
thedialog:SetTypes(types)
==== SetDescriptions() method ====
The SetDescriptions() method adds text descriptions for each input value. The number of descriptions must match the number of types.
A call to ''SetDescriptions()'' is **required** prior to displaying the dialog box with ''Execute()''.
The number of description fields must match the number of types. If a large number of fields should be used, always use a table for all the descriptions.
Example:
local thedialog = finenv.UserValueInput()
thedialog:SetDescriptions("Field 1", "Field 2", "Field 3")
or:
local thedialog = finenv.UserValueInput()
descriptions = {"Field 1", "Field 2", "Field 3"}
thedialog:SetDescriptions(descriptions)
==== SetInitValues() ====
The ''SetInitValues()'' method adds initial values to each of the fields. These values will be displayed when the dialog opens.
Example:
local dialog = finenv.UserValueInput()
dialog:SetTypes("String", "Boolean")
dialog:SetInitValues("Oboe", true)
If a **list** (through ''SetLists()'') is connected with a input field and init value isn't found in the list, the topmost item in the list will be selected.
The call to ''SetInitValues()'' is **optional**. (FUTURE_VERSION) However, if a dialog with ''ReadOnly'' content is defined, it wouldn't make much sense to not call it.
==== SetLists() ====
The ''SetLists()'' method connects lists of options to fields. Each list is a table with all available items for the field. If a field doesn't require a list, use ''nil''.
Any field type can have lists:
^ Type ^ Meaning of the list ^ Input/Output Value ^
| ''"String"'' | A popup that will contain the strings. | String |
| ''"Number"'' | A popup that will contain the numbers. | Number |
| ''"Boolean"'' | A popup with a ''true'' and ''false'' string. The first string will represent the ''true'' state, the second string will represent the ''false'' state. More strings than 2 will result in an error. | Boolean |
| ''"Measurement"'' | A popup that will contain the EVPU values displayed in the user's preferred measurement unit. | Number |
| (FUTURE_VERSION) ''"Set"'' | A list with a checkbox at each string. | Table |
| ''"NumberList"'' | A popup that will contain the strings. | 1-based item number. |
A ''SetList()'' call is **optional** for all types, except ''"Set"'' and ''"NumberList"'' where it's **required**. If a large number of fields should be used, always use a table for all the lists (which in this case would mean a table with tables).
Example:
mydialog:SetTypes("String")
mydialog:SetLists({"Flute", "Oboe", "Clarinet"})
If there's any danger that 2 texts in a string list might be identical (such as when a list of all staves in a score is listed), use ''"NumberList'' instead of ''String''.
==== (FUTURE_VERSION) SetReadOnlyFields() ====
The ''SetReadOnlyFields()'' method sets individual fields to read-only text information. Use this only when the dialog box is a mix of information fields and regular input fields. If the dialog box should only contain information fields, use the ''ReadOnly'' property instead.
A call to ''SetReadOnlyFields()'' is **optional**. The number of parameters can be less than in the Types/Description setters, if the fields at the end shouldn't be affected. If a large number of fields should be used, always use a table for all the read-only settings.
mydialog:SetTypes("String", "Number", "Number")
mydialog:SetReadOnlyFields(false, true, true)
==== Execute() method ====
To display the dialog box to the user, use the ''Execute()'' method. The user dialog will be in a modal state until the user press either OK or Cancel.
The **return value** is a table with all user values from the dialog after the user has pressed the OK button. This table is 1-based, so the first user value will be at 1, the next at 2, etc. If the user pressed the Cancel button, the return value is ''nil''.
Example:
local dialog = finenv.UserValueInput()
-- Insert the dialog setup code here
local returnvalues = dialog:Execute()
if returnvalues ~= nil then
-- returnvalues[1] contains the first user input value, returnvalues[2] the second, etc
end