Previous Up Next

6  Function reference

6.1  Functions exported by ioncore

Synopsis:
string ioncore.aboutmsg()
Description:
Returns an about message (version, author, copyright notice).
Synopsis:
bool ioncore.add_searchdir(string dir)
Description:
Add a directory to search path.
Synopsis:
bool ioncore.add_shortenrule(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 Description
$0 Place the original string here.
$1 to $9 Insert n:th capture here (as usual,captures are surrounded by parentheses in the regex).
$| Alternative shortening separator. The shortening described before the first this kind of separator is tried first and if it fails to make the string short enough, the next is tried, and so on.
$< Remove characters on the left of this marker to shorten the string.
$> Remove characters on the right of this marker to shorten the string. Only the first $< or $> within an alternative shortening is used.
Synopsis:
void ioncore.clear_tags()
Description:
Untag all regions.
Synopsis:
table ioncore.clientwin_list()
Description:
Return a list of all client windows.
Synopsis:
bool 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.
Synopsis:
bool ioncore.exec_on(WRegion reg, string cmd)
Description:
Run cmd with the environment variable DISPLAY set to point to the root window of the X screen reg is on.
Synopsis:
WScreen ioncore.find_screen_id(integer id)
Description:
Find the screen with numerical id id. If Xinerama is not present, id corresponds to X screen numbers. Otherwise the ids are some arbitrary ordering of Xinerama rootwins.
Synopsis:
WHook ioncore.get_hook(string name)
Description:
Find named hook name.
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.
Synopsis:
table ioncore.get_scriptdirs()
Description:
Get all directories on search path.
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 the region that had its activity state previously saved.

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 Ion supporting locale-specifically multibyte-encoded strings?
Synopsis:
bool ioncore.load_module(string modname)
Description:
Attempt to load module modname. Ion will use libltdl to search the library path (the default setting is ~/.ion3/libs and $PREFIX/lib/ion) and also try diffent extensions, so only the module name should usually be necessary to give here.
Synopsis:
WClientWin ioncore.lookup_clientwin(string name)
Description:
Attempt to find a client window with name name.
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.
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.
Synopsis:
bool ioncore.popen_bgread(string cmd, function handler)
Description:
Run cmd with a read pipe connected to its stdout. When data is received through the pipe, handler is called with that data.
Synopsis:
table ioncore.region_list(string typenam)
Description:
Find all non-client window regions inheriting typenam.
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:
table ioncore.root_windows()
Description:
Returns a table of root windows indexed by the X screen id.
Synopsis:
string ioncore.sessiondir()
Description:
Get session directory.
Synopsis:
void ioncore.set_dblclick_delay(integer dd)
Description:
Set double click delay in milliseconds.
Synopsis:
void ioncore.set_get_winprop_fn(function fn)
Description:
Set function used to look up winprops.
Synopsis:
void ioncore.set_moveres_accel(integer t_max, integer t_min, double step, double maxacc)
Description:
Set keyboard resize acceleration parameters. When a keyboard resize function is called, and at most t_max milliseconds has passed from a previous call, acceleration factor is reset to 1.0. Otherwise, if at least t_min milliseconds have passed from the from previous acceleration update or reset the squere root of the acceleration factor is incremented by step. The maximum acceleration factor (pixels/call modulo size hints) is given by maxacc. The default values are (200, 50, 30, 100).

Notice the interplay with X keyboard acceleration parameters. (Maybe insteed of t_min we should use a minimum number of calls to the function/key presses between updated? Or maybe the resize should be completely time-based with key presses triggering the changes?)
Synopsis:
void ioncore.set_opaque_resize(bool opaque)
Description:
Enable/disable opaque move/resize mode.
Synopsis:
void ioncore.set_resize_delay(integer rd)
Description:
Set keyboard resize mode auto-finish delay in milliseconds.
Synopsis:
void ioncore.set_screen_notify(bool enabled)
Description:
Set to true to enable small notification windows at corners of screens when there is activity on a hidden workspace (or other object).
Synopsis:
void ioncore.set_switchto(bool sw)
Description:
Should newly created client window be switched to immediately or should the active window retain focus by default?
Synopsis:
void ioncore.set_warp(bool warp)
Description:
Enable/disable warping pointer to be contained in activated region.
Synopsis:
void ioncore.shutdown()
Description:
End session saving it first.
Synopsis:
void ioncore.snapshot()
Description:
Save session.
Synopsis:
string ioncore.userdir()
Description:
Get user configuration file directory.
Synopsis:
string ioncore.version()
Description:
Returns Ioncore version string.
Synopsis:
void ioncore.warn(string str)
Description:
Issue a warning. How the message is displayed depends on the current warning handler.

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), WM_WINDOW_ROLE (and role) and _ION_KLUDGES (kludges) properties for cwin. If a property is not set, the corresponding field(s) are unset in the table.
Synopsis:
void WClientWin.kill(WClientWin cwin)
Description:
Attempt to kill (with XKillWindow) the client that owns the X window correspoding to cwin.
Synopsis:
table WClientWin.managed_list(WClientWin cwin)
Description:
Returns a list of regions managed by the clientwin (transients, mostly).
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:
bool WClientWin.toggle_fullscreen(WClientWin cwin)
Description:
Toggle between full screen and normal (framed) mode.
Synopsis:
void WClientWin.toggle_transients_pos(WClientWin cwin)
Description:
Toggle transients managed by cwin between top/bottom of the window.
Synopsis:
double WClientWin.xid(WClientWin cwin)
Description:
Return the X window id for the client window.

