path: root/core/.ui.dialogs.luadoc

-- Copyright 2007-2016 Mitchell mitchell.att.foicica.com. See LICENSE.
-- This is a DUMMY FILE used for making LuaDoc for built-in functions in the
-- ui.dialogs table.

--- Provides a set of interactive dialog prompts for user input.
module('ui.dialogs')

---
-- Prompts the user with a generic message box dialog defined by dialog options
-- table *options*, returning the selected button's index.
-- If *options*.`string_output` is `true`, returns the selected button's label.
-- If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-- dialog, returns `-1` or `"delete"`.
-- @param options Table of key-value option pairs for the message box.
--
--   * `title`: The dialog's title text.
--   * `text`: The dialog's main message text.
--   * `informative_text`: The dialog's extra informative text.
--   * `icon`: The dialog's GTK stock icon name. Examples are
--     "gtk-dialog-error", "gtk-dialog-info", "gtk-dialog-question", and
--     "gtk-dialog-warning". The dialog does not display an icon by default.
--   * `icon_file`: The dialog's icon file path. This option has no effect when
--     `icon` is set.
--   * `button1`: The right-most button's label. The default value is
--     `_L['_OK']`.
--   * `button2`: The middle button's label.
--   * `button3`: The left-most button's label. This option requires `button2`
--     to be set.
--   * `string_output`: Return the selected button's label (instead of its
--     index) or the dialog's exit status instead of the button's index (instead
--     of its exit code). The default value is `false`.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
--   * `float`: Show the dialog on top of all desktop windows. The default value
--     is `false`.
--   * `timeout`: The integer number of seconds the dialog waits for the user to
--     select a button before timing out. Dialogs do not time out by default.
-- @return selected button or exit code
-- @usage ui.dialogs.msgbox{title = 'EOL Mode', text = 'Which EOL?',
--   icon = 'gtk-dialog-question', button1 = 'CRLF', button2 = 'CR',
--   button3 = 'LF'}
function msgbox(options) end

---
-- Prompts the user with a generic message box dialog defined by dialog options
-- table *options* and with localized "Ok" and "Cancel" buttons, returning the
-- selected button's index.
-- If *options*.`string_output` is `true`, returns the selected button's label.
-- If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-- dialog, returns `-1` or `"delete"`.
-- @param options Table of key-value option pairs for the message box.
--
--   * `title`: The dialog's title text.
--   * `text`: The dialog's main message text.
--   * `informative_text`: The dialog's extra informative text.
--   * `icon`: The dialog's GTK stock icon name. Examples are
--     "gtk-dialog-error", "gtk-dialog-info", "gtk-dialog-question", and
--     "gtk-dialog-warning". The dialog does not display an icon by default.
--   * `icon_file`: The dialog's icon file path. This option has no effect when
--     `icon` is set.
--   * `no_cancel`: Do not display the "Cancel" button. The default value is
--     `false`.
--   * `string_output`: Return the selected button's label (instead of its
--     index) or the dialog's exit status instead of the button's index (instead
--     of its exit code). The default value is `false`.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
--   * `float`: Show the dialog on top of all desktop windows. The default value
--     is `false`.
--   * `timeout`: The integer number of seconds the dialog waits for the user to
--     select a button before timing out. Dialogs do not time out by default.
-- @return selected button or exit code
function ok_msgbox(options) end

---
-- Prompts the user with a generic message box dialog defined by dialog options
-- table *options* and with localized "Yes", "No", and "Cancel" buttons,
-- returning the selected button's index.
-- If *options*.`string_output` is `true`, returns the selected button's label.
-- If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-- dialog, returns `-1` or `"delete"`.
-- @param options Table of key-value option pairs for the message box.
--
--   * `title`: The dialog's title text.
--   * `text`: The dialog's main message text.
--   * `informative_text`: The dialog's extra informative text.
--   * `icon`: The dialog's GTK stock icon name. Examples are
--     "gtk-dialog-error", "gtk-dialog-info", "gtk-dialog-question", and
--     "gtk-dialog-warning". The dialog does not display an icon by default.
--   * `icon_file`: The dialog's icon file path. This option has no effect when
--     `icon` is set.
--   * `no_cancel`: Do not display the "Cancel" button. The default value is
--     `false`.
--   * `string_output`: Return the selected button's label (instead of its
--     index) or the dialog's exit status instead of the button's index (instead
--     of its exit code). The default value is `false`.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
--   * `float`: Show the dialog on top of all desktop windows. The default value
--     is `false`.
--   * `timeout`: The integer number of seconds the dialog waits for the user to
--     select a button before timing out. Dialogs do not time out by default.
-- @return selected button or exit code
function yesno_msgbox(options) end

