File `fhutils` - function `getParam`

getParam

getParam provides an easy way to prompt used for information. Similar to a simplified iup.GetParam you pass in a set of variables as a table and receive a table back containing the updated values you passed in and a results table.

getParam(sTitle, sTopMessage, fields, tButtons, shortcuts, hParent)

This function allows a dynamic prompt box to be created with 5 different line types with a variety of controls for ranges and prompting.

Parameters

sTitle: Window title to be displayed
sTopMessage: text to be displayed at the top of the prompt; can be nil
fields: table of fields to be displayed
tButtons: table of buttons to be displayed along the bottom of the prompt
shortcuts: table of string tables to use for the autofill on String fields
hParent: Parent Dialog handle

Return value

table fields including result table with values by tag

Fields

STRING: Simply text string which supports auto text, just set the shortcut table for the tag name.
DATE: returns a fhDate Object (supports range checking)
NUMBER: returns a number (supports range checking)
RECORD: returns an item pointer, needs the recordtype field set to the correct type.
LIST: takes two arrays values - the values returned and prompts the values displayed.
BOOLEAN: returns a boolean true/false and displays a tick box

Each field supports the following values:

tag: string, tag for the field, should be unique
label: string, value to show as the label for the field
type: string, as detailed above
value: current value of field (returned from prompt)
child: string, the tag of the field which is the child of this field
childUpdate: function to call when this field is updated; it should return a table of values suitable for the child field.
protect: boolean Protects field from update (iup.ACTIVE = 'NO')

STRING only

lines: makes the field multiline and with a height of the number given for the lines value

DATE and NUMBER only

range: from and to value for field numbers for the NUMBER and fhDate objects for the DATE.

RECORD only

prompt: function to use as an override for the prompt when the button is pressed. A results table will be passed in and it should return the following:
- value - value to be stored against record button
- error - string if error, nil if not
- title - string to display on button

LIST only

prompts: list of values to show; if not set values will be used for the prompts
values: list of values to return
valueNo: the currently selected index number

buttons

List of buttons to show; if none sent an OK button will be added.

The title of the button pressed will be returned in the returned table as .button_pressed and the number as .button_no. button_no will be zero if the dialog is closed.

iup.buttons can also be passed in instead of strings and can have any actions defined. This includes the return from helpButton.

The first button will be disabled when any field fails validation.

Adding an element of vertical=true will display the buttons down rather than across.

shortcuts

Table of lists of strings for the String Autotext, keyed on the tag of the fields they are to be used in. The value of the string is not limited to the values in the shortcut; if mandatory strings are required use LIST instead.

Returned Table

Original passed in table with updated values plus:

ok - boolean true if button 1 (OK) pressed
results table keyed on tag containing the values of all fields

Examples

Simple Yes/No prompt

function yes(sQuestion)
    local r = fh.getParam(sPluginName, sQuestion, {}, {'Yes','No'})
    return r.ok
end

Prompt for Attribute

factFields = {
    {tag="VALU.NEW", label="Fact", type="STRING", value=sValue},
    {tag="DATE.NEW", label="Fact Date", type="DATE", value=dtDate, minlength=1},
    {tag="PLAC.NEW", label=" Fact Place", type="STRING", value=sPlace},
    {tag="ADDR.NEW", label=" Fact Address", type="STRING", value=sAddress},
    {tag="ACTION", label="Action", type="LIST", prompts={'Add new fact'}, value="new", values={'new'}}
}

local p = fh.getParam(sMessage, nil, factFields, {'OK','Skip'}, s)

File fhutils - function getParam