6.1.2  WFrame functions

Synopsis:
WMoveresMode WFrame.begin_moveres(WFrame frame)
Description:
Enter move/resize mode for frame. The bindings set with WMoveresMode.bindings are used in this mode and of of the exported functions only WMoveresMode.resize, WMoveresMode.move, WMoveresMode.cancel and WMoveresMode.end are allowed to be called.
Synopsis:
bool WFrame.is_shaded(WFrame frame)
Description:
Is frame shaded?
Synopsis:
bool WFrame.is_tabbar_hidden(WFrame frame)
Description:
Is frame's tab bar displayed?
Synopsis:
void WFrame.maximize_horiz(WFrame frame)
Description:
Attempt to maximize frame horizontally.
Synopsis:
void WFrame.maximize_vert(WFrame frame)
Description:
Attempt to maximize frame vertically.
Synopsis:
void WFrame.p_move(WFrame frame)
Description:
Start moving frame with the mouse or other pointing device. This function should only be used by binding it to mpress or mdrag action.
Synopsis:
void WFrame.p_resize(WFrame frame)
Description:
Start resizing frame with the mouse or other pointing device. This function should only be used by binding it to mpress or mdrag action.
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.toggle_shade(WFrame frame)
Description:
Toggle shade (only titlebar visible) mode.
Synopsis:
bool WFrame.toggle_tab(WFrame frame)
Description:
Toggle tab visibility.

6.1.3  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?
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.4  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:
Field Description
type Class name (a string) of the object to be created. Mandatory.
name Name of the object to be created (a string). Optional.
switchto Should the region be switched to (boolean)? Optional.
index Index of the new region in mplex's list of managed objects (integer, 0 = first). Optional.
layer Layer to attach on; 1 (default) or 2.
passive Is a layer 2 object passive/skipped when deciding object to gives focus to (boolean)? Optional.

