Subsections

- 6.1 Functions defined in ioncore
  - 6.1.1 WClientWin functions
  - 6.1.2 WFrame functions
  - 6.1.3 WGroup functions
  - 6.1.4 WGroupCW functions
  - 6.1.5 WGroupWS functions
  - 6.1.6 WHook functions
  - 6.1.7 WInfoWin functions
  - 6.1.8 WMPlex functions
  - 6.1.9 WMoveresMode functions
  - 6.1.10 WRegion functions
  - 6.1.11 WRootWin functions
  - 6.1.12 WScreen functions
  - 6.1.13 WTimer functions
  - 6.1.14 WWindow functions
  - 6.1.15 global functions
  - 6.1.16 gr functions
  - 6.1.17 string functions
  - 6.1.18 table functions
- 6.2 Functions defined in mod_tiling
  - 6.2.1 WSplit functions
  - 6.2.2 WSplitInner functions
  - 6.2.3 WSplitRegion functions
  - 6.2.4 WSplitSplit functions
  - 6.2.5 WTiling functions
- 6.3 Functions defined in mod_query
  - 6.3.1 WComplProxy functions
  - 6.3.2 WEdln functions
  - 6.3.3 WInput functions
- 6.4 Functions defined in mod_menu
  - 6.4.1 WMenu functions
- 6.5 Functions defined in mod_dock
  - 6.5.1 WDock functions
- 6.6 Functions defined in mod_sp
- 6.7 Functions defined in mod_statusbar
  - 6.7.1 WStatusBar functions
- 6.8 Functions defined in de
- 6.9 Hooks
- 6.10 Miscellaneous
  - 6.10.1 Size policies

#
6. Function reference

##
6.1 Functions defined in ioncore

Synopsis:
  `ioncore.TR(s, ...)`
Description:
  gettext+string.format

Synopsis:
  `ioncore.bdoc(text)`
Description:
  Used to enter documentation among bindings so that other programs can read it. Does nothing.

Synopsis:
  `ioncore.chdir_for(reg, dir)`
Description:
  Change default working directory for new programs started in `reg`.

Synopsis:
  `ioncore.compile_cmd(cmd, guard)`
Description:
  Compile string `cmd` into a bindable function. Within `cmd`, the variable ''`_`'' (underscore) can be used to refer to the object that was selecting for the bound action and chosen to handle it. The variable ''`_sub`'' refers to a ''currently active'' sub-object of `_`, or a sub-object where the action loading to the binding being called actually occured.

  The string `guard` maybe set to pose limits on `_sub`. Currently supported guards are `_sub:non-nil` and `_sub:WFoobar`, where WFoobar is a class.

Synopsis:
  `WTimer ioncore.create_timer()`
Description:
  Create a new timer.

Synopsis:
  `ioncore.create_ws(scr, tmpl, layout)`
Description:
  Create new workspace on screen `scr`. The table `tmpl` may be used to override parts of the layout named with `layout`. If no `layout` is given, "default" is used.

Synopsis:
  `ioncore.defbindings(context, bindings)`
Description:
  Define bindings for context `context`. Here `binding` is a table composed of entries created with `ioncore.kpress`, etc.; see Section 3.3 for details.

Synopsis:
  `ioncore.defctxmenu(ctx, ...)`
Description:
  Define context menu for context `ctx`, `tab` being a table of menu entries.

Synopsis:
  `ioncore.deflayout(name, tab)`
Description:
  Define a new workspace layout with name `name`, and attach/creation parameters given in `tab`. The layout "empty" may not be defined.

Synopsis:
  `ioncore.defmenu(name, tab)`
Description:
  Define a new menu with `name` being the menu's name and `tab` being a table of menu entries. If `tab.append` is set, the entries are appended to previously-defined ones, if possible.

Synopsis:
  `ioncore.defwinprop(list)`
Description:
  Define a winprop. For more information, see section 3.5.

Synopsis:
  `ioncore.exec_on(reg, cmd, merr_internal)`
Description:
  Run `cmd` with the environment variable DISPLAY set to point to the root window of the X screen `reg` is on. If `cmd` is prefixed by a colon (`:`), the following command is executed in an xterm (or other terminal emulator) with the help of the `ion-runinxterm` script. If the command is prefixed by two colons, `ion-runinxterm` will ask you to press enter after the command is finished, even if it returns succesfully.

  For GUI commands, you might prefer to use mod_query.exec_on_merr(), which monitors the process's `stderr` and shows any output as warnings on the screen instead of in notions own output.

Synopsis:
  `table ioncore.read_savefile(string basename)`
Description:
  Read a savefile. This function is considered safe.

Synopsis:
  `string ioncore.get_savefile(string basename)`
Description:
  Get a file name to save (session) data in. The string `basename` should contain no path or extension components. This function is considered safe.

Synopsis:
  `string ioncore.lookup_script(string file, string sp)`
Description:
  Lookup script `file`. If `try_in_dir` is set, it is tried before the standard search path. This function is considered safe.

Synopsis:
  `bool ioncore.write_savefile(string basename, table tab)`
Description:
  Write `tab` in file with basename `basename` in the session directory. This function is considered safe.

Synopsis:
  `ioncore.find_manager(obj, t)`
Description:
  Find an object with type name `t` managing `obj` or one of its managers.

Synopsis:
  `ioncore.get_dir_for(reg)`
Description:
  Get default working directory for new programs started in `reg`.

Synopsis:
  `ioncore.getbindings(maybe_context)`
Description:
  Get a table of all bindings.

Synopsis:
  `ioncore.getctxmenu(name)`
Description:
  Returns a context menu defined with `ioncore.defctxmenu`.

Synopsis:
  `ioncore.getlayout(name, all)`
Description:
  Get named layout (or all of the latter parameter is set, but this is for internal use only).

Synopsis:
  `ioncore.getmenu(name)`
Description:
  Returns a menu defined with `ioncore.defmenu`.

Synopsis:
  `ioncore.getwinprop(cwin)`
Description:
  Find winprop table for `cwin`.

Synopsis:
  `string ioncore.aboutmsg()`
Description:
  Returns an about message (version, author, copyright notice). This function is considered safe.

Synopsis:
  `WRegion ioncore.activity_first()`
Description:
  Returns first region on activity list. This function is considered safe.

Synopsis:
  `bool ioncore.activity_i(function iterfn)`
Description:
  Iterate over activity list until `iterfn` returns `false`. The function is called in protected mode. This routine returns `true` if it reaches the end of list without this happening. This function is considered safe.

Synopsis:
  `bool ioncore.clientwin_i(function fn)`
Description:
  Iterate over client windows until `iterfn` returns `false`. The function is called in protected mode. This routine returns `true` if it reaches the end of list without this happening. This function is considered safe.

Synopsis:
  `WRegion ioncore.current()`
Description:
  Returns the currently focused region, if any.

Synopsis:
  `bool ioncore.defshortening(string rx, string rule, bool always)`
Description:
  Add a rule describing how too long titles should be shortened to fit in tabs. The regular expression `rx` (POSIX, not Lua!) is used to match titles and when `rx` matches, `rule` is attempted to use as a replacement for title. If `always` is set, the rule is used even if no shortening is necessary.

  Similarly to sed's 's' command, `rule` may contain characters that are inserted in the resulting string and specials as follows:

  Special
  $0
  $1 to $9
  $|
  $<
  $>

Synopsis:
  `bool ioncore.detach(WRegion reg, string how)`
