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.