In addition parameters to the region to be created are passed in this same table.
Synopsis:
void WMPlex.attach_tagged(WMPlex mplex)
Description:
Attach all tagged regions to mplex.
Synopsis:
void WMPlex.dec_index(WMPlex mplex, WRegion r)
Description:
Move r ''right'' within objects managed by mplex.
Synopsis:
integer WMPlex.get_index(WMPlex mplex, WRegion reg)
Description:
Get index of reg within the multiplexer. The first region managed by mplex has index zero. If reg is not managed by mplex, -1 is returned.
Synopsis:
table WMPlex.get_stdisp(WMPlex mplex)
Description:
Get status display information. See WMPlex.get_stdisp for information on the fields.
Synopsis:
void WMPlex.inc_index(WMPlex mplex, WRegion r)
Description:
Move r ''right'' within objects managed by mplex.
Synopsis:
bool WMPlex.l2_hide(WMPlex mplex, WRegion reg)
Description:
If var reg is on the l2 list of mplex and currently shown, hide it. if reg is nil, hide all objects on the l2 list.
Synopsis:
bool WMPlex.l2_show(WMPlex mplex, WRegion reg)
Description:
If var reg is on the l2 list of mplex and currently hidden, display it. if reg is nil, display all objects on the l2 list.
Synopsis:
integer WMPlex.lcount(WMPlex mplex, integer l)
Description:
Returns the number of regions managed by mplex on layer l.
Synopsis:
WRegion WMPlex.lcurrent(WMPlex mplex, integer l)
Description:
Return the managed object currently active within layer l of mplex.
Synopsis:
table WMPlex.llist(WMPlex mplex, integer l)
Description:
Returns a list of regions managed by mplex on layer l.
Synopsis:
WRegion WMPlex.lnth(WMPlex mplex, integer l, integer n)
Description:
Returns the n:th object managed by mplex on the the l:th layer..
Synopsis:
void WMPlex.set_index(WMPlex mplex, WRegion reg, integer index)
Description:
Set index of reg within the multiplexer to index.
Synopsis:
bool 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:
pos The corner of the screen to place the status display in. One of tl, tr, bl or br.
action If this field is set to keep, corner and orientation are changed for the existing status display. If this field is set to remove, the existing status display is removed. If this field is not set or is set to replace, a new status display is created and the old, if any, removed.
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.

6.1.5  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:
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.

6.1.6  WRegion functions

Synopsis:
void WRegion.clear_activity(WRegion reg, bool force)
Description:
Clear notification of activity in reg. If reg is a client window and its urgency hint is set, force must be set to clear the state.
Synopsis:
WRegion WRegion.current(WRegion mgr)
Description:
Return the object, if any, that is considered ''currently active'' within the objects managed by mplex.
Synopsis:
bool WRegion.display(WRegion reg)
Description:
Attempt to display reg.
Synopsis:
bool WRegion.display_sp(WRegion reg)
Description:
Attempt to display reg and save the current region activity status for use by goto_previous.
Synopsis:
table WRegion.geom(WRegion reg)
Description:
Returns the geometry of reg within its parent; a table with fields x, y, w and h.
Synopsis:
bool WRegion.goto(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:
bool WRegion.is_active(WRegion reg)
Description:
Is reg active/does it or one of it's children of focus?
Synopsis:
bool WRegion.is_mapped(WRegion reg)
Description:
Is reg visible/is it and all it's ancestors mapped?
Synopsis:
bool WRegion.is_tagged(WRegion reg)
Description:
Is reg tagged?
Synopsis:
WRegion WRegion.manager(WRegion reg)
Description:
Returns the region that manages reg.
Synopsis:
string WRegion.name(WRegion reg)
Description:
Returns the name for reg.
Synopsis:
void WRegion.notify_activity(WRegion reg)
Description:
Notify of activity in reg.
Synopsis:
WRegion WRegion.parent(WRegion reg)
Description:
Returns the parent region of reg.
Synopsis:
WRootWin WRegion.rootwin_of(WRegion reg)
Description:
Returns the root window reg is on.
Synopsis:
bool WRegion.rqclose(WRegion reg)
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). If the operations is likely to succeed, true is returned, otherwise false. In most cases the region will not have been actually destroyed when this function returns.
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. Also see notes for WRegion.rqclose_propagate.
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:
WScreen WRegion.screen_of(WRegion reg)
Description:
Returns the screen reg is on.
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:
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.
Synopsis:
void WRegion.tag(WRegion reg)
Description:
Tag reg.
Synopsis:
void WRegion.toggle_tag(WRegion reg)
Description:
Toggle region reg tag.
Synopsis:
void WRegion.untag(WRegion reg)
Description:
Untag reg.