Description:
  Detach or reattach `reg` or any group it is the leader of (see `WRegion.groupleader_of`), depending on whether `how` is ``set`', ``unset`' or ``toggle`'. If this region is not a window, it is put into a frame.

  Detaching a region means having it managed by its nearest ancestor WGroup. Reattaching means having it managed where it used to be managed, if a ``return placeholder'' exists.

  Additionally, setting `how` to ``forget`', can be used to clear this return placeholder of the group leader of `reg`.

Synopsis:
  `integer ioncore.exec(string cmd)`
Description:
  Run `cmd` with the environment variable DISPLAY set to point to the X display the WM is running on. No specific screen is set unlike with `WRootWin.exec_on`. The PID of the (shell executing the) new process is returned. This function is considered safe.

Synopsis:
  `WScreen ioncore.find_screen_id(integer id)`
Description:
  Find the screen with numerical id `id`. This function is considered safe.

Synopsis:
  `bool ioncore.focushistory_i(function iterfn)`
Description:
  Iterate over focus history until `iterfn` returns `false`. The function is called in protected mode. This routine returns `true` if it reaches the end of list without this happening.

Synopsis:
  `table ioncore.get()`
Description:
  Get ioncore basic settings. For details see `ioncore.set`. This function is considered safe.

Synopsis:
  `table ioncore.get_paths(table tab)`
Description:
  Get important directories (the fields `userdir`, `sessiondir`, `searchpath` in the returned table). This function is considered safe.

Synopsis:
  `bool ioncore.goto_activity()`
Description:
  Go to first region on activity list.

Synopsis:
  `WRegion ioncore.goto_first(WRegion reg, string dirstr, table param)`
Description:
  Go to first region within `reg` in direction `dirstr`. For information on `param`, see `ioncore.navi_next`. Additionally this function supports the boolean `nofront` field, for not bringing the object to front.

Synopsis:
  `WRegion ioncore.goto_next(WRegion reg, string dirstr, table param)`
Description:
  Go to region next from `reg` in direction `dirstr`. For information on `param`, see `ioncore.navi_next`. Additionally this function supports the boolean `nofront` field, for not bringing the object to front.

Synopsis:
  `WScreen ioncore.goto_next_screen()`
Description:
  Switch focus to the next screen and return it.

  Note that this function is asynchronous; the screen will not actually have received the focus when this function returns.

Synopsis:
  `WScreen ioncore.goto_nth_screen(integer id)`
Description:
  Switch focus to the screen with id `id` and return it.

  Note that this function is asynchronous; the screen will not actually have received the focus when this function returns.

Synopsis:
  `WScreen ioncore.goto_prev_screen()`
Description:
  Switch focus to the previous screen and return it.

  Note that this function is asynchronous; the screen will not actually have received the focus when this function returns.

Synopsis:
  `WRegion ioncore.goto_previous()`
Description:
  Go to and return to a previously active region (if any).

  Note that this function is asynchronous; the region will not actually have received the focus when this function returns.

Synopsis:
  `bool ioncore.is_i18n()`
Description:
  Is Notion supporting locale-specifically multibyte-encoded strings? This function is considered safe.

Synopsis:
  `bool ioncore.load_module(string modname)`
Description:
  Attempt to load a C-side module.

Synopsis:
  `WClientWin ioncore.lookup_clientwin(string name)`
Description:
  Attempt to find a client window with name `name`. This function is considered safe.

Synopsis:
  `WRegion ioncore.lookup_region(string name, string typenam)`
Description:
  Attempt to find a non-client window region with name `name` and type inheriting `typenam`. This function is considered safe.

Synopsis:
  `WRegion ioncore.navi_first(WRegion reg, string dirstr, table param)`
Description:
  Find first region within `reg` in direction `dirstr`. For information on `param`, see `ioncore.navi_next`.

Synopsis:
  `WRegion ioncore.navi_next(WRegion reg, string dirstr, table param)`
Description:
  Find region next from `reg` in direction `dirstr` (``up`', ``down`', ``left`', ``right`', ``next`', ``prev`', or ``any`'). The table `param` may contain the boolean field `nowrap`, instructing not to wrap around, and the WRegions `no_ascend` and `no_descend`, and boolean functions `ascend_filter` and `descend_filter` on `WRegion` pairs (`to`, `from`), are used to decide when to descend or ascend into another region.

Synopsis:
  `integer ioncore.popen_bgread(string cmd, function h, function errh, string wd)`
Description:
  Run `cmd` in directory `wd` with a read pipe connected to its stdout and stderr. When data is received through one of these pipes, `h` or `errh` is called with that data. When the pipe is closed, the handler is called with `nil` argument. The PID of the new process is returned, or -1 on error. This function is considered safe.

Synopsis:
  `void ioncore.profiling_start(string filename)`
Description:
  Start profiling (if enabled at compile-time) This function is considered safe.

Synopsis:
  `void ioncore.profiling_stop()`
Description:
  Stop profiling (if enabled at compile-time) This function is considered safe.

Synopsis:
  `string ioncore.progname()`
Description:
  Returns the name of program using Ioncore. This function is considered safe.

Synopsis:
  `bool ioncore.region_i(function fn, string typenam)`
Description:
  Iterate over all non-client window regions with (inherited) class `typenam` until `iterfn` returns `false`. The function is called in protected mode. This routine returns `true` if it reaches the end of list without this happening. This function is considered safe.

Synopsis:
  `void ioncore.request_selection(function fn)`
Description:
  Request (string) selection. The function `fn` will be called with the selection when and if it is received.

Synopsis:
  `void ioncore.resign()`
Description:
  Causes the window manager to simply exit without saving state/session.

Synopsis:
  `void ioncore.restart()`
Description:
  Restart, saving session first.

Synopsis:
  `void ioncore.restart_other(string cmd)`
Description:
  Attempt to restart another window manager `cmd`.

Synopsis:
  `WRootWin ioncore.rootwin()`
Description:
  Returns the first WRootWin This function is considered safe.

Synopsis:
  `void ioncore.screens_updated(WRootWin rw)`
Description:
  refresh _NET_WM_VIRTUAL_ROOTS This function is considered safe.

Synopsis:
  `void ioncore.set(table tab)`
Description:
  Set ioncore basic settings. The table `tab` may contain the following fields.

  Field
  `opaque_resize`
  `warp`
  `switchto`
  `screen_notify`
  `frame_default_index`
  `dblclick_delay`
  `kbresize_delay`
  `kbresize_t_max`
  `kbresize_t_min`
  `kbresize_step`
  `kbresize_maxacc`
  `edge_resistance`
  `framed_transients`
  `float_placement_method`
  `float_placement_padding`
  `mousefocus`
  `unsqueeze`
  `autoraise`
  `usertime_diff_current`
  `usertime_diff_new`
  `autosave_layout`
  `window_stacking_request`
  `focuslist_insert_delay`
  `activity_notification_on_all_screens`
  `workspace_indicator_timeout`

  When a keyboard resize function is called, and at most `kbresize_t_max` milliseconds has passed from a previous call, acceleration factor is reset to 1.0. Otherwise, if at least `kbresize_t_min` milliseconds have passed from the from previous acceleration update or reset the squere root of the acceleration factor is incremented by `kbresize_step`. The maximum acceleration factor (pixels/call modulo size hints) is given by `kbresize_maxacc`. The default values are (200, 50, 30, 100).

Synopsis:
  `bool ioncore.set_paths(table tab)`
Description:
  Set important directories (the fields `sessiondir`, `searchpath` of `tab`).

Synopsis:
  `void ioncore.set_selection(string p)`
Description:
  Set primary selection and cutbuffer0 to `p`.

Synopsis:
  `void ioncore.shutdown()`
Description:
  End session saving it first.

Synopsis:
  `void ioncore.snapshot()`
Description:
  Save session.

Synopsis:
  `void ioncore.tagged_clear()`
Description:
  Untag all regions.

Synopsis:
  `WRegion ioncore.tagged_first(bool untag)`
Description:
  Returns first tagged object, untagging it as well if `untag` is set. This function is considered safe.

Synopsis:
  `bool ioncore.tagged_i(function iterfn)`
Description:
  Iterate over tagged regions until `iterfn` returns `false`. The function is called in protected mode. This routine returns `true` if it reaches the end of list without this happening. This function is considered safe.

Synopsis:
  `void ioncore.unsqueeze(WRegion reg, bool override)`
Description:
  Try to detach `reg` if it fits poorly in its current location. This function does not do anything, unless `override` is set or the `unsqueeze` option of `ioncore.set` is set.

Synopsis:
  `void ioncore.update_net_state(WClientWin cwin)`
Description:
  refresh _NET_WM_STATE markers for this window This function is considered safe.

Synopsis:
  `string ioncore.version()`
Description:
  Returns Ioncore version string. This function is considered safe.

Synopsis:
  `void ioncore.warn(string str)`
Description:
  Issue a warning. How the message is displayed depends on the current warning handler. This function is considered safe.

Synopsis:
  `void ioncore.warn_traced(string str)`
Description:
  Similar to `ioncore.warn`, but also print Lua stack trace. This function is considered safe.

Synopsis:
  `void ioncore.x_change_property(integer win, integer atom, integer atom_type, integer format, string mode, table tab)`
Description:
  Modify a window property. The `mode` is one of ``replace`', ``prepend`' or ``append`', and format is either 8, 16 or 32. Also see `ioncore.x_get_window_property` and the `XChangeProperty`(3) manual page.

Synopsis:
  `void ioncore.x_delete_property(integer win, integer atom)`
Description:
  Delete a window property.

Synopsis:
  `string ioncore.x_get_atom_name(integer atom)`
Description:
  Get the name of an atom. See `XGetAtomName`(3) manual page for details.

Synopsis:
  `table ioncore.x_get_text_property(integer win, integer atom)`
Description:
  Get a text property for a window. The fields in the returned table (starting from 1) are the null-separated parts of the property. See the `XGetTextProperty`(3) manual page for more information. This function is considered safe.

Synopsis:
  `table ioncore.x_get_window_property(integer win, integer atom, integer atom_type, integer n32expected, bool more)`
Description:
  Get a property `atom` of type `atom_type` for window `win`. The `n32expected` parameter indicates the expected number of 32bit words, and `more` indicates whether all or just this amount of data should be fetched. Each 8, 16 or 32bit element of the property, as deciphered from `atom_type` is a field in the returned table. See `XGetWindowProperty`(3) manual page for more information. This function is considered safe.

