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

-- Copyright 2007-2022 Mitchell. 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 icon name, according to the Free Desktop Icon Naming
--     Specification. Examples are "dialog-error", "dialog-information", "dialog-question",
--     and "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 = '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 icon name, according to the Free Desktop Icon Naming
--     Specification. Examples are "dialog-error", "dialog-information", "dialog-question",
--     and "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 icon name, according to the Free Desktop Icon Naming
--     Specification. Examples are "dialog-error", "dialog-information", "dialog-question",
--     and "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

---
-- Displays a progressbar dialog, defined by dialog options table *options*, that receives
-- updates from function *f*.
-- Returns "stopped" if *options*.`stoppable` is `true` and the user clicked the "Stop"
-- button. Otherwise, returns `nil`.
-- @param options Table of key-value option pairs for the progressbar dialog.
--
--   * `title`: The dialog's title text.
--   * `percent`: The initial progressbar percentage between 0 and 100.
--   * `text`: The initial progressbar display text (GTK only).
--   * `indeterminate`: Show the progress bar as "busy", with no percentage updates.
--   * `stoppable`: Show the "Stop" button.
--   * `width`: The dialog's pixel width.
--   * `height`: The dialog's pixel height.
-- @param f Function repeatedly called to do work and provide progress updates. The function is
--   called without arguments and must return either `nil`, which indicates work is complete,
--   or a progress percentage number in the range 0-100 and an optional string to display (GTK
--   only). If the text is either "stop disable" or "stop enable" and *options*.`stoppable` is
--   `true`, the "Stop" button is disabled or enabled, respectively.
-- @return nil or "stopped"
-- @usage ui.dialogs.progressbar({stoppable = true},
--   function() if work() then return percent, status else return nil end end)
function progressbar(options, f) 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. The default width stretches nearly the width of
--     Textadept's window.
--   * `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

---
-- Prompts the user with a color selection dialog defined by dialog options table *options*,
-- returning the color selected.
-- If the user canceled the dialog, returns `nil`.
-- @param options Table of key-value option pairs for the option select dialog.
--
--   * `title`: The dialog's title text.
--   * `color`: The initially selected color as either a number in "0xBBGGRR" format, or as a
--     string in "#RRGGBB" format.
--   * `palette`: The list of colors to show in the dialog's color palette. Up to 20 colors can
--     be specified as either numbers in "0xBBGGRR" format or as strings in "#RRGGBB" format. If
--     `true` (no list was given), a default palette is shown.
--   * `string_output`: Return the selected color in string "#RRGGBB" format instead of as a
--     number. The default value is `false`.
--   * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
-- @return selected color
-- @usage ui.dialogs.colorselect{title = 'Foreground color', color = 0x000000,
--   palette = {'#000000', 0x0000FF, '#00FF00', 0xFF0000}}
function colorselect(options) end

---
-- Prompts the user with a font selection dialog defined by dialog options table *options*,
-- returning the font selected (including style and size).
-- If the user canceled the dialog, returns `nil`.
-- @param options Table of key-value option pairs for the option select dialog.
--
--   * `title`: The dialog's title text.
--   * `text`: The font preview text.
--   * `font_name`: The initially selected font name.
--   * `font_size`: The initially selected font size. The default value is `12`.
--   * `font_style`: The initially selected font style. The available options are `"regular"`,
--     `"bold"`, `"italic"`, and `"bold italic"`. The default value is `"regular"`.
--   * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
-- @return selected font, including style and size
-- @usage ui.dialogs.fontselect{title = 'Font', font_name = 'Monospace', font_size = 10}
function fontselect(options) end