6.1.7  WRootWin functions

Synopsis:
WScreen WRootWin.current_scr(WRootWin rootwin)
Description:
Returns previously active screen on root window rootwin.

6.1.8  WScreen functions

Synopsis:
integer WScreen.id(WScreen scr)
Description:
Return the numerical id for screen scr.
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.9  global functions

Synopsis:
bool obj_exists(Obj obj)
Description:
Does obj still exist on the C side of Ion?
Synopsis:
bool obj_is(Obj obj, string typename)
Description:
Is obj of type typename.
Synopsis:
string obj_typename(Obj obj)
Description:
Return type name of obj.
Synopsis:
bool include(string what)
Description:
Execute another file with Lua code.

6.1.10  gr functions

Synopsis:
void gr.read_config()
Description:
Read drawing engine configuration file draw.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.2  Functions exported by mod_ionws

6.2.1  WIonWS functions

Synopsis:
WRegion WIonWS.current(WIonWS ws)
Description:
Returns most recently active region on ws.
Synopsis:
WRegion WIonWS.farthest(WIonWS ws, string dirstr)
Description:
Return the most previously active region on ws with no other regions next to it in direction dirstr (left/right/up/down).
Synopsis:
WRegion WIonWS.goto_dir(WIonWS ws, string dirstr)
Description:
Go to the most previously active region on ws next to reg in direction dirstr (up/down/left/right), wrapping around to a most recently active farthest region in the opposite direction if reg is already the further region in the given direction.