Synopsis:
  `integer ioncore.x_intern_atom(string name, bool only_if_exists)`
Description:
  Create a new atom. See `XInternAtom`(3) manual page for details.

Synopsis:
  `void ioncore.x_set_text_property(integer win, integer atom, table tab)`
Description:
  Set a text property for a window. The fields of `tab` starting from 1 should be the different null-separated parts of the property. See the `XSetTextProperty`(3) manual page for more information.

Synopsis:
  `void ioncore.x_set_utf8_property(integer win, integer atom, table tab)`
Description:
  Set a `UTF8_STRING` property for a window. The fields of `tab` starting from 1 should be the different null-separated parts of the property. See the `XSetTextProperty`(3) manual page for more information.

Synopsis:
  `ioncore.kpress(keyspec, cmd, guard)`
Description:
  Creates a binding description table for the action of pressing a key given by `keyspec` (with possible modifiers) to the function `cmd`. The `guard` controls when the binding can be called. For more informationp see Section 3.3.

Synopsis:
  `ioncore.kpress_wait(keyspec, cmd, guard)`
Description:
  This is similar to `ioncore.kpress` but after calling `cmd`, Ioncore waits for all modifiers to be released before processing any further actions. For more information on bindings, see Section 3.3.

Synopsis:
  `bool ioncore.defer(function fn)`
Description:
  Defer execution of `fn` until the main loop. This function is considered safe.

Synopsis:
  `WHook ioncore.get_hook(string name)`
Description:
  Find named hook `name`. This function is considered safe.

Synopsis:
  `ioncore.match_winprop_dflt(prop, cwin, id)`
Description:
  The basic name-based winprop matching criteria.

Synopsis:
  `ioncore.mclick(buttonspec, cmd, guard)`
Description:
  Creates a binding description table for the action of clicking a mouse button while possible modifier keys are pressed, both given by `buttonspec`, to the function `cmd`. For more information, see Section 3.3.

Synopsis:
  `ioncore.mdblclick(buttonspec, cmd, guard)`
Description:
  Similar to `ioncore.mclick` but for double-click. Also see Section 3.3.

Synopsis:
  `ioncore.mdrag(buttonspec, cmd, guard)`
Description:
  Creates a binding description table for the action of moving the mouse (or other pointing device) while the button given by `buttonspec` is held pressed and the modifiers given by `buttonspec` were pressed when the button was initially pressed. Also see section 3.3.

Synopsis:
  `ioncore.menuentry(name, cmd, guard_or_opts)`
Description:
  Use this function to define normal menu entries. The string `name` is the string shown in the visual representation of menu. The parameter `cmd` and `guard_or_opts` (when string) are similar to those of `ioncore.defbindings`. If `guard_or_opts` is a table, it may contains the `guard` field, and the `priority` field, for controlling positioning of entries in context menus. (The default priority is 1 for most entries, and -1 for auto-generated submenus.)

Synopsis:
  `ioncore.mpress(buttonspec, cmd, guard)`
Description:
  Similar to `ioncore.mclick` but for just pressing the mouse button. Also see Section 3.3.

Synopsis:
  `ioncore.refresh_stylelist()`
Description:
  Refresh list of known style files.

Synopsis:
  `ioncore.submap(keyspec, list)`
Description:
  Returns a function that creates a submap binding description table. When the key press action `keyspec` occurs, Ioncore will wait for a further key presse and act according to the submap. For details, see Section 3.3.

Synopsis:
  `ioncore.submap_enter(cmd, guard)`
Description:
  Submap enter event for bindings.

Synopsis:
  `ioncore.submap_wait(cmd, guard)`
Description:
  Submap modifier release event for bindings.

Synopsis:
  `ioncore.submenu(name, sub_or_name, options)`
Description:
  Use this function to define menu entries for submenus. The parameter `sub_or_name` is either a table of menu entries or the name of an already defined menu. The initial menu entry to highlight can be specified by `options.initial` as either an integer starting from 1, or a function that returns such a number. Another option supported is `options.noautoexpand` that will cause `mod_query.query_menu` to not automatically expand this submenu.

Synopsis:
  `ioncore.tabnum.clear()`
Description:
  Clear all tab numbers set by `ioncore.tabnum.show`.

Synopsis:
  `ioncore.tabnum.show(frame, delay)`
Description:
  Show tab numbers on `frame`, clearing them when submap grab is released the next time. If `delay` is given, in milliseconds, the numbers are not actually displayed until this time has passed.

Synopsis:
  `ioncore.tagged_attach(reg, param)`
Description:
  Attach tagged regions to `reg`. The method of attach depends on the types of attached regions and whether `reg` implements `attach_framed` and `attach`. If `param` is not set, the default of `{switchto=true}` is used. The function returns `true` if all tagged regions were succesfully attached, and `false` otherwisse.

### 6.1.1 WClientWin functions

Synopsis:
  `table WClientWin.get_ident(WClientWin cwin)`
Description:
  Returns a table containing the properties `WM_CLASS` (table entries `instance` and `class`) and `WM_WINDOW_ROLE` (`role`) properties for `cwin`. If a property is not set, the corresponding field(s) are unset in the table. This function is considered safe.

Synopsis:
  `void WClientWin.kill(WClientWin cwin)`
Description:
  Attempt to kill (with `XKillWindow`) the client that owns the X window correspoding to `cwin`.

Synopsis:
  `void WClientWin.nudge(WClientWin cwin)`
Description:
  Attempts to fix window size problems with non-ICCCM compliant programs.

Synopsis:
  `void WClientWin.quote_next(WClientWin cwin)`
Description:
  Send next key press directly to `cwin`.

Synopsis:
  `double WClientWin.xid(WClientWin cwin)`
Description:
  Return the X window id for the client window. This function is considered safe.

### 6.1.2 WFrame functions

Synopsis:
  `bool WFrame.is_grattr(WFrame frame, string attr)`
Description:
  Is the attribute `attr` set on `frame`? This function is considered safe.

Synopsis:
  `bool WFrame.is_shaded(WFrame frame)`
Description:
  Is `frame` shaded? This function is considered safe.

Synopsis:
  `void WFrame.maximize_horiz(WFrame frame)`
Description:
  Attempt to toggle horizontal maximisation of `frame`.

Synopsis:
  `void WFrame.maximize_vert(WFrame frame)`
Description:
  Attempt to toggle vertical maximisation of `frame`.

Synopsis:
  `string WFrame.mode(WFrame frame)`
Description:
  Get frame mode. This function is considered safe.

Synopsis:
  `void WFrame.p_switch_tab(WFrame frame)`
Description:
  Display the region corresponding to the tab that the user pressed on. This function should only be used by binding it to a mouse action.

Synopsis:
  `void WFrame.p_tabdrag(WFrame frame)`
Description:
  Start dragging the tab that the user pressed on with the pointing device. This function should only be used by binding it to mpress or mdrag action with area ``tab`'.

Synopsis:
  `bool WFrame.set_grattr(WFrame frame, string attr, string how)`
Description:
  Set extra drawing engine attributes for the frame. The parameter `attr` is the attribute, and `how` is one of ``set`', ``unset`', or ``toggle`'.

Synopsis:
  `bool WFrame.set_mode(WFrame frame, string modestr)`
Description:
  Set frame mode (one of ``unknown`', ``tiled`', ``floating`', ``transient`', or any of these suffixed with ``-alt`').

Synopsis:
  `bool WFrame.set_shaded(WFrame frame, string how)`
Description:
  Set shading state according to the parameter `how` (``set`', ``unset`', or ``toggle`'). Resulting state is returned, which may not be what was requested.

### 6.1.3 WGroup functions

Synopsis:
  `WRegion WGroup.attach(WGroup ws, WRegion reg, table param)`
Description:
  Attach and reparent existing region `reg` to `ws`. The table `param` may contain the fields `index` and `switchto` that are interpreted as for `WMPlex.attach_new`.

Synopsis:
  `WRegion WGroup.attach_new(WGroup ws, table param)`
Description:
  Create a new region to be managed by `ws`. At least the following fields in `param` are understood:

  Field
  `type`
  `name`
  `switchto`
  `level`
  `modal`
  `sizepolicy`
  `bottom`

  In addition parameters to the region to be created are passed in this same table.

Synopsis:
  `WRegion WGroup.bottom(WGroup ws)`
Description:
  Returns the `bottom' of `ws`. This function is considered safe.

Synopsis:
  `bool WGroup.managed_i(WGroup ws, function iterfn)`
Description:
  Iterate over managed regions of `ws` until `iterfn` returns `false`. The function is called in protected mode. This routine returns `true` if it reaches the end of list without this happening. This function is considered safe.

Synopsis:
  `bool WGroup.set_bottom(WGroup ws, WRegion reg)`
Description:
  Sets the `bottom' of `ws`. The region `reg` must already be managed by `ws`, unless `nil`.

Synopsis:
  `bool WGroup.set_fullscreen(WGroup grp, string how)`
