# gui

Utilities for interacting with Textadept's user interface.

- - -

## Fields

- - -

<a id="clipboard_text"></a>
### `clipboard_text` (string, Read-only)

The text on the clipboard.

- - -

<a id="context_menu"></a>
### `context_menu` 

The editor's context menu, a [`gui.menu()`](#menu).
  This is a low-level field. You probably want to use the higher-level
  `_M.textadept.menu.set_contextmenu()`.

- - -

<a id="docstatusbar_text"></a>
### `docstatusbar_text` (string, Write-only)

The text displayed by the buffer statusbar.

- - -

<a id="statusbar_text"></a>
### `statusbar_text` (string, Write-only)

The text displayed by the statusbar.

- - -

<a id="title"></a>
### `title` (string, Write-only)

The title of the Textadept window.

- - -


## Functions

- - -

<a id="_print"></a>
### `_print`(*buffer\_type, ...*)

Helper function for printing messages to buffers.
Splits the view and opens a new buffer for printing messages to. If the
message buffer is already open in a view, the message is printed to that
view. Otherwise the view is split and the message buffer is opened or
displayed before being printed to.

Parameters:

* *`buffer_type`*: String type of message buffer.
* *`...`*: Message strings.

Usage:

* `gui._print(_L['[Message Buffer]'], message)`

- - -

<a id="dialog"></a>
### `dialog`(*kind, ...*)

