The Dialog module

The dialog module provides a relatively simple way to create some fairly complex dialog boxes for user interaction.  The general idea is very loosely based on HTML forms.

The functions are described below. The  dlg  argument expects a dialog object, most other arguments are strings, unless otherwise noted.

Note that you can also use these functions in object-oriented style:
  For instance   dialog.label(dlg, "hello") 
  can also be written as   dlg:label("hello")


function dialog.new ( title, buttons )

Creates a new dialog object. The title string assigns the window's title bar text for the dialog.   The  buttons  argument is a table of strings, where each string will create a button with that text and add it to the bottom row of the dialog. If a button's text contains an underscore, the letter after it will be seen as an underlined accelerator for the button.


function dialog.run ( dlg )

Displays the dialog to the user and waits for submission.

This function returns two values:  the one-based index of the the clicked button, and a results table containing key-value pairs collected from the dialog's elements.

If the user cancels the dialog e.g. by pressing the [Esc] key, the index will be zero, and the results table will be nil.


function dialog.label ( dlg, text )

Adds some informative text to the dialog.


function dialog.hr ( dlg )

Draws a horizontal separator across the dialog.


function dialog.heading ( dlg, text )

Adds a horizontal separator with some informative text below it.

This function is the same as calling the hr() and label() functions individually.


function dialog.text ( dlg, key, default, prompt )

Creates a single-line text entry widget.

The value of the key field in the results table will be set to the contents of the entry box.
If the default string is non-nil, that text will initially be displayed in the entry box.
The prompt string displays a label in front of the entry box to describe the requested input.


function dialog.password ( dlg, key, default, prompt )

Identical to the text() function, except that the contents of the entry box are "masked", the characters are displayed as asterisks.


function dialog.textarea ( dlg, key, default, caption )

Creates a multi-line text entry widget.

The value of the key field in the results table will be set to the contents of the text area.
If the default string is non-nil, that text will initially be displayed in the text area.
The caption string displays a label above the text area to describe the requested input.


function dialog.checkbox ( dlg, key, default, caption )

Creates an on/off toggle button.

If the boolean default argument is true, the button will initially be shown in a "checked" state.
The caption argument is the human-readable text to be displayed next to the button.

Note that although the default argument is boolean, the key value returned in the results table will be a string, either  "1"  for checked or  "0"  for unchecked.


function dialog.select ( dlg, key, default, caption )

Creates an empty drop-down list box.

The contents of the key field in the results table will be set to the value of the selected item.
If the default string is non-nil, the item with that value will initially be selected in the list.
The caption string displays a label in front of the list box to describe the requested input.


function dialog.option ( dlg, key, value, label )

Adds an item to the drop-down list identified by key.

The returned value of key will be set to this value in the results table if this item is selected.
The label argument is the human-readable text to be displayed in the list.


function dialog.group ( dlg, key, default, caption )

Creates an empty group for radio buttons.

The contents of the key field in the results table will be set to the value of the selected radio button.
If the default string is non-nil, the button with that value will initially be selected in the group.
The caption string displays a label above of the group to describe the requested input.


function dialog.radio ( dlg, key, value, label )

Adds a button to the radio group identified by key.

The returned value of key will be set to this value in the results table if this button is selected.
The label argument is the human-readable text to be displayed next to this button.


function dialog.file ( dlg, key, default, caption )

Creates a single-line text entry widget, along with a "browse" button that invokes a separate file-selection dialog.
If the user selects a filename in the file dialog, the text in the entry widget will be set to the selected filename.

The value of the key field in the results table will be set to the contents of the entry box.


function dialog.color ( dlg, key, default, caption )

Creates a single-line text entry widget, along with a "choose" button that invokes a separate color-selection dialog.
If the user selects a color from the dialog, the text in the entry widget will be set to the selected color name in  #RRGGBB  format.

The value of the key field in the results table will be set to the contents of the entry box.


function dialog.font ( dlg, key, default, caption )

Creates a single-line text entry widget, along with a "select" button that invokes a separate font-selection dialog.
If the user selects a font from the dialog, the text in the entry widget will be set to the font name.

The value of the key field in the results table will be set to the contents of the entry box.




© 2007-2008 Jeff Pohlmeyer