Description:
  Set client window `reg` full screen state according to the parameter `how` (one of ``set`', ``unset`', or ``toggle`'). Resulting state is returned, which may not be what was requested.

### 6.1.4 WGroupCW functions

### 6.1.5 WGroupWS functions

Synopsis:
  `bool WGroupWS.attach_framed(WGroupWS ws, WRegion reg, table t)`
Description:
  Attach region `reg` on `ws`. At least the following fields in `t` are supported:

  Field
  `switchto`
  `geom`

### 6.1.6 WHook functions

Synopsis:
  `bool WHook.add(WHook hk, function efn)`
Description:
  Add `efn` to the list of functions to be called when the hook `hk` is triggered.

Synopsis:
  `bool WHook.listed(WHook hk, function efn)`
Description:
  Is `fn` hooked to hook `hk`? This function is considered safe.

Synopsis:
  `bool WHook.remove(WHook hk, function efn)`
Description:
  Remove `efn` from the list of functions to be called when the hook `hk` is triggered.

### 6.1.7 WInfoWin functions

Synopsis:
  `void WInfoWin.set_text(WInfoWin p, string str, integer maxw)`
Description:
  Set contents of the info window.

### 6.1.8 WMPlex functions

Synopsis:
  `WRegion WMPlex.attach(WMPlex mplex, WRegion reg, table param)`
Description:
  Attach and reparent existing region `reg` to `mplex`. The table `param` may contain the fields `index` and `switchto` that are interpreted as for `WMPlex.attach_new`.

Synopsis:
  `WRegion WMPlex.attach_new(WMPlex mplex, table param)`
Description:
  Create a new region to be managed by `mplex`. At least the following fields in `param` are understood (all but `type` are optional).

  Field
  `type`
  `name`
  `switchto`
  `unnumbered`
  `index`
  `level`
  `modal`
  `hidden`
  `passive`
  `pseudomodal`
  `sizepolicy`
  `geom`

  In addition parameters to the region to be created are passed in this same table.

Synopsis:
  `void WMPlex.dec_index(WMPlex mplex, WRegion r)`
Description:
  Move `r` ``left'' within objects managed by `mplex` on list 1.

Synopsis:
  `integer WMPlex.get_index(WMPlex mplex, WRegion reg)`
Description:
  Get index of `reg` on the mutually exclusive list of `mplex`. The indices begin from zero.. If `reg` is not on the list, -1 is returned. This function is considered safe.

Synopsis:
  `table WMPlex.get_stdisp(WMPlex mplex)`
Description:
  Get status display information. See `WMPlex.get_stdisp` for information on the fields. This function is considered safe.

Synopsis:
  `void WMPlex.inc_index(WMPlex mplex, WRegion r)`
Description:
  Move `r` ``right'' within objects managed by `mplex` on list 1.

Synopsis:
  `bool WMPlex.is_hidden(WMPlex mplex, WRegion reg)`
Description:
  Is `reg` on within `mplex` and hidden? This function is considered safe.

Synopsis:
  `bool WMPlex.managed_i(WMPlex mplex, function iterfn)`
Description:
  Iterate over managed regions of `mplex` until `iterfn` returns `false`. The function is called in protected mode. This routine returns `true` if it reaches the end of list without this happening. This function is considered safe.

Synopsis:
  `integer WMPlex.mx_count(WMPlex mplex)`
Description:
  Returns the number of objects on the mutually exclusive list of `mplex`. This function is considered safe.

Synopsis:
  `WRegion WMPlex.mx_current(WMPlex mplex)`
Description:
  Returns the managed object currently active within the mutually exclusive list of `mplex`. This function is considered safe.

Synopsis:
  `bool WMPlex.mx_i(WMPlex mplex, function iterfn)`
Description:
  Iterate over numbered/mutually exclusive region list of `mplex` until `iterfn` returns `false`. The function is called in protected mode. This routine returns `true` if it reaches the end of list without this happening. This function is considered safe.

Synopsis:
  `WRegion WMPlex.mx_nth(WMPlex mplex, integer n)`
Description:
  Returns the `n`:th object on the mutually exclusive list of `mplex`. This function is considered safe.

Synopsis:
  `bool WMPlex.set_hidden(WMPlex mplex, WRegion reg, string how)`
Description:
  Set the visibility of the region `reg` on `mplex` as specified with the parameter `how` (one of ``set`', ``unset`', or ``toggle`'). The resulting state is returned.

Synopsis:
  `void WMPlex.set_index(WMPlex mplex, WRegion reg, integer index)`
Description:
  Set index of `reg` to `index` within the mutually exclusive list of `mplex`. Special values for `index` are:

  -1 mathend000#
  -2 mathend000#

Synopsis:
  `WRegion WMPlex.set_stdisp(WMPlex mplex, table t)`
Description:
  Set/create status display for `mplex`. Table is a standard description of the object to be created (as passed to e.g. `WMPlex.attach_new`). In addition, the following fields are recognised:

  Field
  `pos`
  `fullsize`
  `action`

Synopsis:
  `void WMPlex.switch_next(WMPlex mplex)`
Description:
  Have `mplex` display next (wrt. currently selected) object managed by it.

Synopsis:
  `void WMPlex.switch_nth(WMPlex mplex, integer n)`
Description:
  Have `mplex` display the `n`:th object managed by it.

Synopsis:
  `void WMPlex.switch_prev(WMPlex mplex)`
Description:
  Have `mplex` display previous (wrt. currently selected) object managed by it.

Synopsis:
  `void WMPlex.switch_to(WMPlex mplex, WRegion reg)`
Description:
  Have `mplex` display the given child window already added to the mplex

### 6.1.9 WMoveresMode functions

Synopsis:
  `void WMoveresMode.cancel(WMoveresMode mode)`
Description:
  Return from move/resize cancelling changes if opaque move/resize has not been enabled.

Synopsis:
  `void WMoveresMode.finish(WMoveresMode mode)`
Description:
  Return from move/resize mode and apply changes unless opaque move/resize is enabled.

Synopsis:
  `table WMoveresMode.geom(WMoveresMode mode)`
Description:
  Returns current geometry.

Synopsis:
  `void WMoveresMode.move(WMoveresMode mode, integer horizmul, integer vertmul)`
Description:
  Move resize mode target one step:

  `horizmul`/`vertmul` | effect
  -1 | Move left/up
  0 | No effect
  1 | Move right/down

Synopsis:
  `void WMoveresMode.resize(WMoveresMode mode, integer left, integer right, integer top, integer bottom)`
Description:
  Shrink or grow resize mode target one step in each direction. Acceptable values for the parameters `left`, `right`, `top` and `bottom` are as follows: -1: shrink along, 0: do not change, 1: grow along corresponding border.

Synopsis:
  `table WMoveresMode.rqgeom(WMoveresMode mode, table g)`
Description:
  Request exact geometry in move/resize mode. For details on parameters, see `WRegion.rqgeom`.

### 6.1.10 WRegion functions

Synopsis:
  `WMoveresMode WRegion.begin_kbresize(WRegion reg)`
Description:
  Enter move/resize mode for `reg`. The bindings set with `ioncore.set_bindings` for WMoveresMode are used in this mode. Of the functions exported by the Ion C core, only `WMoveresMode.resize`, `WMoveresMode.move`, `WMoveresMode.cancel` and `WMoveresMode.end` are allowed to be called while in this mode.

Synopsis:
  `WRegion WRegion.current(WRegion mgr)`
Description:
  Return the object, if any, that is considered ``currently active'' within the objects managed by `mplex`. This function is considered safe.

Synopsis:
  `table WRegion.geom(WRegion reg)`
Description:
  Returns the geometry of `reg` within its parent; a table with fields `x`, `y`, `w` and `h`. This function is considered safe.

Synopsis:
  `table WRegion.get_configuration(WRegion reg, bool clientwins)`
Description:
  Get configuration tree. If `clientwins` is unset, client windows are filtered out.

Synopsis:
  `bool WRegion.goto(WRegion reg)`
Description:
  Deprecated in favour of `WRegion.goto_focus` because 'goto' is a keyword since Lua 5.2.

Synopsis:
  `bool WRegion.goto_focus(WRegion reg)`
Description:
  Attempt to display `reg`, save region activity status and then warp to (or simply set focus to if warping is disabled) `reg`.

  Note that this function is asynchronous; the region will not actually have received the focus when this function returns.

Synopsis:
  `WRegion WRegion.groupleader_of(WRegion reg)`
Description:
  Returns the group of `reg`, if `reg` is its bottom, and `reg` itself otherwise.

Synopsis:
  `bool WRegion.is_active(WRegion reg, bool pseudoact_ok)`
Description:
  Is `reg` active/does it or one of it's children of focus? This function is considered safe.

Synopsis:
  `bool WRegion.is_activity(WRegion reg)`
Description:
  Is activity notification set on `reg`. This function is considered safe.

Synopsis:
  `bool WRegion.is_mapped(WRegion reg)`
Description:
  Is `reg` visible/is it and all it's ancestors mapped? This function is considered safe.

