Common Dialog API - WIN

The Common Dialog API provides a series of common purpose popupFrame dialogs, used frequently in application writing, and are utilized in the win API itself.

Functions

See also API Reference, WIN.

cmndlg.color

result cmndlg.color (owner_frame, init_color, bgcolor)

Displays a dialog to select a color.

Parameters
owner_frame parentFrame The owner frame of the dialog. Must be the currently active frame in the application (applicationFrame or popupFrame).
init_color number/nil The initially selected color, term.colors.black if nil.
bgcolor number/nil Background color of the dialog, the theme's popup_back color if nil.

Returns
result number/nil The color selected on Ok, otherwise nil.

Remarks
The following example gains a color from the user.
local last_color = term.colors.black
local color = cmndlg.color (appFrame, last_color) if color then    last_color = color end

top


cmndlg.confirm

result cmndlg.confirm (owner_frame, title, message, default_ok, bgcolor)

Displays a message dialog with an Ok button.

Parameters
owner_frame parentFrame The owner frame of the dialog. Must be the currently active frame in the application (applicationFrame or popupFrame).
title string Text to display in title bar.
message string The message to display to the user.
default_ok boolean If true the Ok button initially has input focus, otherwise the close button.
bgcolor number/nil Background color of the dialog, the theme's popup_back color if nil.

Returns
result boolean True if the user selects Ok, false otherwise.

Remarks
The following example asks the user if they wish to continue, with the close button initially active:
if cmndlg.confirm (appFrame, "Continue", "Do you want to continue?") then
   -- do something
end

top


cmndlg.file

result cmndlg.file (owner_frame, title, init_path, prompt_overwrite, not_hidden, hide_new_dir, validate, bgcolor)

Displays a file chooser dialog.

Parameters
owner_frame parentFrame The owner frame of the dialog. Must be the currently active frame in the application (applicationFrame or popupFrame).
title string Text to display in title bar.
init_path string The initial path for the file dialog. Root if nil.
prompt_overwrite boolean If true an overwrite confirmation is sought if the file exists, otherwise no confirmation.
not_hidden boolean If true hidden files and folders are not displayed in the file list, otherwise they are (names that start with a .).
hide_new_dir boolean If true the button to create a new folder is hidden, otherwise visible.
validate function/nil A function that will be called to validate the file path. No validation if nil.
bgcolor number/nil Background color of the dialog, the theme's popup_back color if nil.

Returns
result string/nil The selected full file path on Ok, otherwise nil.

Remarks
If a validation function is specified, if it returns false the dialog will remain active, and the file name field selected and placed into error state. Otherwise the dialog dismisses returning the full path. The validation function is of the form:

continue validate (path)

See cmndlg.save_file, cmndlg.open_file.


top


cmndlg.input

result cmndlg.input (owner_frame, title, prompt, init_text, banner, max_len, validate, bgcolor)

Displays a single input field dialog with an Ok button.

Parameters
owner_frame parentFrame The owner frame of the dialog. Must be the currently active frame in the application (applicationFrame or popupFrame).
title string Text to display in title bar.
prompt string Text to display in the prompt label.
init_text string/nil Initial text in the input field, empty if nil.
banner string/nil Banner text for the input field, none if nil.
max_len number/nil Maximum character length that may be entered by the user, unlimited if nil.
validate function/nil A function that will be called to validate the user input. No validation if nil.
bgcolor number/nil Background color of the dialog, the theme's popup_back color if nil.

Returns
result string/nil The user input if Ok, otherwise nil.

Remarks
If a validation function is specified, if it returns false the dialog will remain active, and the input field selected and placed into error state. Otherwise the dialog dismisses returning the input. The validation function is of the form:

continue validate (user_input)

The following example gains user input for a file name. The validation ensures the entered is not empty and does not contain a "/" character.
local function validate (str)
   return (string.len (str) > 0 and string.find (str, "/", 1) == nil)
end

local name = cmndlg.input (appFrame, "New File", "Enter the new file name", nil, nil, nil, validate) if name then    appFrame:msgbox ("You entered", name) end

top


cmndlg.open_file

result cmndlg.open_file (owner_frame, init_path, not_hidden, validate, bgcolor)

Wraps cmndlg.file with suitable parameters for an open file operation, and provides initial validation that the selected file exists.

Parameters
owner_frame parentFrame The owner frame of the dialog. Must be the currently active frame in the application (applicationFrame or popupFrame).
init_path string The initial path for the file dialog. Root if nil.
not_hidden boolean If true hidden files and folders are not displayed in the file list, otherwise they are (names that start with a .).
validate function/nil A function that will be called to validate the file path. No validation if nil.
bgcolor number/nil Background color of the dialog, the theme's popup_back color if nil.

Returns
result string The selected full file path on Ok, otherwise nil.

Remarks
If a validation function is specified, if it returns false the dialog will remain active, and the file name field selected and placed into error state. Otherwise the dialog dismisses returning the full path. The validation function is of the form:

continue validate (path)

The following example gains a file path from the user.
local last_path
local path = cmndlg.open_file (appFrame, last_path) if path then    last_path = path end
See cmndlg.save_file.


top


cmndlg.print

printer, from_page, to_page cmndlg.print (owner_frame, total_pages, bgcolor)

Displays a dialog to select an available printer, and optionally enter a page range.

Parameters
owner_frame parentFrame The owner frame of the dialog. Must be the currently active frame in the application (applicationFrame or popupFrame).
total_pages number/nil The total pages available to print. If nil the page range controls are not displayed.
bgcolor number/nil Background color of the dialog, the theme's popup_back color if nil.

Returns
printer string/nil The selected printer's digilines channel on Ok, otherwise nil.
from_page number/nil On Ok, if total_pages was specified then the first page to print. If total_pages was not specified then zero. On close is always nil.
to_page number/nil On Ok, if total_pages was specified then the last page to print. If total_pages was not specified then zero. On close is always nil.

Remarks
The following example gains a printer from the user.
local printer = cmndlg.print (appFrame)
if printer then
   appFrame:msgbox ("You Selected", printer)
end

top


cmndlg.save_file

result cmndlg.save_file (owner_frame, init_path, not_hidden, validate, bgcolor)

Wraps cmndlg.file with suitable parameters for a save file operation.

Parameters
owner_frame parentFrame The owner frame of the dialog. Must be the currently active frame in the application (applicationFrame or popupFrame).
init_path string The initial path for the file dialog. Root if nil.
not_hidden boolean If true hidden files and folders are not displayed in the file list, otherwise they are.
validate function/nil A function that will be called to validate the file path. No validation if nil.
bgcolor number/nil Background color of the dialog, the theme's popup_back color if nil.

Returns
result string The selected full file path on Ok, otherwise nil.

Remarks
If a validation function is specified, if it returns false the dialog will remain active, and the file name field selected and placed into error state. Otherwise the dialog dismisses returning the full path. The validation function is of the form:

continue validate (path)

The following example gains the file path from the user.
local last_path;
local path = cmndlg.save_file (appFrame, last_path) if path then    last_path = path end

See cmndlg.open_file.


top


See also API Reference, WIN.