Note that this function is asynchronous; the region will not actually have received the focus when this function returns.
Synopsis:
WRegion WIonWS.goto_dir_nowrap(WIonWS ws, string dirstr)
Description:
Go to the most previously active region on ws next to reg in direction dirstr (up/down/left/right) without wrapping around.
Synopsis:
table WIonWS.managed_list(WIonWS ws)
Description:
Returns a list of regions managed by the workspace (frames, mostly).
Synopsis:
WRegion WIonWS.next_to(WIonWS ws, WRegion reg, string dirstr)
Description:
Return the most previously active region next to reg in direction dirstr (left/right/up/down). The region reg must be managed by ws.
Synopsis:
WSplit WIonWS.node_of(WIonWS ws, WRegion reg)
Description:
For region reg managed by ws return the WSplit a leaf of which reg is.
Synopsis:
WRegion WIonWS.region_at(WIonWS ws, integer x, integer y)
Description:
Find region on ws overlapping coordinates (x, y).
Synopsis:
table WIonWS.resize_tree(WIonWS ws, Obj node, table g)
Description:
Attempt to resize and/or move the split tree starting at node (WSplit or WRegion). Behaviour and the g parameter are as for WRegion.rqgeom operating on node (if it were a WRegion).
Synopsis:
WFrame WIonWS.split_at(WIonWS ws, WFrame frame, string dirstr, bool attach_current)
Description:
Split frame creating a new frame to direction dir (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.
Synopsis:
WFrame WIonWS.split_top(WIonWS ws, string dirstr)
Description:
Create a new frame on ws above/below/left of/right of all other objects depending on dirstr (one of ''left'', ''right'', ''top'' or ''bottom'').
Synopsis:
WSplit WIonWS.split_tree(WIonWS ws)
Description:
Returns the root of the split tree.
Synopsis:
void WIonWS.unsplit_at(WIonWS ws, WFrame frame)
Description:
Try to relocate regions managed by frame to another frame and, if possible, destroy the frame.

6.2.2  WSplit functions

Synopsis:
WSplit WSplit.br(WSplit split)
Description:
For splits of type SPLIT_HORIZONTAL the right child node is returned, and for splits of type SPLIT_VERTICAL returns the bottom child node is returned. For other types of nodes nil is returned.
Synopsis:
table WSplit.geom(WSplit split)
Description:
Returns the area of workspace used by the regions under split.
Synopsis:
WSplit WSplit.parent(WSplit split)
Description:
Return parent split for split.
Synopsis:
WRegion WSplit.reg(WSplit node)
Description:
For split nodes of type SPLIT_REGNODE or SPLIT_STDISPNODE this function returns the region contained in the node. For other types of nodes nil is returned.
Synopsis:
WSplit WSplit.tl(WSplit split)
Description:
For splits of type SPLIT_HORIZONTAL the left child node is returned, and for splits of type SPLIT_VERTICAL returns the top child node is returned. For other types of nodes nil is returned.
Synopsis:
string WSplit.type(WSplit split)
Description:
Returns the split type of node, one of SPLIT_VERTICAL, SPLIT_HORIZONTAL, SPLIT_UNUSED, SPLIT_REGNODE and SPLIT_STDISPNODE.

6.3  Functions exported by mod_floatws

Synopsis:
void mod_floatws.set_placement_method(string method)
Description:
Set placement method for WFloatWS:s. Method can be one of ''udlr'', ''lrud'' (default) and ''random''. The method ''udlr'' looks for free space starting from top the top left corner of the workspace moving first down keeping the x coordinate fixed. If it find no free space, it start looking similarly at next x coordinate unoccupied by other objects and so on. ''lrud' is the same but with the role of coordinates changed and both fall back to ''random'' placement if no free area was found.

6.3.1  WFloatFrame functions

Synopsis:
bool WFloatFrame.is_sticky(WFloatFrame frame)
Description:
Is frame sticky?
Synopsis:
void WFloatFrame.toggle_sticky(WFloatFrame frame)
Description:
Toggle frame stickyness. Only works across frames on WFloatWS that have the same WMPlex parent.

6.3.2  WFloatWS functions

Synopsis:
bool WFloatWS.attach(WFloatWS ws, WClientWin cwin, table p)
Description:
Attach client window cwin on ws. At least the following fields in p are supported:
Field Description
switchto Should the region be switched to (boolean)? Optional.
geom Geometry; x and y, if set, indicates top-left of the frame to be created while width and height, if set, indicate the size of the client window within that frame. Optional.
Synopsis:
WRegion WFloatWS.backcirculate(WFloatWS ws)
Description:
Activate previous object on ws.
Synopsis:
WRegion WFloatWS.circulate(WFloatWS ws)
Description:
Activate next object on ws.
Synopsis:
WRegion WFloatWS.current(WFloatWS ws)
Description:
Returns the object that currently has or previously had focus on ws (if no other object on the workspace currently has focus).
Synopsis:
void WFloatWS.lower(WFloatWS ws, WRegion reg)
Description:
Lower reg that must be managed by ws. If reg is nil, this function silently fails.
Synopsis:
table WFloatWS.managed_list(WFloatWS ws)
Description:
Returns a list of regions managed by the workspace (frames, mostly).
Synopsis:
void WFloatWS.raise(WFloatWS ws, WRegion reg)
Description:
Raise reg that must be managed by ws. If reg is nil, this function silently fails.
Synopsis:
bool WFloatWS.rqclose_relocate(WFloatWS ws)
Description:
Destroys ws unless this would put the WM in a possibly unusable state.

6.4  Functions exported by mod_query

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.
Synopsis:
void mod_query.history_push(string str)
Description:
Push an entry into line editor history.
Synopsis:
WMessage mod_query.message(WMPlex mplex, string p)
Description:
Display a message in the mplex.
Synopsis:
WEdln mod_query.query(WMPlex mplex, string prompt, string dflt, function handler, function completor)
Description:
Show a query window in mplex with prompt prompt, initial contents dflt. The function handler is called with the entered string as the sole argument when WEdln.finish is called. The function completor is called with the created WEdln is first argument and the string to complete is the second argument when WEdln.complete is called.
Synopsis:
WMessage mod_query.warn(WMPlex mplex, string p)
Description:
Display an error message box in the multiplexer mplex.

6.4.1  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)
Description:
Call completion handler with the text between the beginning of line and current cursor position.
Synopsis:
string WEdln.contents(WEdln wedln)
Description:
Get line editor contents.
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)
Description:
Replace line editor contents with the entry in history if one exists.
Synopsis:
void WEdln.history_prev(WEdln wedln)
Description:
Replace line editor contents with the previous in history if one exists.
Synopsis:
void WEdln.insstr(WEdln wedln, string str)
Description:
Input str in wedln at current editing point.
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.
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.
Synopsis:
void WEdln.set_completions(WEdln wedln, table completions)
Description:
This function should be called in completors (such given as parameters to mod_query.query) to return the set of completions found. The numerical indexes of completions list the found completions. If the entry common_part exists, it gives an extra common prefix of all found completions.
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..