Synopsis:
  `bool WRegion.is_tagged(WRegion reg)`
Description:
  Is `reg` tagged? This function is considered safe.

Synopsis:
  `WRegion WRegion.manager(WRegion reg)`
Description:
  Returns the region that manages `reg`. This function is considered safe.

Synopsis:
  `string WRegion.name(WRegion reg)`
Description:
  Returns the name for `reg`. This function is considered safe.

Synopsis:
  `WWindow WRegion.parent(WRegion reg)`
Description:
  Returns the parent region of `reg`. This function is considered safe.

Synopsis:
  `WRootWin WRegion.rootwin_of(WRegion reg)`
Description:
  Returns the root window `reg` is on. This function is considered safe.

Synopsis:
  `void WRegion.rqclose(WRegion reg, bool relocate)`
Description:
  Attempt to close/destroy `reg`. Whether this operation works depends on whether the particular type of region in question has implemented the feature and, in case of client windows, whether the client supports the `WM_DELETE` protocol (see also `WClientWin.kill`). The region will not be destroyed when this function returns. To find out if and when it is destroyed, use the ``deinit`' notification. If `relocate` is not set, and `reg` manages other regions, it will not be closed. Otherwise the managed regions will be attempted to be relocated.

Synopsis:
  `WRegion WRegion.rqclose_propagate(WRegion reg, WRegion maybe_sub)`
Description:
  Recursively attempt to close a region or one of the regions managed by it. If `sub` is set, it will be used as the managed region, otherwise `WRegion.current``(reg)`. The object to be closed is returned, or NULL if nothing can be closed. For further details, see notes for `WRegion.rqclose`.

Synopsis:
  `table WRegion.rqgeom(WRegion reg, table g)`
Description:
  Attempt to resize and/or move `reg`. The table `g` is a usual geometry specification (fields `x`, `y`, `w` and `h`), but may contain missing fields, in which case, `reg`'s manager may attempt to leave that attribute unchanged.

Synopsis:
  `bool WRegion.rqorder(WRegion reg, string ord)`
Description:
  Request ordering. Currently supported values for `ord` are ``front`' and ``back`'.

Synopsis:
  `WScreen WRegion.screen_of(WRegion reg)`
Description:
  Returns the screen `reg` is on. This function is considered safe.

Synopsis:
  `bool WRegion.set_activity(WRegion reg, string how)`
Description:
  Set activity flag of `reg`. The `how` parameter must be one of ``set`', ``unset`' or ``toggle`'.

Synopsis:
  `bool WRegion.set_name(WRegion reg, string p)`
Description:
  Set the name of `reg` to `p`. If the name is already in use, an instance number suffix ``<n>`' will be attempted. If `p` has such a suffix, it will be modified, otherwise such a suffix will be added. Setting `p` to nil will cause current name to be removed.

Synopsis:
  `bool WRegion.set_name_exact(WRegion reg, string p)`
Description:
  Similar to `WRegion.set_name` except if the name is already in use, other instance numbers will not be attempted. The string `p` should not contain a ``<n>`' suffix or this function will fail.

Synopsis:
  `bool WRegion.set_tagged(WRegion reg, string how)`
Description:
  Change tagging state of `reg` as defined by `how` (one of ``set`', ``unset`', or ``toggle`'). The resulting state is returned.

Synopsis:
  `table WRegion.size_hints(WRegion reg)`
Description:
  Returns size hints for `reg`. The returned table always contains the fields `min_?`, `base_?` and sometimes the fields `max_?`, `base_?` and `inc_?`, where `?`=`w`, `h`. This function is considered safe.

### 6.1.11 WRootWin functions

Synopsis:
  `WScreen WRootWin.current_scr(WRootWin rootwin)`
Description:
  Returns previously active screen on root window `rootwin`. This function is considered safe.

Synopsis:
  `void WRootWin.warp_pointer(WRootWin root, integer x, integer y)`
Description:
  Warp the cursor pointer to this location

  I'm not *entirely* sure what 'safe' means, but this doesn't change internal notion state, so I guess it's 'safe'... This function is considered safe.

### 6.1.12 WScreen functions

Synopsis:
  `integer WScreen.id(WScreen scr)`
Description:
  Return the numerical id for screen `scr`. This function is considered safe.

Synopsis:
  `bool WScreen.set_managed_offset(WScreen scr, table offset)`
Description:
  Set offset of objects managed by the screen from actual screen geometry. The table `offset` should contain the entries `x`, `y`, `w` and `h` indicating offsets of that component of screen geometry.

### 6.1.13 WTimer functions

Synopsis:
  `bool WTimer.is_set(WTimer timer)`
Description:
  Is timer set?

Synopsis:
  `void WTimer.reset(WTimer timer)`
Description:
  Reset timer.

Synopsis:
  `void WTimer.set(WTimer timer, integer msecs, function fn)`
Description:
  Set `timer` to call `fn` in `msecs` milliseconds.

### 6.1.14 WWindow functions

Synopsis:
  `void WWindow.p_move(WWindow wwin)`
Description:
  Start moving `wwin` with the mouse or other pointing device. This function should only be used by binding it to mpress or mdrag action.

Synopsis:
  `void WWindow.p_resize(WWindow wwin)`
Description:
  Start resizing `wwin` with the mouse or other pointing device. This function should only be used by binding it to mpress or mdrag action.

Synopsis:
  `double WWindow.xid(WWindow wwin)`
Description:
  Return the X window id for `wwin`. This function is considered safe.

### 6.1.15 global functions

Synopsis:
  `export(lib, ...)`
Description:
  Export a list of functions from `lib` into global namespace.

### 6.1.16 gr functions

Synopsis:
  `void gr.read_config()`
Description:
  Read drawing engine configuration file look.lua.

Synopsis:
  `void gr.refresh()`
Description:
  Refresh objects' brushes to update them to use newly loaded style.

Synopsis:
  `bool gr.select_engine(string engine)`
Description:
  Future requests for ``brushes'' are to be forwarded to the drawing engine `engine`. If no engine of such name is known, a module with that name is attempted to be loaded. This function is only intended to be called from colour scheme etc. configuration files and can not be used to change the look of existing objects; for that use `gr.read_config`.

### 6.1.17 string functions

Synopsis:
  `string.shell_safe(str)`
Description:
  Make `str` shell-safe.

### 6.1.18 table functions

Synopsis:
  `table.append(t1, t2)`
Description:
  Add entries that do not exist in `t1` from `t2` to `t1`.

Synopsis:
  `table.copy(t, deep)`
Description:
  Make copy of `table`. If `deep` is unset, shallow one-level copy is made, otherwise a deep copy is made.

Synopsis:
  `table.icat(t1, t2)`
Description:
  Insert all positive integer entries from t2 into t1.

Synopsis:
  `table.join(t1, t2)`
Description:
  Create a table containing all entries from `t1` and those from `t2` that are missing from `t1`.

Synopsis:
  `table.map(f, t)`
Description:
  Map all entries of `t` by `f`.

##
6.2 Functions defined in mod_tiling

Synopsis:
  `table mod_tiling.get()`
Description:
  Get parameters. For details see `mod_tiling.set`. This function is considered safe.

Synopsis:
  `bool mod_tiling.mkbottom(WRegion reg)`
Description:
  Create a new WTiling 'bottom' for the group of `reg`, consisting of `reg`.

Synopsis:
  `void mod_tiling.set(table tab)`
Description:
  Set parameters. Currently only `raise_delay` (in milliseconds) is supported.

Synopsis:
  `bool mod_tiling.untile(WTiling tiling)`
Description:
  If `tiling` is managed by some group, float the frames in the tiling in that group, and dispose of `tiling`.

### 6.2.1 WSplit functions

Synopsis:
  `table WSplit.geom(WSplit split)`
Description:
  Returns the area of workspace used by the regions under `split`. This function is considered safe.

Synopsis:
  `WSplitInner WSplit.parent(WSplit split)`
Description:
  Return parent split for `split`. This function is considered safe.

Synopsis:
  `table WSplit.rqgeom(WSplit node, table g)`
Description:
  Attempt to resize and/or move the split tree starting at `node`. Behaviour and the `g` parameter are as for `WRegion.rqgeom` operating on `node` (if it were a WRegion).

Synopsis:
  `void WSplit.transpose(WSplit node)`
Description:
  Transpose contents of `node`.

### 6.2.2 WSplitInner functions

Synopsis:
  `WSplit WSplitInner.current(WSplitInner node)`
Description:
  Returns the most previously active child node of `split`. This function is considered safe.

### 6.2.3 WSplitRegion functions

Synopsis:
  `WRegion WSplitRegion.reg(WSplitRegion node)`
Description:
  Returns the region contained in `node`. This function is considered safe.

### 6.2.4 WSplitSplit functions

Synopsis:
  `WSplit WSplitSplit.br(WSplitSplit split)`
Description:
  Returns the bottom or right child node of `split` depending on the direction of the split. This function is considered safe.

Synopsis:
  `string WSplitSplit.dir(WSplitSplit split)`