---
-- Prompts the user with an inputbox dialog defined by dialog options table
-- *options*, returning the selected button's index along with the user's
-- input text (the latter as a string or table, depending on the type of
-- *options*.`informative_text`).
-- If *options*.`string_output` is `true`, returns the selected button's label
-- along with the user's input text.
-- If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-- dialog, returns `-1` or `"delete"`.
-- @param options Table of key-value option pairs for the inputbox.
--
--   * `title`: The dialog's title text.
--   * `informative_text`: The dialog's main message text. If the value is a
--     table, the first table value is the main message text and any subsequent
--     values are used as the labels for multiple entry boxes. Providing a
--     single label has no effect.
--   * `text`: The dialog's initial input text. If the value is a table, the
--     table values are used to populate the multiple entry boxes defined by
--     `informative_text`.
--   * `button1`: The right-most button's label. The default value is
--     `_L['_OK']`.
--   * `button2`: The middle button's label.
--   * `button3`: The left-most button's label. This option requires `button2`
--     to be set.
--   * `string_output`: Return the selected button's label (instead of its
--     index) or the dialog's exit status instead of the button's index (instead
--     of its exit code). The default value is `false`.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
--   * `float`: Show the dialog on top of all desktop windows. The default value
--     is `false`.
--   * `timeout`: The integer number of seconds the dialog waits for the user to
--     select a button before timing out. Dialogs do not time out by default.
-- @return selected button or exit code, input text
-- @usage ui.dialogs.inputbox{title = 'Goto Line', informative_text = 'Line:',
--   text = '1'}
function inputbox(options) end

---
-- Prompts the user with an inputbox dialog defined by dialog options table
-- *options* and with localized "Ok" and "Cancel" buttons, returning the
-- selected button's index along with the user's input text (the latter as a
-- string or table, depending on the type of *options*.`informative_text`).
-- If *options*.`string_output` is `true`, returns the selected button's label
-- along with the user's input text.
-- If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-- dialog, returns `-1` or `"delete"`.
-- @param options Table of key-value option pairs for the inputbox.
--
--   * `title`: The dialog's title text.
--   * `informative_text`: The dialog's main message text. If the value is a
--     table, the first table value is the main message text and any subsequent
--     values are used as the labels for multiple entry boxes. Providing a
--     single label has no effect.
--   * `text`: The dialog's initial input text. If the value is a table, the
--     table values are used to populate the multiple entry boxes defined by
--     `informative_text`.
--   * `no_cancel`: Do not display the "Cancel" button. The default value is
--     `false`.
--   * `string_output`: Return the selected button's label (instead of its
--     index) or the dialog's exit status instead of the button's index (instead
--     of its exit code). The default value is `false`.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
--   * `float`: Show the dialog on top of all desktop windows. The default value
--     is `false`.
--   * `timeout`: The integer number of seconds the dialog waits for the user to
--     select a button before timing out. Dialogs do not time out by default.
-- @return selected button or exit code, input text
function standard_inputbox(options) end

