## 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