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_moduledir(string dir)
Description:
Add a module search path.
Synopsis:
bool ioncore.add_scriptdir(string dir)
Description:
Add a script 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(WRootWin rootwin, string cmd)
Description:
Run cmd with the environment variable DISPLAY set to point to the root window rootwin of the X display the WM is running on.
Synopsis:
void ioncore.exit()
Description:
Causes the window manager to exit.
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:
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.restart()
Description:
Restart Ioncore.
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:
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_save_layout(bool enable)
Description:
Enable or disable layout saving on exit.
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:
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.

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_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  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.

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:
void WMPlex.inc_index(WMPlex mplex, WRegion r)
Description:
Move r ''right'' within objects managed by mplex.
Synopsis:
integer WMPlex.l1_count(WMPlex mplex)
Description:
Returns the number of regions managed/multiplexed by mplex on layer 1.
Synopsis:
WRegion WMPlex.l1_current(WMPlex mplex)
Description:
Return the managed object currently active within layer 1 of mplex.
Synopsis:
table WMPlex.l1_list(WMPlex mplex)
Description:
Returns a list of regions managed by mplex on layer 1.
Synopsis:
WRegion WMPlex.l1_nth(WMPlex mplex, integer n)
Description:
Returns the n:th object managed by mplex on the layer 1 list.
Synopsis:
integer WMPlex.l2_count(WMPlex mplex)
Description:
Returns the number of regions managed by mplex on layer 2.
Synopsis:
WRegion WMPlex.l2_current(WMPlex mplex)
Description:
Return the managed object currently active within layer 2 of 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:
table WMPlex.l2_list(WMPlex mplex)
Description:
Returns a list of regions managed by mplex on layer 2.
Synopsis:
WRegion WMPlex.l2_nth(WMPlex mplex, integer n)
Description:
Returns the n:th object managed by mplex on the layer 1 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:
void WMPlex.set_index(WMPlex mplex, WRegion reg, integer index)
Description:
Set index of reg within the multiplexer to index.
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.4  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.5  WRegion functions

Synopsis:
WRegion WRegion.active_sub(WRegion reg)
Description:
Returns most recently active region that has reg as its parent.
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:
void WRegion.keep_on_top(WRegion reg)
Description:
Inform that reg should be kept above normally stacked regions within its parent.
Synopsis:
void WRegion.lower(WRegion reg)
Description:
Lower reg in the stack. The regions marked to be stacked above reg will also be lowerd and regions marked to be kept on top will not be lowered below normally stacked regions.
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:
WRegion WRegion.parent(WRegion reg)
Description:
Returns the parent region of reg.
Synopsis:
void WRegion.raise(WRegion reg)
Description:
Raise reg in the stack. The regions marked to be stacked above reg will also be raised and normally stacked regions will not be raised above region marked to be kept on top.
Synopsis:
void WRegion.reset_stacking(WRegion reg)
Description:
Inform that reg should be stacked normally.
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:
bool WRegion.stack_above(WRegion reg, WRegion above)
Description:
Inform that reg should be stacked above the region above.
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.6  WRootWin functions

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

6.1.7  WScreen functions

Synopsis:
integer WScreen.id(WScreen scr)
Description:
Return the numerical id for screen scr.

6.1.8  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.9  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:
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 (WWsSplit or WRegion). Behaviour and the g parameter are as for WRegion.rqgeom operating on node (if it were a WRegion).
Synopsis:
WIonFrame WIonWS.split_at(WIonWS ws, WIonFrame frame, string dirstr, bool attach_current)
Description:
Split frame creating a new WIonFrame 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:
WWsSplit WIonWS.split_of(WIonWS ws, WRegion reg)
Description:
For region reg managed by ws return the WWsSplit a leaf of which reg is.
Synopsis:
WIonFrame WIonWS.split_top(WIonWS ws, string dirstr)
Description:
Create new WIonFrame on ws above/below/left of/right of all other objects depending on dirstr (one of ''left'', ''right'', ''top'' or ''bottom'').
Synopsis:
void WIonWS.unsplit_at(WIonWS ws, WIonFrame frame)
Description:
Try to relocate regions managed by frame to another frame and, if possible, destroy the frame.

6.2.2  WWsSplit functions

Synopsis:
Obj WWsSplit.br(WWsSplit split)
Description:
Return the object (region or split) corresponding to bottom or right sibling of split depending on the split's direction.
Synopsis:
table WWsSplit.geom(WWsSplit split)
Description:
Returns the area of workspace used by the regions under split.
Synopsis:
bool WWsSplit.is_horizontal(WWsSplit split)
Description:
Is split a horizontal split?
Synopsis:
bool WWsSplit.is_vertical(WWsSplit split)
Description:
Is split a vertical split?
Synopsis:
WWsSplit WWsSplit.parent(WWsSplit split)
Description:
Return parent split for split.
Synopsis:
Obj WWsSplit.tl(WWsSplit split)
Description:
Return the object (region or split) corresponding to top or left sibling of split depending on the split's direction.

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.p_move(WFloatFrame frame)
Description:
Start moving frame with the mouse (or other pointing device). this should only be used by binding to the mpress or mdrag actions.
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.backcirculate_and_raise(WFloatWS ws)
Description:
Activate and raise previous object on ws.
Synopsis:
WRegion WFloatWS.circulate(WFloatWS ws)
Description:
Activate next object on ws.
Synopsis:
WRegion WFloatWS.circulate_and_raise(WFloatWS ws)
Description:
Activate and raise 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:
table WFloatWS.managed_list(WFloatWS ws)
Description:
Returns a list of regions managed by the workspace (frames, mostly).
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

Synopsis:
WDock mod_dock.create_dock(integer screen, table conftab)
Description:
Create a dock. screen is the screen number on which the dock should appear. conftab is the initial configuration table passed to WDock.set.

6.6.1  WDock functions

Synopsis:
void WDock.destroy(WDock dock)
Description:
Destroys dock if it is empty.
Synopsis:
table WDock.get(WDock dock)
Description:
Get dock's configuration table. See WDock.set for a description of the table.
Synopsis:
bool WDock.is_mapped(WDock dock)
Description:
Is dock mapped? This is much faster than calling WDock.get(dock).is_mapped.
Synopsis:
void WDock.map(WDock dock)
Description:
Map (show) dock. This is much faster than calling WDock.set(dock, {is_mapped=true}).
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
hpos left/center/right Horizontal position
vpos top/middle/bottom Vertical position
grow up/down/left/right Growth direction where new dockapps are added)
is_auto bool Should dock automatically manage new dockapps?
is_mapped bool Is dock mapped?

Any parameters not explicitly set in conftab will be left unchanged.
Synopsis:
void WDock.toggle(WDock dock)
Description:
Toggle dock's mapped (shown/hidden) state.
Synopsis:
void WDock.unmap(WDock dock)
Description:
Unmap (hide) dock. This is much faster than calling WDock.set(dock, {is_mapped=false}).

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.add_to_hook(hookname, fn)
Description:
Register fn as a handler for hook hookname.
Synopsis:
ioncorelib.call_hook(hookname, ...)
Description:
Call hook hookname with the remaining arguments to this function as parameters.
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.remove_from_hook(hookname, fn)
Description:
Unregister fn as a handler for hook hookname.
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.

6.10  Functions defined in querylib

Synopsis:
querylib.popen_completions(wedln, cmd)
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_exit(mplex)
Description:
This query asks whether the user wants to have Ioncore exit. If the answer is 'y', 'Y' or 'yes', so will happen.
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_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_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.

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