---
-- Prompts the user with a masked inputbox dialog defined by dialog options
-- table *options*, returning the selected button's index along with the user's
-- input text (the latter as a string or table, depending on the type of
-- *options*.`informative_text`).
-- If *options*.`string_output` is `true`, returns the selected button's label
-- along with the user's input text.
-- If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-- dialog, returns `-1` or `"delete"`.
-- @param options Table of key-value option pairs for the inputbox.
--
--   * `title`: The dialog's title text.
--   * `informative_text`: The dialog's main message text. If the value is a
--     table, the first table value is the main message text and any subsequent
--     values are used as the labels for multiple entry boxes. Providing a
--     single label has no effect.
--   * `text`: The dialog's initial input text. If the value is a table, the
--     table values are used to populate the multiple entry boxes defined by
--     `informative_text`.
--   * `button1`: The right-most button's label. The default value is
--     `_L['_OK']`.
--   * `button2`: The middle button's label.
--   * `button3`: The left-most button's label. This option requires `button2`
--     to be set.
--   * `string_output`: Return the selected button's label (instead of its
--     index) or the dialog's exit status instead of the button's index (instead
--     of its exit code). The default value is `false`.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
--   * `float`: Show the dialog on top of all desktop windows. The default value
--     is `false`.
--   * `timeout`: The integer number of seconds the dialog waits for the user to
--     select a button before timing out. Dialogs do not time out by default.
-- @return selected button or exit code, input text
function secure_inputbox(options) end

---
-- Prompts the user with a masked inputbox dialog defined by dialog options
-- table *options* and with localized "Ok" and "Cancel" buttons, returning the
-- selected button's index along with the user's input text (the latter as a
-- string or table, depending on the type of *options*.`informative_text`).
-- If *options*.`string_output` is `true`, returns the selected button's label
-- along with the user's input text.
-- If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-- dialog, returns `-1` or `"delete"`.
-- @param options Table of key-value option pairs for the inputbox.
--
--   * `title`: The dialog's title text.
--   * `informative_text`: The dialog's main message text. If the value is a
--     table, the first table value is the main message text and any subsequent
--     values are used as the labels for multiple entry boxes. Providing a
--     single label has no effect.
--   * `text`: The dialog's initial input text. If the value is a table, the
--     table values are used to populate the multiple entry boxes defined by
--     `informative_text`.
--   * `no_cancel`: Do not display the "Cancel" button. The default value is
--     `false`.
--   * `string_output`: Return the selected button's label (instead of its
--     index) or the dialog's exit status instead of the button's index (instead
--     of its exit code). The default value is `false`.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
--   * `float`: Show the dialog on top of all desktop windows. The default value
--     is `false`.
--   * `timeout`: The integer number of seconds the dialog waits for the user to
--     select a button before timing out. Dialogs do not time out by default.
-- @return selected button or exit code, input text
function secure_standard_inputbox(options) end

---
-- Prompts the user with a file selection dialog defined by dialog options
-- table *options*, returning the string file selected.
-- If *options*.`select_multiple` is `true`, returns the list of files selected.
-- If the user canceled the dialog, returns `nil`.
-- @param options Table of key-value option pairs for the dialog.
--
--   * `title`: The dialog's title text.
--   * `with_directory`: The initial filesystem directory to show.
--   * `with_file`: The initially selected filename. This option requires
--     `with_directory` to be set.
--   * `with_extension`: The list of extensions selectable files must have.
--   * `select_multiple`: Allow the user to select multiple files. The default
--     value is `false`.
--   * `select_only_directories`: Only allow the user to select directories. The
--     default value is `false`.
-- @return filename, list of filenames, or nil
-- @usage ui.dialogs.fileselect{title = 'Open C File', with_directory = _HOME,
--   with_extension = {'c', 'h'}, select_multiple = true}
function fileselect(options) end

---
-- Prompts the user with a file save dialog defined by dialog options table
-- *options*, returning the string file chosen.
-- If the user canceled the dialog, returns `nil`.
-- @param options Table of key-value option pairs for the dialog.
--
--   * `title`: The dialog's title text.
--   * `with_directory`: The initial filesystem directory to show.
--   * `with_file`: The initially chosen filename. This option requires
--     `with_directory` to be set.
--   * `with_extension`: The list of extensions selectable files must have.
--   * `no_create_directories`: Prevent the user from creating new directories.
--     The default value is `false`.
-- @return filename or nil
function filesave(options) end