6.4.2  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.5  Functions exported by mod_menu

Synopsis:
WMenu mod_menu.menu(WMPlex mplex, function handler, table tab, bool big_mode)
Description:
Display a menu inside multiplexer. The handler parameter is a function that gets the selected menu entry as argument and should call it with proper parameters. The table tab is a list of menu entries of the form {name = ???, [ submenu_fn = ??? ]}. The function submenu_fn return a similar submenu definition when called.

Do not use this function directly. Use menulib.menu and menulib.bigmenu.
Synopsis:
WMenu mod_menu.pmenu(WWindow where, function handler, table tab)
Description:
Display a pop-up menu inside window where. This function can only be called from a mouse/pointing device button press handler and the menu will be placed below the point where the press occured. The handler and tab parameters are similar to those of menu_menu.

Do not use this function directly. Use menulib.pmenu.
Synopsis:
void mod_menu.set_scroll_params(integer delay, integer amount)
Description:
Set ''pmenu'' off-screen scrolling parameters: the number of pixels to scroll at each timer event, amount, and the time between those events, delay (in milliseconds). The default values are 3 pixels every 20msec.

6.5.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.6  Functions exported by mod_dock

6.6.1  WDock functions

Synopsis:
table WDock.get(WDock dock)
Description:
Get dock's configuration table. See WDock.set for a description of the table.
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 Description
name string Name of dock
pos string in {t,m,b}ื{t,c,b} Dock position. Can only be used in floating mode.
grow up/down/left/right Growth direction where new dockapps are added. Also sets orientation for dock when working as WMPlex status display (see WMPlex.set_stdisp).
is_auto bool Should dock automatically manage new dockapps?

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

6.7  Functions exported by mod_sp

Synopsis:
bool mod_sp.toggle_on(WMPlex mplex)
Description:
Toggle displayed status of some scratchpad on mplex if one is found.

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.

6.9  Functions defined in ioncorelib

