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 (1.9 #99)

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