---
-- Prompts the user with a multiple-line textbox dialog defined by dialog
-- options table *options*, returning the selected button's index.
-- If *options*.`string_output` is `true`, returns the selected button's label.
-- If *options*.`editable` is `true`, also returns the textbox's text. If the
-- dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-- dialog, returns `-1` or `"delete"`.
-- @param options Table of key-value option pairs for the dialog.
--
--   * `title`: The dialog's title text.
--   * `informative_text`: The dialog's main message text.
--   * `text`: The dialog's initial textbox text.
--   * `text_from_file`: The filename whose contents are loaded into the
--     textbox. This option has no effect when `text` is given.
--   * `button1`: The right-most button's label. The default value is
--     `_L['_OK']`.
--   * `button2`: The middle button's label.
--   * `button3`: The left-most button's label. This option requires `button2`
--     to be set.
--   * `editable`: Allows the user to edit the textbox's text. The default value
--     is `false`.
--   * `focus_textbox`: Focus the textbox instead of the buttons. The default
--     value is `false`.
--   * `scroll_to`: Where to scroll the textbox's text.
--     The available values are `"top"` and `"bottom"`. The default value is
--     `"top"`.
--   * `selected`: Select all of the textbox's text. The default value is
--     `false`.
--   * `monospaced_font`: Use a monospaced font in the textbox instead of a
--     proportional one. The default value is `false`.
--   * `string_output`: Return the selected button's label (instead of its
--     index) or the dialog's exit status instead of the button's index (instead
--     of its exit code). The default value is `false`.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
--   * `float`: Show the dialog on top of all desktop windows. The default value
--     is `false`.
--   * `timeout`: The integer number of seconds the dialog waits for the user to
--     select a button before timing out. Dialogs do not time out by default.
-- @return selected button or exit code, textbox text
-- @usage ui.dialogs.textbox{title = 'License Agreement',
--   informative_text = 'You agree to:', text_from_file = _HOME..'/LICENSE'}
function textbox(options) end

---
-- Prompts the user with a drop-down item selection dialog defined by dialog
-- options table *options*, returning the selected button's index along with the
-- index of the selected item.
-- If *options*.`string_output` is `true`, returns the selected button's label
-- along with the selected item's text.
-- If the dialog closed due to *options*.`exit_onchange`, returns `4` along with
-- either the selected item's index or its text. If the dialog timed out,
-- returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or
-- `"delete"`.
-- @param options Table of key-value option pairs for the drop-down dialog.
--
--   * `title`: The dialog's title text.
--   * `text`: The dialog's main message text.
--   * `items`: The list of string items to show in the drop-down.
--   * `button1`: The right-most button's label. The default value is
--     `_L['_OK']`.
--   * `button2`: The middle button's label.
--   * `button3`: The left-most button's label. This option requires `button2`
--     to be set.
--   * `exit_onchange`: Close the dialog after selecting a new item. The default
--     value is `false`.
--   * `select`: The index of the initially selected list item. The default
--     value is `1`.
--   * `string_output`: Return the selected button's label (instead of its
--     index) and the selected item's text (instead of its index). If no item
--     was selected, returns the dialog's exit status (instead of its exit
--     code). The default value is `false`.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
--   * `float`: Show the dialog on top of all desktop windows. The default value
--     is `false`.
--   * `timeout`: The integer number of seconds the dialog waits for the user to
--     select a button before timing out. Dialogs do not time out by default.
-- @return selected button or exit code, selected item
-- @usage ui.dialogs.dropdown{title = 'Select Encoding', width = 200,
--   items = io.encodings, string_output = true}
function dropdown(options) end

---
-- Prompts the user with a drop-down item selection dialog defined by dialog
-- options table *options* and with localized "Ok" and "Cancel" buttons,
-- returning the selected button's index along with the selected item's index.
-- If *options*.`string_output` is `true`, returns the selected button's label
-- along with the selected item's text.
-- If the dialog closed due to *options*.`exit_onchange`, returns `4` along with
-- either the selected item's index or its text. If the dialog timed out,
-- returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or
-- `"delete"`.
-- @param options Table of key-value option pairs for the drop-down dialog.
--
--   * `title`: The dialog's title text.
--   * `text`: The dialog's main message text.
--   * `items`: The list of string items to show in the drop-down.
--   * `no_cancel`: Do not display the "Cancel" button. The default value is
--     `false`.
--   * `exit_onchange`: Close the dialog after selecting a new item. The default
--     value is `false`.
--   * `select`: The index of the initially selected list item. The default
--     value is `1`.
--   * `string_output`: Return the selected button's label (instead of its
--     index) and the selected item's text (instead of its index). If no item
--     was selected, returns the dialog's exit status (instead of its exit
--     code). The default value is `false`.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
--   * `float`: Show the dialog on top of all desktop windows. The default value
--     is `false`.
--   * `timeout`: The integer number of seconds the dialog waits for the user to
--     select a button before timing out. Dialogs do not time out by default.
-- @return selected button or exit code, selected item
function standard_dropdown(options) end

