Table of Contents

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:

  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:

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