next up previous contents index
Next: A. The GNU General Up: Ion: Configuring and extending Previous: 5. Scripting   Contents   Index

Subsections


6. Function reference

The following subsections list out the functions exported to Lua scripts by Ioncore and the ionws, floatws and query modules.


6.1 Functions exported by Ioncore

Synopsis:
bool 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 clear_tags()
Description:
Untag all regions.

Synopsis:
table complete_clientwin(string nam)
Description:
Find all client windows whose name begins with nam or, if none are found, all whose name contains name.

Synopsis:
table complete_region(string nam, string typenam)
Description:
Find all non-client window regions inheriting typename and whose name begins with nam or, if none are found all whose name contains name.

Synopsis:
void enable_opaque_resize(bool opaque)
Description:
Enable/disable opaque move/resize mode.

Synopsis:
void enable_warp(bool warp)
Description:
Enable/disable warping pointer to be contained in activated region.

Synopsis:
void enable_workspace_saves(bool enable)
Description:

Synopsis:
bool 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:
void exit_wm()
Description:
Causes the window manager to exit.

Synopsis:
void warn(string str)
Description:
Issue a warning. How the message is displayed depends on the current warning handler.

Synopsis:
WScreen 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:
bool genframe_bindings(table tab)
Description:
Add a set of bindings available in WGenFrames (all types of frames).

Synopsis:
string 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:
bool global_bindings(table tab)
Description:
Add a set of bindings available everywhere. The bound functions should accept WScreen as argument.

Synopsis:
WScreen 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 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 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 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:
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 reread_draw_config.

Synopsis:
bool include(string what)
Description:
Execute another file with Lua code.

Synopsis:
bool initialise_screen_id(integer id, table tab)
Description:
(Intended to be called from workspace savefiles.) Set screen name and initial workspaces etc.

Synopsis:
string ioncore_aboutmsg()
Description:
Returns an about message (version, author, copyright notice).

Synopsis:
bool ioncore_add_scriptdir(string dir)
Description:
Add a search path.

Synopsis:
table ioncore_get_scriptdirs()
Description:
Get all directories on search path.

Synopsis:
bool ioncore_is_i18n()
Description:
Is Ion supporting locale-specifically multibyte-encoded strings?

Synopsis:
string ioncore_userdir()
Description:
Get user configuration file directory.

Synopsis:
string ioncore_version()
Description:
Returns Ioncore version string.

Synopsis:
bool load_module(string modname)
Description:
Attempt to load module modname. Ion will use libltdl to search the library path (the default setting is ~/.ion2/libs and $PREFIX/lib/ion) and also try diffent extensions, so only the module name should usually be necessary to give here.

Synopsis:
WClientWin lookup_clientwin(string name)
Description:
Attempt to find a client window with name name.

Synopsis:
WRegion lookup_region(string name, string typenam)
Description:
Attempt to find a non-client window region with name name and type inheriting typenam.

Synopsis:
string lookup_script(string file, string try_in_dir)
Description:

Synopsis:
bool mplex_bindings(table tab)
Description:
Add a set of bindings available in WMPlexes (screens and all types of frames).

Synopsis:
bool obj_is(WObj obj, string typename)
Description:
Is obj of type typename.

Synopsis:
string obj_typename(WObj obj)
Description:
Return type name of obj.

Synopsis:
bool 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:
void restart_other_wm(string cmd)
Description:
Attempt to restart another window manager cmd.

Synopsis:
void restart_wm()
Description:
Restart Ioncore.

Synopsis:
table root_windows()
Description:
Returns a table of root windows indexed by the X screen id.

Synopsis:
void set_dblclick_delay(integer dd)
Description:
Set double click delay in milliseconds.