Displays a *kind* [gtdialog][] with the given string arguments to pass to
the dialog and returns a formatted string of the dialog's output.
Table arguments containing strings are allowed and expanded in place. This is
useful for filtered list dialogs with many items.
For more information on gtdialog, see [http://foicica.com/gtdialog][].

[gtdialog]: http://foicica.com/gtdialog/02_Usage.html
[http://foicica.com/gtdialog]: http://foicica.com/gtdialog

Parameters:

* *`kind`*: The kind of gtdialog.
* *`...`*: Parameters to the gtdialog.

Return:

* string gtdialog result.

- - -

<a id="filteredlist"></a>
### `filteredlist`(*title, columns, items, int\_return, ...*)

Convenience function for `gui.dialog('filteredlist', ...)` with "Ok" and
"Cancel" buttons that returns the text or index of the selection depending on
the boolean value of *int_return*.
*title* is the title of the dialog, *columns* is a list of column names, and
*items* is a list of items to show.

Parameters:

* *`title`*: The title for the filtered list dialog.
* *`columns`*: A column name or list of column names.
* *`items`*: An item or list of items.
* *`int_return`*: Optional flag indicating whether to return the integer
  index of the selected item in the filtered list or the string selected
  item. A `true` value is not compatible with the `'--select-multiple'`
  option. The default value is `false`.
* *`...`*: Optional additional parameters to pass to `gui.dialog()`.

Usage:

* `gui.filteredlist('Title', 'Foo', {'Bar', 'Baz'})`
* `gui.filteredlist('Title', {'Foo', 'Bar'}, {'a', 'b', 'c', 'd'}, false,
                        '--output-column', '2')`

Return:

* Either a string or integer on success; `nil` otherwise. In strings,
  multiple items are separated by newlines.

See also:

* [`dialog`](#dialog)

- - -

<a id="get_split_table"></a>
### `get_split_table`()

Returns the current split view structure.
This is primarily used in session saving.

Return:

* table of split views. Each split view entry is a table with 4
  fields: `1`, `2`, `vertical`, and `size`. `1` and `2` have values of either
  nested split view entries or the views themselves; `vertical` is a flag
  indicating if the split is vertical or not; and `size` is the integer
  position of the split resizer.

- - -

<a id="goto_file"></a>
### `goto_file`(*filename, split, preferred\_view, sloppy*)

Goes to the buffer whose filename is *filename* in an existing view,
otherwise splitting the current view if *split* is `true` or going to the
next or *preferred_view* view instead of staying in the current one.
If *sloppy* is `true`, only the last part of *filename* is matched to a
buffer's `filename`.

Parameters:

* *`filename`*: The filename of the buffer to go to.
* *`split`*: Optional flag indicating whether or not to open the buffer in a
  split view if there is only one view. The default value is `false`.
* *`preferred_view`*: Optional view to open the desired buffer in if the
  buffer is not visible in any other view.
* *`sloppy`*: Optional flag indicating whether or not to not match *filename*
  to `buffer.filename` exactly. When `true`, matches *filename* to only the
  last part of `buffer.filename` This is useful for run and compile commands
  which output relative filenames and paths instead of full ones and it is
  likely that the file in question is already open. The default value is
  `false`.

- - -

<a id="goto_view"></a>
### `goto_view`(*n, relative*)

Goes to view number *n*.
If *relative* is `true`, *n* is an index relative to the index of the current
view in `_G._VIEWS` instead of an absolute index.
Emits `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events.

Parameters:

* *`n`*: A relative or absolute view index in `_G._VIEWS`.
* *`relative`*: Optional flag indicating whether *n* is a relative or
  absolute index. The default value is `false`, for an absolute index.

See also:

* [`_G._VIEWS`](_G.html#_VIEWS)
* [`events.VIEW_BEFORE_SWITCH`](events.html#VIEW_BEFORE_SWITCH)
* [`events.VIEW_AFTER_SWITCH`](events.html#VIEW_AFTER_SWITCH)

- - -

<a id="menu"></a>
### `menu`(*menu\_table*)

Low-level function for creating a menu from table *menu_table* and returning
the userdata.
You probably want to use the higher-level `_M.textadept.menu.set_menubar()`
or `_M.textadept.menu.set_contextmenu()` functions. Emits a `MENU_CLICKED`
event when a menu item is selected.

Parameters:

* *`menu_table`*: A table defining the menu. It is an ordered list of tables
  with a string menu item, integer menu ID, and optional GDK keycode and
  modifier mask. The latter two are used to display key shortcuts in the
  menu. '_' characters are treated as a menu mnemonics. If the menu item is
  empty, a menu separator item is created. Submenus are just nested
  menu-structure tables. Their title text is defined with a `title` key.

Usage:

* `gui.menu{{'_New', 1}, {'_Open', 2}, {''}, {'_Quit', 4}}`
* `gui.menu{{'_New', 1, string.byte('n'), 4}} -- 'Ctrl+N'`

See also:

* [`events.MENU_CLICKED`](events.html#MENU_CLICKED)
* [`_M.textadept.menu.set_menubar`](_M.textadept.menu.html#set_menubar)
* [`_M.textadept.menu.set_contextmenu`](_M.textadept.menu.html#set_contextmenu)

- - -

<a id="print"></a>
### `print`(*...*)

Prints messages to the Textadept message buffer.
Opens a new buffer if one has not already been opened for printing messages.

Parameters:

* *`...`*: Message strings.

- - -

<a id="select_theme"></a>
### `select_theme`()

Prompts the user to select an editor theme from a list of themes found in the
*`_HOME`/themes/* and *`_USERHOME`/themes/* directories.

- - -

<a id="set_theme"></a>
### `set_theme`(*name*)

Sets the editor theme name to *name* or the default platform theme.
Themes with *name* in the *`_USERHOME`/themes/* directory override themes of
the same name in *`_HOME`/themes/*. If *name* contains slashes ('\' on
Windows, '/' otherwise), it is assumed to be an absolute path to a theme
instead of a theme name. An error is thrown if the theme is not found. Any
errors in the theme are printed to `io.stderr`. Running Textadept from a
terminal is the easiest way to see errors as they occur.

Parameters:

* *`name`*: Optional name or absolute path of a theme to set. If `nil`, sets
  the default platform theme.

- - -

<a id="switch_buffer"></a>
### `switch_buffer`()

Prompts the user to select a buffer to switch to.

- - -


## Tables

- - -

<a id="menubar"></a>
### `menubar`

A table of menus defining a menubar. (Write-only)

See also:

* [`_M.textadept.menu.set_menubar`](_M.textadept.menu.html#set_menubar)

- - -

<a id="size"></a>
### `size`

A table containing the width and height values of the Textadept window.

- - -