Description:
  Returns the direction of `split`; either ``vertical`' or ``horizontal`'. This function is considered safe.

Synopsis:
  `void WSplitSplit.flip(WSplitSplit split)`
Description:
  Flip contents of `split`.

Synopsis:
  `WSplit WSplitSplit.tl(WSplitSplit split)`
Description:
  Returns the top or left child node of `split` depending on the direction of the split. This function is considered safe.

### 6.2.5 WTiling functions

Synopsis:
  `bool WTiling.flip_at(WTiling ws, WRegion reg)`
Description:
  Flip `ws` at `reg` or root if nil.

Synopsis:
  `bool WTiling.transpose_at(WTiling ws, WRegion reg)`
Description:
  Transpose `ws` at `reg` or root if nil.

Synopsis:
  `WRegion WTiling.farthest(WTiling ws, string dirstr, bool any)`
Description:
  Return the most previously active region on `ws` with no other regions next to it in direction `dirstr` (``left`', ``right`', ``up`', or ``down`'). If `any` is not set, the status display is not considered. This function is considered safe.

Synopsis:
  `bool WTiling.managed_i(WTiling ws, function iterfn)`
Description:
  Iterate over managed regions of `ws` until `iterfn` returns `false`. The function is called in protected mode. This routine returns `true` if it reaches the end of list without this happening. This function is considered safe.

Synopsis:
  `WRegion WTiling.nextto(WTiling ws, WRegion reg, string dirstr, bool any)`
Description:
  Return the most previously active region next to `reg` in direction `dirstr` (``left`', ``right`', ``up`', or ``down`'). The region `reg` must be managed by `ws`. If `any` is not set, the status display is not considered. This function is considered safe.

Synopsis:
  `WSplitRegion WTiling.node_of(WTiling ws, WRegion reg)`
Description:
  For region `reg` managed by `ws` return the WSplit a leaf of which `reg` is. This function is considered safe.

Synopsis:
  `bool WTiling.set_floating_at(WTiling ws, WRegion reg, string how, string dirstr)`
Description:
  Toggle floating of the sides of a split containin `reg` as indicated by the parameters `how` (``set`', ``unset`', or ``toggle`') and `dirstr` (``left`', ``right`', ``up`', or ``down`'). The new status is returned (and `false` also on error).

Synopsis:
  `WSplitSplit WTiling.set_floating(WTiling ws, WSplitSplit split, string how)`
Description:
  Toggle floating of a split's sides at `split` as indicated by the parameter `how` (``set`', ``unset`', or ``toggle`'). A split of the appropriate is returned, if there was a change.

Synopsis:
  `WFrame WTiling.split(WTiling ws, WSplit node, string dirstr)`
Description:
  Create a new frame on `ws` ``above`', ``below`' ``left`' of, or ``right`' of `node` as indicated by `dirstr`. If `dirstr` is prefixed with ``floating:`' a floating split is created.

Synopsis:
  `WFrame WTiling.split_at(WTiling ws, WFrame frame, string dirstr, bool attach_current)`
Description:
  Split `frame` creating a new frame to direction `dirstr` (one of ``left`', ``right`', ``top`' or ``bottom`') of `frame`. If `attach_current` is set, the region currently displayed in `frame`, if any, is moved to thenew frame. If `dirstr` is prefixed with ``floating:`', a floating split is created.

Synopsis:
  `WFrame WTiling.split_top(WTiling ws, string dirstr)`
Description:
  Same as `WTiling.split` at the root of the split tree.

Synopsis:
  `WSplit WTiling.split_tree(WTiling ws)`
Description:
  Returns the root of the split tree. This function is considered safe.

Synopsis:
  `void WTiling.unsplit_at(WTiling ws, WRegion reg)`
Description:
  Try to relocate regions managed by `reg` to another frame and, if possible, destroy it.

##
6.3 Functions defined in mod_query

Synopsis:
  `mod_query.defcmd(cmd, fn)`
Description:
  Define a command override for the `query_exec` query.

Synopsis:
  `mod_query.message(mplex, str)`
Description:
  Display a message in `mplex`.

Synopsis:
  `table mod_query.get()`
Description:
  Get module configuration. For more information see `mod_query.set`. This function is considered safe.

Synopsis:
  `void mod_query.history_clear()`
Description:
  Clear line editor history.

Synopsis:
  `string mod_query.history_get(integer n)`
Description:
  Get entry at index `n` in line editor history, 0 being the latest. This function is considered safe.

Synopsis:
  `bool mod_query.history_push(string str)`
Description:
  Push an entry into line editor history.

Synopsis:
  `integer mod_query.history_search(string s, integer from, bool bwd, bool exact)`
Description:
  Try to find matching history entry. Returns -1 if none was found. The parameter `from` specifies where to start searching from, and `bwd` causes backward search from that point. If `exact` is not set, `s` only required to be a prefix of the match. This function is considered safe.

Synopsis:
  `table mod_query.history_table()`
Description:
  Return table of history entries. This function is considered safe.

Synopsis:
  `void mod_query.set(table tab)`
Description:
  Set module configuration. The following are supported:

  Field
  `autoshowcompl`
  `autoshowcompl_delay`
  `caseicompl`
  `substrcompl`

Synopsis:
  `mod_query.popen_completions(cp, cmd, fn, reshnd, wd)`
Description:
  This function can be used to read completions from an external source. The parameter `cp` is the completion proxy to be used, and the string `cmd` the shell command to be executed, in the directory `wd`. To its stdout, the command should on the first line write the `common_beg` parameter of `WComplProxy.set_completions` (which `fn` maybe used to override) and a single actual completion on each of the successive lines. The function `reshnd` may be used to override a result table building routine. Its first argument is the completion table to be passed to `WComplProxy.set_completions`, and the second a new line of output from the command.

Synopsis:
  `mod_query.query(mplex, prompt, initvalue, handler, completor, context)`
Description:
  Low-level query routine. `mplex` is the WMPlex to display the query in, `prompt` the prompt string, and `initvalue` the initial contents of the query box. `handler` is a function that receives (`mplex`, result string) as parameter when the query has been succesfully completed, `completor` the completor routine which receives a (`cp`, `str`, `point`) as parameters. The parameter `str` is the string to be completed and `point` cursor's location within it. Completions should be eventually, possibly asynchronously, set with `WComplProxy.set_completions` on `cp`.

Synopsis:
  `mod_query.query_attachclient(mplex)`
Description:
  This query asks for the name of a client window and attaches it to the frame the query was opened in. It uses the completion function `ioncore.complete_clientwin`.

Synopsis:
  `mod_query.query_editfile(mplex, script, prompt)`
Description:
  Asks for a file to be edited. This script uses `run-mailcap -mode=edit` by default, but you may provide an alternative script to use. The default prompt is "Edit file:" (translated).

Synopsis:
  `mod_query.query_exec(mplex)`
Description:
  This function asks for a command to execute with /bin/sh. If the command is prefixed with a colon (':'), the command will be run in an XTerm (or other terminal emulator) using the script ion-runinxterm. Two colons ('::') will ask you to press enter after the command has finished.

Synopsis:
  `mod_query.query_gotoclient(mplex)`
Description:
  This query asks for the name of a client window and switches focus to the one entered. It uses the completion function `ioncore.complete_clientwin`.

Synopsis:
  `mod_query.query_lua(mplex)`
Description:
  This query asks for Lua code to execute. It sets the variable '`_`' in the local environment of the string to point to the mplex where the query was created. It also sets the table `arg` in the local environment to `{_, _:current()}`.

Synopsis:
  `mod_query.query_man(mplex, prog)`
Description:
  This query asks for a manual page to display. By default it runs the `man` command in an `xterm` using `ion-runinxterm`, but it is possible to pass another program as the `prog` argument.

Synopsis:
  `mod_query.query_menu(mplex, sub, themenu, prompt)`
Description:
  This query can be used to create a query of a defined menu.

Synopsis:
  `mod_query.query_renameframe(frame)`
Description:
  This function asks for a name new for the frame where the query was created.

Synopsis:
  `mod_query.query_renameworkspace(mplex, ws)`
Description:
  This function asks for a name new for the workspace `ws`, or the one on which `mplex` resides, if it is not set. If `mplex` is not set, one is looked for.

Synopsis:
  `mod_query.query_restart(mplex)`
Description:
  This query asks whether the user wants restart Ioncore. If the answer is 'y', 'Y' or 'yes', so will happen.

Synopsis:
  `mod_query.query_runfile(mplex, script, prompt)`
Description:
  Asks for a file to be viewed. This script uses `run-mailcap -action=view` by default, but you may provide an alternative script to use. The default prompt is "View file:" (translated).

Synopsis:
  `mod_query.query_shutdown(mplex)`
Description:
  This query asks whether the user wants to exit Ion (no session manager) or close the session (running under a session manager that supports such requests). If the answer is 'y', 'Y' or 'yes', so will happen.

Synopsis:
  `mod_query.query_ssh(mplex, ssh)`
Description:
  This query asks for a host to connect to with SSH. Hosts to tab-complete are read from ~/.ssh/known_hosts.

Synopsis:
  `mod_query.query_workspace(mplex)`
Description:
  This query asks for the name of a workspace. If a workspace (an object inheriting WGroupWS) with such a name exists, it will be switched to. Otherwise a new workspace with the entered name will be created and the user will be queried for the type of the workspace.

Synopsis:
  `mod_query.query_yesno(mplex, prompt, handler)`
Description:
  This function query will display a query with prompt `prompt` in `mplex` and if the user answers affirmately, call `handler` with `mplex` as parameter.

Synopsis:
  `mod_query.show_about_ion(mplex)`
Description:
  Display an "About Ion" message in `mplex`.

Synopsis:
  `mod_query.show_tree(mplex, reg, max_depth)`
Description:
  Show information about a region tree

Synopsis:
  `mod_query.warn(mplex, str)`
Description:
  Display an error message box in the multiplexer `mplex`.

### 6.3.1 WComplProxy functions

Synopsis:
  `bool WComplProxy.set_completions(WComplProxy proxy, table compls)`
Description:
  Set completion list of the WEdln that `proxy` refers to to `compls`, if it is still waiting for this completion run. The numerical indexes of `compls` list the found completions. If the entry `common_beg` (`common_end`) exists, it gives an extra common prefix (suffix) of all found completions.

### 6.3.2 WEdln functions

Synopsis:
  `void WEdln.back(WEdln wedln)`
Description:
  Move backward one character.

Synopsis:
  `void WEdln.backspace(WEdln wedln)`
Description:
  Delete previous character.

Synopsis:
  `void WEdln.bkill_word(WEdln wedln)`
Description:
  Starting from the previous characters, delete possible whitespace and preceding alphanumeric characters until previous non-alphanumeric character.

Synopsis:
  `void WEdln.bol(WEdln wedln)`
Description:
  Go to the beginning of line.

Synopsis:
  `void WEdln.bskip_word(WEdln wedln)`
Description:
  Go to to beginning of current sequence of alphanumeric characters followed by whitespace.

Synopsis:
  `void WEdln.clear_mark(WEdln wedln)`
Description:
  Clear mark.

Synopsis:
  `void WEdln.complete(WEdln wedln, string cycle, string mode)`
Description:
  Call completion handler with the text between the beginning of line and current cursor position, or select next/previous completion from list if in auto-show-completions mode and `cycle` is set to ``next`' or ``prev`', respectively. The `mode` may be ``history`' or ``normal`'. If it is not set, the previous mode is used. Normally next entry is not cycled to despite the setting of `cycle` if mode switch occurs. To override this, use ``next-always`' and ``prev-always`' for `cycle`.

Synopsis:
  `string WEdln.contents(WEdln wedln)`
Description:
  Get line editor contents. This function is considered safe.

Synopsis:
  `string WEdln.context(WEdln wedln)`
Description:
  Get history context for `wedln`. This function is considered safe.

Synopsis:
  `void WEdln.copy(WEdln wedln)`
Description:
  Copy text between mark and current cursor position to clipboard.

Synopsis:
  `void WEdln.cut(WEdln wedln)`
Description:
  Copy text between mark and current cursor position to clipboard and then delete that sequence.

Synopsis:
  `void WEdln.delete(WEdln wedln)`
Description:
  Delete current character.

Synopsis:
  `void WEdln.eol(WEdln wedln)`
Description:
  Go to the end of line.

Synopsis:
  `void WEdln.finish(WEdln wedln)`
Description:
  Close `wedln` and call any handlers.

Synopsis:
  `void WEdln.forward(WEdln wedln)`
Description:
  Move forward one character.

Synopsis:
  `void WEdln.history_next(WEdln wedln, bool match)`
Description:
  Replace line editor contents with next entry in history if one exists. If `match` is `true`, the initial part of the history entry must match the current line from beginning to point.

Synopsis:
  `void WEdln.history_prev(WEdln wedln, bool match)`
Description:
  Replace line editor contents with previous in history if one exists. If `match` is `true`, the initial part of the history entry must match the current line from beginning to point.

Synopsis:
  `void WEdln.insstr(WEdln wedln, string str)`
Description:
  Input `str` in wedln at current editing point.

Synopsis:
  `bool WEdln.is_histcompl(WEdln wedln)`
Description:
  Get history completion mode.

Synopsis:
  `void WEdln.kill_line(WEdln wedln)`
Description:
  Delete the whole line.

Synopsis:
  `void WEdln.kill_to_bol(WEdln wedln)`
Description:
  Delete all characters from previous to beginning of line.

Synopsis:
  `void WEdln.kill_to_eol(WEdln wedln)`
Description:
  Delete all characters from current to end of line.

Synopsis:
  `void WEdln.kill_word(WEdln wedln)`
Description:
  Starting from the current point, delete possible whitespace and following alphanumeric characters until next non-alphanumeric character.

Synopsis:
  `integer WEdln.mark(WEdln wedln)`
Description:
  Get current mark (start of selection) for `wedln`. Return value of -1 indicates that there is no mark, and 0 is the beginning of the line. This function is considered safe.

Synopsis:
  `bool WEdln.next_completion(WEdln wedln)`
Description:
  Select next completion.

Synopsis:
  `void WEdln.paste(WEdln wedln)`
Description:
  Request selection from application holding such.

  Note that this function is asynchronous; the selection will not actually be inserted before Ion receives it. This will be no earlier than Ion return to its main loop.

Synopsis:
  `integer WEdln.point(WEdln wedln)`
Description:
  Get current editing point. Beginning of the edited line is point 0. This function is considered safe.

Synopsis:
  `bool WEdln.prev_completion(WEdln wedln)`
Description:
  Select previous completion.

Synopsis:
  `void WEdln.set_context(WEdln wedln, string context)`
Description:
  Set history context for `wedln`.

Synopsis:
  `void WEdln.set_mark(WEdln wedln)`
Description:
  Set mark to current cursor position.

Synopsis:
  `void WEdln.skip_word(WEdln wedln)`
Description:
  Go to to end of current sequence of whitespace followed by alphanumeric characters..

Synopsis:
  `void WEdln.transpose_chars(WEdln wedln)`
Description:
  Transpose characters.

Synopsis:
  `void WEdln.transpose_words(WEdln wedln)`
Description:
  Transpose words.

### 6.3.3 WInput functions

Synopsis:
  `void WInput.cancel(WInput input)`
Description:
  Close input not calling any possible finish handlers.

Synopsis:
  `void WInput.scrolldown(WInput input)`
Description:
  Scroll input `input` text contents down.

Synopsis:
  `void WInput.scrollup(WInput input)`
Description:
  Scroll input `input` text contents up.

##
6.4 Functions defined in mod_menu

Synopsis:
  `mod_menu.grabmenu(mplex, sub, menu_or_name, param)`
Description:
  This function is similar to `mod_menu.menu`, but input is grabbed and the key used to active the menu can be used to cycle through menu entries.

Synopsis:
  `mod_menu.menu(mplex, sub, menu_or_name, param)`
Description:
  Display a menu in the lower-left corner of `mplex`. The variable `menu_or_name` is either the name of a menu defined with `mod_menu.defmenu` or directly a table similar to ones passesd to this function. When this function is called from a binding handler, `sub` should be set to the second argument of to the binding handler (`_sub`) so that the menu handler will get the same parameters as the binding handler. Extra options can be passed in the table `param`. The initial entry can be specified as the field `initial` as an integer starting from 1. Menus can be made to use a bigger style by setting the field `big` to `true`.

Synopsis:
  `table mod_menu.get()`
Description:
  Get module basic settings. For details, see `mod_menu.set`. This function is considered safe.

Synopsis:
  `void mod_menu.set(table tab)`
Description:
  Set module basic settings. The parameter table may contain the following fields:

  Field
  `scroll_amount`
  `scroll_delay`

Synopsis:
  `mod_menu.pmenu(win, sub, menu_or_name)`
Description:
  This function displays a drop-down menu and should only be called from a mouse press handler. The parameters are similar to those of `mod_menu.menu`.

### 6.4.1 WMenu functions

Synopsis:
  `void WMenu.cancel(WMenu menu)`
Description:
  Close `menu` not calling any possible finish handlers.

Synopsis:
  `void WMenu.finish(WMenu menu)`
Description:
  If selected entry is a submenu, display that. Otherwise destroy the menu and call handler for selected entry.

Synopsis:
  `void WMenu.select_next(WMenu menu)`
Description:
  Select next entry in menu.

Synopsis:
  `void WMenu.select_nth(WMenu menu, integer n)`
Description:
  Select `n`:th entry in menu.

Synopsis:
  `void WMenu.select_prev(WMenu menu)`
Description:
  Select previous entry in menu.

Synopsis:
  `void WMenu.typeahead_clear(WMenu menu)`
Description:
  Clear typeahead buffer.

##
6.5 Functions defined in mod_dock

Synopsis:
  `void mod_dock.set_floating_shown_on(WMPlex mplex, string how)`
Description:
  Toggle floating docks on `mplex`.

### 6.5.1 WDock functions

Synopsis:
  `bool WDock.attach(WDock dock, WRegion reg)`
Description:
  Attach `reg` to `dock`.

Synopsis:
  `table WDock.get(WDock dock)`
Description:
  Get `dock`'s configuration table. See `WDock.set` for a description of the table. This function is considered safe.

Synopsis:
  `void WDock.resize(WDock dock)`
Description:
  Resizes and refreshes `dock`.

Synopsis:
  `void WDock.set(WDock dock, table conftab)`
Description:
  Configure `dock`. `conftab` is a table of key/value pairs:

  Key | Values
  `name` | string
  `pos` | string in {t, m, b}×{t, c, b} mathend000#
  `grow` | up/down/left/right
  `is_auto` | bool

  Any parameters not explicitly set in `conftab` will be left unchanged.

##
6.6 Functions defined in mod_sp

Synopsis:
  `bool mod_sp.create_scratchpad(WScreen scr)`
Description:
  Attempt to create a scratchpad on `scr`.

Synopsis:
  `bool mod_sp.is_scratchpad(WRegion reg)`
Description:
  Is `reg` a scratchpad? This function is considered safe.

Synopsis:
  `bool mod_sp.set_shown(WFrame sp, string how)`
Description:
  Toggle displayed status of `sp`. The parameter `how` is one of ``set`', ``unset`', or ``toggle`'. The resulting status is returned.

Synopsis:
  `bool mod_sp.set_shown_on(WMPlex mplex, string how)`
Description:
  Change displayed status of some scratchpad on `mplex` if one is found. The parameter `how` is one of ``set`', ``unset`', or ``toggle`'. The resulting status is returned.

##
6.7 Functions defined in mod_statusbar

Synopsis:
  `mod_statusbar.create(param)`
Description:
  Create a statusbar. The possible parameters in the table `param` are:

  Variable | Type
  `template` | string
  `pos` | string
  `screen` | integer
  `fullsize` | boolean
  `systray` | boolaen

Synopsis:
  `mod_statusbar.inform(name, value)`
Description:
  Inform of a value.

Synopsis:
  `mod_statusbar.launch_statusd(cfg)`
Description:
  Load modules and launch ion-statusd with configuration table `cfg`. The options for each ion-statusd monitor script should be contained in the corresponding sub-table of `cfg`.

Synopsis:
  `table mod_statusbar.statusbars()`
Description:
  Returns a list of all statusbars.

Synopsis:
  `mod_statusbar.terminate_statusd()`
Description:
  Function to terminate ion-statusd on exit or reload. Should be called from hook `deinit`.

Synopsis:
  `mod_statusbar.update(update_templates)`
Description:
  Update statusbar contents. To be called after series of `mod_statusbar.inform` calls.

### 6.7.1 WStatusBar functions

Synopsis:
  `table WStatusBar.get_template_table(WStatusBar sb)`
Description:
  Get statusbar template as table.

Synopsis:
  `bool WStatusBar.is_systray(WStatusBar sb)`
Description:
  Is `sb` used as a systray?

Synopsis:
  `bool WStatusBar.set_systray(WStatusBar sb, string how)`
Description:
  Enable or disable use of `sb` as systray. The parameter `how` can be one of ``set`', ``unset`', or ``toggle`'. Resulting state is returned.

Synopsis:
  `void WStatusBar.set_template(WStatusBar sb, string tmpl)`
Description:
  Set statusbar template.

Synopsis:
  `void WStatusBar.set_template_table(WStatusBar sb, table t)`
Description:
  Set statusbar template as table.

Synopsis:
  `void WStatusBar.update(WStatusBar sb, table t)`
Description:
  Set statusbar template.

##
6.8 Functions defined in de

Synopsis:
  `bool de.defstyle(string name, table tab)`
Description:
  Define a style.

Synopsis:
  `bool de.defstyle_rootwin(WRootWin rootwin, string name, table tab)`
Description:
  Define a style for the root window `rootwin`.

Synopsis:
  `void de.reset()`
Description:
  Clear all styles from drawing engine memory.

Synopsis:
  `table de.substyle(string pattern, table tab)`
Description:
  Define a substyle. This function is considered safe.

##
6.9 Hooks

Hook name:
  `clientwin_do_manage_alt`
Parameters:
  `(WClientWin, table)`
Description:
  Called when we want to manage a new client window. The table argument contains the following fields:

  Field | Type
  `switchto` | bool
  `jumpto` | bool
  `userpos` | bool
  `dockapp` | bool
  `maprq` | bool
  `gravity` | number
  `geom` | table
  `tfor` | WClientWin

  This hook is not called in protected mode and can be used for arbitrary placement policies (deciding in which workspace a new WClientWin should go). In this case, you can call

      reg:attach(cwin)

  where `reg` is the region where the window should go, and `cwin` is the first argument of the function added to the hook.

Hook name:
  `clientwin_mapped_hook`
Parameters:
  `WClientWin`
Description:
  Called when we have started to manage a client window.

Hook name:
  `clientwin_property_change_hook`
Parameters:
  `(WClientWin, integer)`
Description:
  Called when the property identified by the parameter atom id (integer) has changed on a client window.

Hook name:
  `clientwin_unmapped_hook`
Parameters:
  `number`
Description:
  Called when we no longer manage a client window. The parameter is the X ID of the window; see `WClientWin.xid`.

Hook name:
  `frame_managed_changed_hook`
Parameters:
  `table`
Description:
  Called when there are changes in the objects managed by a frame or their order. The table parameter has the following fields:

  Field | Type
  `reg` | WFrame
  `mode` | string
  `sw` | bool
  `sub` | WRegion

Hook name:
  `ioncore_sigchld_hook`
Parameters:
  `integer`
Description:
  Called when a child process has exited. The parameter is the PID of the process.

Hook name:
  `ioncore_deinit_hook`
Parameters:
  `()`
Description:
  Called when Notion is deinitialising and about to quit.

Hook name:
  `ioncore_post_layout_setup_hook`
Parameters:
  `()`
Description:
  Called when Notion has done all initialisation and is almost ready to enter the main-loop, except no windows are yet being managed.

Hook name:
  `ioncore_snapshot_hook`
Parameters:
  `()`
Description:
  Called to signal scripts and modules to save their state (if any).

Hook name:
  `ioncore_submap_ungrab_hook`
Parameters:
  `()`
Description:
  This hook is used to signal whenever Notion leaves the submap grab mode.

Hook name:
  `tiling_placement_alt`
Parameters:
  `table`
Description:
  Called when a client window is about to be managed by a WTiling to allow for alternative placement policies. The table has the following fields:

  Field | Type
  `tiling` | WTiling
  `reg` | WRegion
  `mp` | table
  `res_frame` | WFrame

  This hook is just for placing within a given workspace after the workspace has been decided by the default workspace selection policy. It is called in protected mode. For arbitrary placement policies, `clientwin_do_manage_alt` should be used; it isn't called in protected mode,

Hook name:
  `region_do_warp_alt`
Parameters:
  `WRegion`
Description:
  This alt-hook exist to allow for alternative pointer warping implementations.

Hook name:
  `screen_managed_changed_hook`
Parameters:
  `table`
Description:
  Called when there are changes in the objects managed by a screen or their order. The table parameter is similar to that of `frame_managed_changed_hook`.

Hook name:
  `region_notify_hook`
Parameters:
  `(WRegion, string)`
Description:
  Signalled when something (minor) has changed in relation to the first parameter region. The string argument gives the change:

  String
  `deinit`
  `activated`
  `inactivated`
  `activity`
  `sub_activity`
  `name`
  `unset_manager`
  `set_manager`
  `tag`
  `pseudoactivated`
  `pseudoinactivated`

  A region is pseudo-active, when a) it is itself not active (does not not have the focus, and may not even have a window that could have it), but b) some region managed by it is active.

##
6.10 Miscellaneous

###
6.10.1 Size policies

Some functions accept a `sizepolicy` parameter. The possible values are:

``default`', ``full`', ``full_bounds`', ``free`', ``free_glue`', ``northwest`', ``north`', ``northeast`', ``west`', ``center`', ``east`', ``southwest`', ``south`', ``southeast`', ``stretch_top`', ``stretch_bottom`', ``stretch_left`', ``stretch_right`', ``free_glue_northwest`', ``free_glue_north`', ``free_glue_northeast`', ``free_glue_west`', ``free_glue_center`', ``free_glue_east`', ``free_glue_southwest`', ``free_glue_south`', and ``free_glue_southeast`'.

The ``free'' policies allow the managed object to be moved around, whereas the other versions do not. The ``glue'' policies glue the object to some border, while allowing it to be moved away from it by user action, but not automatically. The ``stretch'' policies stretch the object along the given border, while the coordinate-based policies simply place the object along that border.