Synopsis:
void set_resize_accel_params(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 set_resize_delay(integer rd)
Description:
Set keyboard resize mode auto-finish delay in milliseconds.

Synopsis:
void set_switch_to_new_clients(bool sw)
Description:
Should newly created client window be switched to immediately or should the active window retain focus by default?

6.1.1 WClientWin functions

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

Synopsis:
void WClientWin.close(WClientWin cwin)
Description:
Request the application that owns the X window corresponding to cwin to close the window. This function will fail if the application is not responding or does not support the WM_DELETE protocol. In that case WClientWin.kill should be used.

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.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 WGenFrame functions

Synopsis:
bool WGenFrame.is_shaded(WGenFrame frame)
Description:
Is frame shaded?

Synopsis:
void WGenFrame.maximize_horiz(WGenFrame frame)
Description:
Attempt to maximize frame horizontally.

Synopsis:
void WGenFrame.maximize_vert(WGenFrame frame)
Description:
Attempt to maximize frame vertically.

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

Synopsis:
void WGenFrame.p_switch_tab(WGenFrame genframe)
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 WGenFrame.p_tabdrag(WGenFrame genframe)
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:
void WGenFrame.toggle_tab(WGenFrame genframe)
Description:
Toggle tab visibility.

6.1.3 WMPlex functions

Synopsis:
bool 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.

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:
WRegion WMPlex.current(WMPlex mplex)
Description:
Return the object managed by and currenly displayed in mplex.

Synopsis:
WRegion WMPlex.current_input(WMPlex mplex)
Description:
Returns the currently active ''input'' (query, message etc.) in mplex or nil.

Synopsis:
integer WMPlex.managed_count(WMPlex mplex)
Description:
Returns the number of regions managed/multiplexed by mplex.

Synopsis:
table WMPlex.managed_list(WMPlex mplex)
Description:
Returns a list of regions managed by mplex.

Synopsis:
void WMPlex.move_to_index(WMPlex mplex, WRegion reg, integer index)
Description:
Set index of reg within the multiplexer to index.

Synopsis:
void WMPlex.move_to_next_index(WMPlex mplex, WRegion reg)
Description:
Move reg to next index within the multiplexer.

Synopsis:
void WMPlex.move_to_prev_index(WMPlex mplex, WRegion reg)
Description:
Move reg to previous index within the multiplexer.

Synopsis:
WRegion WMPlex.nth_managed(WMPlex mplex, integer n)
Description:
Returns the n:th object managed by mplex.

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 WRegion functions

Synopsis:
WRegion WRegion.active_sub(WRegion reg)
Description:
Returns most recently active region that has reg as its parent.

Synopsis:
void WRegion.close(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).

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:
table WRegion.request_geom(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:
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:
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.5 WRootWin functions

Synopsis:
bool WRootWin.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:
WScreen WRootWin.current_scr(WRootWin rootwin)
Description:
Returns previously active screen on root window rootwin.

6.1.6 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.2 Functions exported by the ionws module

Synopsis:
bool ionframe_bindings(table tab)
Description:
Add a set of bindings to the bindings available in WIonFrames.

Synopsis:
bool ionframe_moveres_bindings(table tab)
Description:
Describe WIonFrame resize mode bindings.

Synopsis:
bool ionws_bindings(table tab)
Description:
Add a set of bindings to the bindings available in every object on WIonWS:s.

6.2.1 WIonFrame functions

Synopsis:
void WIonFrame.begin_resize(WIonFrame frame)
Description:
Enter resize mode for frame. The bindings set with ionframe_moveres_bindings are used in this mode and of of the exported functions only WIonFrame.do_resize, ionframe_cancel_resize and WIonFrame.end_resize are allowed to be called.

Synopsis:
void WIonFrame.cancel_resize(WIonFrame frame)
Description:
Return from move/resize cancelling changes if opaque move/resize has not been enabled.

Synopsis:
void WIonFrame.do_resize(WIonFrame frame, integer left, integer right, integer top, integer bottom)
Description:
Shrink or grow frame 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:
void WIonFrame.end_resize(WIonFrame frame)
Description:
Return from move/resize mode and apply changes unless opaque move/resize is enabled.

Synopsis:
void WIonFrame.relocate_and_close(WIonFrame frame)
Description:
Try to relocate regions managed by frame somewhere else and if possible, destroy the frame.

Synopsis:
WIonFrame WIonFrame.split(WIonFrame frame, string dirstr)
Description:
Split frame creating a new WIonFrame to direction dir (one of ''left'', ''right'', ''top'' or ''bottom'') of frame. The active manages region in frame, if any, is moved to the new frame.

Synopsis:
WIonFrame WIonFrame.split_empty(WIonFrame frame, string dirstr)
Description:
Similar to WIonFrame.split except nothing is moved to the newly created frame.

Synopsis:
void WIonFrame.toggle_shade(WIonFrame frame)
Description:
Toggle shade (only titlebar visible) mode.

6.2.2 WIonWS functions

Synopsis:
WRegion WIonWS.above(WIonWS ws, WRegion reg)
Description:
Same as WIonWS.next_to(ws, reg, "up").

Synopsis:
WRegion WIonWS.below(WIonWS ws, WRegion reg)
Description:
Same as WIonWS.nextto(ws, reg, "down").

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_above(WIonWS ws)
Description:
Same as WIonWS.goto_dir(ws, "up").

Synopsis:
WRegion WIonWS.goto_below(WIonWS ws)
Description:
Same as WIonWS.goto_dir(ws, "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_left(WIonWS ws)
Description:
Same as WIonWS.goto_dir(ws, "left").

Synopsis:
WRegion WIonWS.goto_right(WIonWS ws)
Description:
Same as WIonWS.goto_dir(ws, "right").

Synopsis:
WRegion WIonWS.left_of(WIonWS ws, WRegion reg)
Description:
Same as WIonWS.nextto(ws, reg, "left").

Synopsis:
WRegion WIonWS.leftmost(WIonWS ws)
Description:
Same as WIonWS.farthest(ws, "left").

Synopsis:
WRegion WIonWS.lowest(WIonWS ws)
Description:
Same as WIonWS.farthest(ws, "down").

Synopsis:
table WIonWS.managed_list(WIonWS ws)
Description:
Returns a list of regions managed by the workspace (frames, mostly).

Synopsis:
WIonFrame WIonWS.newframe(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:
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:
table WIonWS.resize_tree(WIonWS ws, WObj 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.request_geom operating on node (if it were a WRegion).

Synopsis:
WRegion WIonWS.right_of(WIonWS ws, WRegion reg)
Description:
Same as WIonWS.nextto(ws, reg, "right").

Synopsis:
WRegion WIonWS.rightmost(WIonWS ws)
Description:
Same as WIonWS.farthest(ws, "right").

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:
WRegion WIonWS.topmost(WIonWS ws)
Description:
Same as WIonWS.farthest(ws, "up").

6.2.3 WWsSplit functions

Synopsis:
WObj 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:
WObj 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 the floatws module

Synopsis:
bool floatframe_bindings(table tab)
Description:
Sets up bindings for WFloatFrames.

Synopsis:
bool floatframe_moveres_bindings(table tab)
Description:
Sets up bindings for move/resize mode of WFloatFrames.

Synopsis:
void floatws_bindings(table tab)
Description:
Sets up bindings available in all objects on WFloatWS:s.

Synopsis:
void set_floatws_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:
void WFloatFrame.begin_resize(WFloatFrame frame)
Description:
Enter move/resize mode for frame. The bindings set with floatframe_moveres_bindings are used in this mode and of of the exported functions only WFloatFrame.do_resize, WFloatFrame.do_move, WFloatFrame.cancel_resize and WFloatFrame.end_resize are allowed to be called.

Synopsis:
void WFloatFrame.cancel_resize(WFloatFrame frame)
Description:
Return from move/resize cancelling changes if opaque move/resize has not been enabled.

Synopsis:
void WFloatFrame.do_move(WFloatFrame frame, integer horizmul, integer vertmul)
Description:
Move frame one step (must be in move/resize mode):

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

Synopsis:
void WFloatFrame.do_resize(WFloatFrame frame, integer left, integer right, integer top, integer bottom)
Description:
Shrink or grow frame 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:
void WFloatFrame.end_resize(WFloatFrame frame)
Description:
Return from move/resize mode and apply changes unless opaque move/resize is enabled.

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_shade(WFloatFrame frame)
Description:
Toggle shade (only titlebar visible) mode.

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:
table WFloatWS.managed_list(WFloatWS ws)
Description:
Returns a list of regions managed by the workspace (frames, mostly).

Synopsis:
bool WFloatWS.relocate_and_close(WFloatWS ws)
Description:
Destroys ws unless this would put the WM in a possibly unusable state.


6.4 Functions exported by the query module

Synopsis:
bool query_bindings(table tab)
Description:
Describe bindings common to all WInputs (WEdln, WMessage).

Synopsis:
WMessage query_fwarn(WMPlex mplex, string p)
Description:
Display an error message box in the multiplexer mplex.

Synopsis:
void query_history_clear()
Description:
Clear line editor history.

Synopsis:
string query_history_get(integer n)
Description:
Get entry at index n in line editor history, 0 being the latest.

Synopsis:
void query_history_push(string str)
Description:
Push an entry into line editor history.

Synopsis:
WMessage query_message(WMPlex mplex, string p)
Description:
Display a message in the mplex.

Synopsis:
WEdln 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:
bool query_wedln_bindings(table tab)
Description:
Add a set of bindings available in the line editor.

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.

Synopsis:
void WEdln.set_completions(WEdln wedln, table completions)
Description:
This function should be called in completors (such given as parameters to 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.close(WInput input)
Description:
Same as WInput.cancel.

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 the menu module

Synopsis:
bool menu_bindings(table tab)
Description:
Describe WMenu bindings.

Synopsis:
WMenu 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; use make_menu_fn to create functions that pass a proper handler. The table tab is a list of menu entries of the form {name = ???, [ submenu = ??? ]}. (The table may and usually does contain other entries as well, such as the function to call when entry is activated, but this is handled by handler.)

Synopsis:
WMenu 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.

Synopsis:
void 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.close(WMenu menu)
Description:
Same as WMenu.cancel.

Synopsis:
void WMenu.finish(WMenu menu)
Description:
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.


6.6 Functions exported by the de module

Synopsis:
bool de_do_define_style(WRootWin rootwin, string name, table tab)
Description:
Define a style for the root window rootwin. Use de_define_style instead to define for all root windows.

Synopsis:
void de_reset()
Description:
Clear all styles from drawing engine memory.


6.7 Functions exported by the dock module

Synopsis:
WDock 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.7.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.8 Functions defined in ioncorelib

Function:
WMPlex.close_sub_or_self
Description:
Close a WMPlex or some child of it using WRegion.close as chosen by make_mplex_sub_or_self, but also, when the chosen object is a WClientWin, propagate the close call to transients managed by the WClientWin.

Synopsis:
WMPlex.current_index(mplex)
Description:
Returns the index of WMPlex.current in a mplex's managed list or -1 if there is no current managed object.

Synopsis:
WMPlex.managed_index(mplex, mgd)
Description:
Returns the index of mgd in mplex's managed list or -1 if not on list.

Synopsis:
WMPlex.move_current_to_next_index(mplex)
Description:
Move currently viewed object left within mplex; same as mplex:move_left(mplex:current()).

Synopsis:
WMPlex.move_current_to_prev_index(mplex)
Description:
Move currently viewed object right within mplex; same as mplex:move_left(mplex:current()).

Synopsis:
add_to_hook(hookname, fn)
Description:
Register fn as a handler for hook hookname.

Synopsis:
call_hook(hookname, ...)
Description:
Call hook hookname with the remaining arguments to this function as parameters.

Synopsis:
complete_workspace(nam)
Description:
Equivalent to complete_region(nam, "WGenWS").

Synopsis:
exec_in(where, cmd)
Description:
Equivalent to exec_on_rootwin(WRegion.rootwin_of(where), cmd). This function should be overridden by scripts and other kludges that want to attempt to put new windows where they belong.

Synopsis:
get_winprop(cwin)
Description:
Find winprop table for cwin.

Synopsis:
kpress(keyspec, func)
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:
kpress_waitrel(keyspec, func)
Description:
This is similar to kpress but after calling func, Ioncore waits for all modifiers to be released before processing any further actions. For more information on bindings, see section 3.3.

Synopsis:
lookup_workspace(nam)
Description:
Equivalent to lookup_region(nam, "WGenWS").

Synopsis:
make_exec_fn(cmd)
Description:
This function will generate another function that, depending on its parameter, will call either exec_in or exec_on_rootwin to execute cmd. You should use this function to bind execution commands to keys.

Synopsis:
make_mplex_clientwin_fn(fn)
Description:
Create a WMPlex-bindable function with arguments (mplex [, sub]) that chooses parameter for fn as sub if it is not nil and otherwise mplex:current(), and calls fn if the object chosen is of type WClientWin.

Calling this function is equivalent to make_mplex_sub_or_self_fn(fn, true, true, true).

Synopsis:
make_mplex_sub_fn(fn)
Description:
Create a WMPlex-bindable function with arguments (mplex [, sub]) that calls fn with parameter chosen as sub if it is not nil and otherwise mplex:current().

Calling this function is equivalent to make_mplex_sub_or_self_fn(fn, true, true, false).

Synopsis:
make_mplex_sub_or_self_fn(fn, noself, noinput, cwincheck)
Description:
Create a WMPlex-bindable function with arguments (mplex [, sub]) that calls fn with parameter chosen as the first match from the following steps:
  1. sub if it is not nil.
  2. The current input in mplex (see WMPlex.current_input) if one exists and noinput is not set.
  3. The currently displayed object in mplex (see WMPlex.current), if not nil.
  4. mplex itself, if noself is not set.
Additionally, if cwincheck is set, the function is only called if the object selected above is of type WClientWin.

Synopsis:
mclick(buttonspec, func, area)
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. The optional argument area (a string or nil) depends on the context. For more information, see section 3.3.

Synopsis:
mdblclick(buttonspec, func, area)
Description:
Similar to mclick but for double-click. Also see section 3.3.

Synopsis:
mdrag(buttonspec, func, area)
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:
mpress(buttonspec, func, area)
Description:
Similar to mclick but for just pressing the mouse button. Also see section 3.3.

Synopsis:
obj_exists(obj)
Description:
Check that the WObj obj still exists in the C side of Ion.

Synopsis:
remove_from_hook(hookname, fn)
Description:
Unregister fn as a handler for hook hookname.

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

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

Synopsis:
winprop(list)
Description:
Define a winprop. For more information, see section 3.4.


6.9 Functions defined in querylib

Synopsis:
querylib.make_completor(completefn)
Description:
Generate a ''completor'' passable to many of the querylib.make_*_fn functions from a simple function completefn that completes an input string to a table of completion strings.

Synopsis:
querylib.make_execfile_fn(prompt, prog)
Description:
Generate a function that can be directly passed in mplex/frame/screen binding definitions to display a query to start a program with a tab-completed file as parameter. The previously inputted file's directory is used as the initial input. The parameters to this function are
Parameter Description
prompt The prompt
prog Program name or a function that returns it when called.

Synopsis:
querylib.make_execwith_fn(prompt, dflt, prog, completor)
Description:
Generate a function that can be directly passed in mplex/frame/screen binding definitions to display a query to start a program with a tab-completed parameter. The parameters to this function are
Parameter Description
prompt The prompt
dflt Default value to call prog with
prog Program name or a function that returns it when called.
completor A completor function.

Synopsis:
querylib.make_frame_fn(prompt, initfn, handler, completor)
Description:
Generate a function that can be directly passed in mplex/frame/screen binding definitions to display a query to call a function with tab-completed parameter. The parameters to this function are
Parameter Description
prompt The prompt.
initfn A function that returns initial input when called.
handler The function to be called with the mplex/frame/screen and user input as parameters when the query is finished.
completor A completor function.

Synopsis:
querylib.make_simple_fn(prompt, initfn, handler, completor)
Description:
Generate a function that can be directly passed in mplex/frame/screen binding definitions to display a query to call a function with tab-completed parameter. The parameters to this function are
Parameter Description
prompt The prompt.
initfn A function that returns initial input when called.
handler The function to be called with the user input as parameter when the query is finished.
completor A completor function.

Synopsis:
querylib.make_yesno_fn(prompt, handler)
Description:
Generate a function that can be directly passed in mplex/frame/screen binding definitions to display a query to conditionally depending on user's input call another function handler that will get the mplex/frame/screen where the query was displayed as argument.

Function:
querylib.query_attachclient
Description:
This query asks for the name of a client window and switches focus to the one entered. It uses the completion function complete_clientwin.

Function:
querylib.query_editfile
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.

Function:
querylib.query_exec
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.

Function:
querylib.query_exit
Description:
This query asks whether the user wants to have Ioncore exit. If the answer is 'y', 'Y' or 'yes', so will happen.

Function:
querylib.query_gotoclient
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 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()}.

Function:
querylib.query_man
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. To enable tab-completion you must list paths with manuals in the table query_man_path. For example,
query_man_path = {
    "/usr/local/man","/usr/man",
    "/usr/share/man", "/usr/X11R6/man",
}

Function:
querylib.query_renameframe
Description:
This function asks for a name new for the frame where the query was created.

Function:
querylib.query_renameworkspace
Description:
This function asks for a name new for the workspace on which the query resides.

Function:
querylib.query_restart
Description:
This query asks whether the user wants restart Ioncore. If the answer is 'y', 'Y' or 'yes', so will happen.

Function:
querylib.query_runfile
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.

Function:
querylib.query_workspace
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.show_aboutmsg(mplex)
Description:
Display an "About Ion" message in mplex.


6.10 Functions defined in delib

Synopsis:
de_define_style(name, list)
Description:
Define a new style for the default drawing engine (that must've been loaded with gr_select_engine.

Synopsis:
de_substyle(pattern, list)
Description:
Define a substyle for the default drawing engine. This function is to be used in constructing style definitions for de_define_style.


6.11 Functions defined in menulib

Synopsis:
defmenu(name, tab)
Description:
Define a new menu with name being the menu's name and tab being a table of menu entries.

Synopsis:
getmenu(menu_or_name)
Description:
If menu_or_name is a string, returns a menu defined with defmenu, else return menu_or_name.

Synopsis:
make_bigmenu_fn(menuname)
Description:
This function is similar to make_menu_fn but uses a possibly bigger style for the menu.

Synopsis:
make_menu_fn(menu_or_name, big)
Description:
This function can be used to create a wrapper to create an embedded-in-an-mplex menu and to call the handler for a menu entry once selected.

See also: menu_menu, make_bigmenu_fn and make_pmenu_fn.

Synopsis:
make_pmenu_fn(menu_or_name)
Description:
This function can be used to create a wrapper display a drop-down menu and to call the handler for a menu entry once selected. The resulting function should only be called from a mouse press binding.

See also: menu_pmenu, make_menu_fn.

Synopsis:
menuentry(name, fn)
Description:
Use this function to define normal menu entries.

Synopsis:
submenu(name, sub_or_name)
Description:
Use this function to define menu entries for submenus.


next up previous contents index
Next: A. The GNU General Up: Ion: Configuring and extending Previous: 5. Scripting   Contents   Index