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.

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()

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"

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

Setting the information for each field are made with these setter methods:

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)

The SetTypes() method defines:

1. How many input values the dialog box should contain.
2. 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:

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)

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)

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.

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:

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.

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)

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