---
-- Prompts the user with a filtered list item selection dialog defined by dialog
-- options table *options*, returning the selected button's index along with the
-- index or indices of the selected item or items (depending on whether or not
-- *options*.`select_multiple` is `true`).
-- If *options*.`string_output` is `true`, returns the selected button's label
-- along with the text of the selected item or items.
-- If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-- dialog, returns `-1` or `"delete"`.
-- Spaces in the filter text are treated as wildcards.
-- @param options Table of key-value option pairs for the filtered list dialog.
--
--   * `title`: The dialog's title text.
--   * `informative_text`: The dialog's main message text.
--   * `text`: The dialog's initial input text.
--   * `columns`: The list of string column names for list rows.
--   * `items`: The list of string items to show in the filtered list.
--   * `button1`: The right-most button's label. The default value is
--     `_L['_OK']`.
--   * `button2`: The middle button's label.
--   * `button3`: The left-most button's label. This option requires `button2`
--     to be set.
--   * `select_multiple`: Allow the user to select multiple items. The default
--     value is `false`.
--   * `search_column`: The column number to filter the input text against. The
--     default value is `1`. This option requires `columns` to be set and
--     contain at least *n* column names.
--   * `output_column`: The column number to use for `string_output`. The
--     default value is `1`. This option requires `columns` to be set and
--     contain at least *n* column names.
--   * `string_output`: Return the selected button's label (instead of its
--     index) and the selected item's text (instead of its index). If no item
--     was selected, returns the dialog's exit status (instead of its exit
--     code). The default value is `false`.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
--   * `float`: Show the dialog on top of all desktop windows. The default value
--     is `false`.
--   * `timeout`: The integer number of seconds the dialog waits for the user to
--     select a button before timing out. Dialogs do not time out by default.
-- @return selected button or exit code, selected item or list of selected items
-- @usage ui.dialogs.filteredlist{title = 'Title', columns = {'Foo', 'Bar'},
--   items = {'a', 'b', 'c', 'd'}}
function filteredlist(options) end

---
-- Prompts the user with an option selection dialog defined by dialog options
-- table *options*, returning the selected button's index along with the indices
-- of the selected options.
-- If *options*.`string_output` is `true`, returns the selected button's label
-- along with the text of the selected options.
-- If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-- dialog, returns `-1` or `"delete"`.
-- @param options Table of key-value option pairs for the option select dialog.
--
--   * `title`: The dialog's title text.
--   * `text`: The dialog's main message text.
--   * `items`: The list of string options to show in the option group.
--   * `button1`: The right-most button's label. The default value is
--     `_L['_OK']`.
--   * `button2`: The middle button's label.
--   * `button3`: The left-most button's label. This option requires `button2`
--     to be set.
--   * `select`: The indices of initially selected options.
--   * `string_output`: Return the selected button's label or the dialog's exit
--     status along with the selected options' text instead of the button's
--     index or the dialog's exit code along with the options' indices. The
--     default value is `false`.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
--   * `float`: Show the dialog on top of all desktop windows. The default value
--     is `false`.
--   * `timeout`: The integer number of seconds the dialog waits for the user to
--     select a button before timing out. Dialogs do not time out by default.
-- @return selected button or exit code, list of selected options
-- @usage ui.dialogs.optionselect{title = 'Language',
--   informative_text = 'Check the languages you understand'
--   items = {'English', 'Romanian'}, select = 1, string_output = true}
function optionselect(options) end