Synopsis:
ioncorelib.close_current_ws(scr)
Description:
Close current workspace on screen scr.
Synopsis:
ioncorelib.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:
ioncorelib.create_new_ws(scr, ws_type)
Description:
Create new workspace on screen scr. If ws_type is set, then a workspace of that type is created. Otherwise a workspace of type indicated by the DEFAULT_WS_TYPE variable is created.
Synopsis:
ioncorelib.defbindings(context, bindings)
Description:
Define bindings for context context. Here binding is a table composed of entries created with ioncorelib.kpress, etc.; see section 3.3 for details.
Synopsis:
ioncorelib.defwinprop(list)
Description:
Define a winprop. For more information, see section 3.4.
Synopsis:
ioncorelib.export(lib, ...)
Description:
Export a list of functions from lib into global namespace.
Synopsis:
ioncorelib.find_manager(obj, t)
Description:
Find an object with type name t managing obj or one of its managers.
Synopsis:
ioncorelib.get_winprop(cwin)
Description:
Find winprop table for cwin.
Synopsis:
ioncorelib.getbindings(maybe_context)
Description:
Get a table of all bindings.
Synopsis:
ioncorelib.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 func. For more information on bindings, see section 3.3.
Synopsis:
ioncorelib.kpress_wait(keyspec, cmd, guard)
Description:
This is similar to 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:
ioncorelib.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 func. For more information, see section 3.3.
Synopsis:
ioncorelib.mdblclick(buttonspec, cmd, guard)
Description:
Similar to mclick but for double-click. Also see section 3.3.
Synopsis:
ioncorelib.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:
ioncorelib.mpress(buttonspec, cmd, guard)
Description:
Similar to mclick but for just pressing the mouse button. Also see section 3.3.
Synopsis:
ioncorelib.show_manual(for_what)
Description:
Show manual page for for_what, ion if unset.
Synopsis:
ioncorelib.submap(kcb_, 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.

6.9.1  string functions

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

6.9.2  table functions

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.join(t1, t2)
Description:
Create a table containing all entries from t1 and those from t2 that are missing from t1.

6.10  Functions defined in querylib

Synopsis:
querylib.popen_completions(wedln, cmd, beg)
Description:
This function can be used to read completions from an external source. The string cmd is a shell command to be executed. To its stdout, the command should on the first line write the common_part parameter of WEdln.set_completions and a single actual completion on each of the successive lines.
Synopsis:
querylib.query_attachclient(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:
querylib.query_editfile(mplex)
Description:
Asks for a file to be edited. It uses the script ion-edit to start a program to edit the file. This script uses run-mailcap by default, but if you don't have it, you may customise the script.
Synopsis:
querylib.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.
Synopsis:
querylib.query_gotoclient(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:
querylib.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:
querylib.query_man(mplex)
Description:
This query asks for a manual page to display. It uses the command ion-man to run man in a terminal emulator. By customizing this script it is possible use some other man page viewer. The script ion-completeman is used to complete manual pages.
Synopsis:
querylib.query_menu(mplex, prompt, menuname)
Description:
This query can be used to create a query of a defined menu.
Synopsis:
querylib.query_renameframe(frame)
Description:
This function asks for a name new for the frame where the query was created.
Synopsis:
querylib.query_renameworkspace(mplex)
Description:
This function asks for a name new for the workspace on which the query resides.
Synopsis:
querylib.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:
querylib.query_runfile(mplex)
Description:
Asks for a file to be viewed. It uses the script ion-view to start a program to view the file. This script uses run-mailcap by default, but if you don't have it, you may customise the script.
Synopsis:
querylib.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:
querylib.query_ssh(mplex)
Description:
This query asks for a host to connect to with SSH. It starts up ssh in a terminal using ion-ssh. Hosts to tab-complete are read from ~/.ssh/known_hosts.
Synopsis:
querylib.query_workspace(mplex)
Description:
This query asks for the name of a workspace. If a workspace (an object inheriting WGenWS) 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:
querylib.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:
querylib.show_about_ion(mplex)
Description:
Display an "About Ion" message in mplex.
Synopsis:
querylib.show_clientwin(mplex, cwin)
Description:
Show information about a client window.

6.11  Functions defined in menulib

Synopsis:
menulib.bigmenu(mplex, sub, menu_or_name)
Description:
This function is similar to menulib.menu, but a style with possibly bigger font and menu entries is used.
Synopsis:
menulib.defmenu(name, tab)
Description:
Define a new menu with name being the menu's name and tab being a table of menu entries.
Synopsis:
menulib.getmenu(menu_or_name)
Description:
If menu_or_name is a string, returns a menu defined with defmenu, else return menu_or_name.
Synopsis:
menulib.menu(mplex, sub, menu_or_name)
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 menulib.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.
Synopsis:
menulib.menuentry(name, cmd, guard)
Description:
Use this function to define normal menu entries. The string name is the string shown in the visual representation of menu, and the parameter cmd and guard are similar to those of ioncorelib.defbindings.
Synopsis:
menulib.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 thos of menulib.menu.
Synopsis:
menulib.refresh_styles()
Description:
Refresh list of known style files.
Synopsis:
menulib.submenu(name, sub_or_name)
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.

Previous Up Next