Subsections
6. Function reference
6.1 Functions defined in ioncore
-
- Synopsis:
- ioncore.TR(s, ...)
- Description:
- gettext+string.format
-
- Synopsis:
- ioncore.bdoc(text)
- Description:
- Used to enter documentation among bindings so that other programs
can read it. Does nothing.
-
- Synopsis:
- ioncore.chdir_for(reg, dir)
- Description:
- Change default working directory for new programs started in reg.
-
- Synopsis:
- ioncore.compile_cmd(cmd, guard)
- Description:
- Compile string cmd into a bindable function. Within cmd, the
variable ''_'' (underscore) can be used to refer to the object
that was selecting for the bound action and chosen to handle it.
The variable ''_sub'' refers to a ''currently active'' sub-object
of _, or a sub-object where the action loading to the binding
being called actually occured.
The string guard maybe set to pose limits on _sub. Currently
supported guards are _sub:non-nil and _sub:WFoobar, where
WFoobar is a class.
-
- Synopsis:
- WTimer ioncore.create_timer()
- Description:
- Create a new timer.
-
- Synopsis:
- ioncore.create_ws(scr, tmpl, layout)
- Description:
- Create new workspace on screen scr. The table tmpl
may be used to override parts of the layout named with layout.
If no layout is given, "default" is used.
-
- Synopsis:
- ioncore.defbindings(context, bindings)
- Description:
- Define bindings for context context. Here binding is
a table composed of entries created with ioncore.kpress,
etc.; see Section 3.3 for details.
-
- Synopsis:
- ioncore.defctxmenu(ctx, ...)
- Description:
- Define context menu for context ctx, tab being a table
of menu entries.
-
- Synopsis:
- ioncore.deflayout(name, tab)
- Description:
- Define a new workspace layout with name name, and
attach/creation parameters given in tab. The layout
"empty" may not be defined.
-
- Synopsis:
- ioncore.defmenu(name, tab)
- Description:
- Define a new menu with name being the menu's name and tab
being a table of menu entries. If tab.append is set, the entries
are appended to previously-defined ones, if possible.
-
- Synopsis:
- ioncore.defwinprop(list)
- Description:
- Define a winprop. For more information, see section 3.5.
-
- Synopsis:
- ioncore.exec_on(reg, cmd, merr_internal)
- Description:
- Run cmd with the environment variable DISPLAY set to point to the
root window of the X screen reg is on. If cmd is prefixed
by a colon (:), the following command is executed in an xterm
(or other terminal emulator) with the help of the ion-runinxterm
script. If the command is prefixed by two colons, ion-runinxterm
will ask you to press enter after the command is finished, even if it
returns succesfully.
-
- Synopsis:
- table ioncore.read_savefile(string basename)
- Description:
- Read a savefile.
-
- 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:
- 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.write_savefile(string basename, table tab)
- Description:
- Write tab in file with basename basename in the
session directory.
-
- Synopsis:
- ioncore.find_manager(obj, t)
- Description:
- Find an object with type name t managing obj or one of
its managers.
-
- Synopsis:
- ioncore.get_dir_for(reg)
- Description:
- Get default working directory for new programs started in reg.
-
- Synopsis:
- ioncore.getbindings(maybe_context)
- Description:
- Get a table of all bindings.
-
- Synopsis:
- ioncore.getctxmenu(name)
- Description:
- Returns a context menu defined with ioncore.defctxmenu.
-
- Synopsis:
- ioncore.getlayout(name, all)
- Description:
- Get named layout (or all of the latter parameter is set,
but this is for internal use only).
-
- Synopsis:
- ioncore.getmenu(name)
- Description:
- Returns a menu defined with ioncore.defmenu.
-
- Synopsis:
- ioncore.getwinprop(cwin)
- Description:
- Find winprop table for cwin.
-
- Synopsis:
- string ioncore.aboutmsg()
- Description:
- Returns an about message (version, author, copyright notice).
-
- Synopsis:
- WRegion ioncore.activity_first()
- Description:
- Returns first region on activity list.
-
- Synopsis:
- bool ioncore.activity_i(function iterfn)
- Description:
- Iterate over activity list until iterfn returns false.
The function itself returns true if it reaches the end of list
without this happening.
-
- Synopsis:
- bool ioncore.clientwin_i(function fn)
- Description:
- Iterate over client windows until iterfn returns false.
The function itself returns true if it reaches the end of list
without this happening.
-
- Synopsis:
- WRegion ioncore.current()
- Description:
- Returns the currently focused region, if any.
-
- Synopsis:
- bool ioncore.defshortening(string rx, string rule, bool always)
- Description:
- Add a rule describing how too long titles should be shortened to fit in tabs.
The regular expression rx (POSIX, not Lua!) is used to match titles
and when rx matches, rule is attempted to use as a replacement
for title. If always is set, the rule is used even if no shortening
is necessary.
Similarly to sed's 's' command, rule may contain characters that are
inserted in the resulting string and specials as follows:
| Special |
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:
- bool ioncore.detach(WRegion reg, string how)
- Description:
- Detach or reattach reg, depending on whether how
is `set', `unset' or `toggle'. (Detaching
means making reg managed by its nearest ancestor WGroup,
framed if reg is not itself WFrame. Reattaching means
making it managed where it used to be managed, if a return-placeholder
exists.)
If reg is the `bottom' of some group, the whole group is
detached. If reg is a WWindow, it is put into a
frame.
-
- Synopsis:
- integer ioncore.exec(string cmd)
- Description:
- Run cmd with the environment variable DISPLAY set to point to the
X display the WM is running on. No specific screen is set unlike with
WRootWin.exec_on. The PID of the (shell executing the) new
process is returned.
-
- Synopsis:
- WScreen ioncore.find_screen_id(integer id)
- Description:
- Find the screen with numerical id id.
-
- Synopsis:
- bool ioncore.focushistory_i(function iterfn)
- Description:
- Iterate over focus history until iterfn returns false.
The function itself returns true if it reaches the end of list
without this happening.
-
- Synopsis:
- table ioncore.get()
- Description:
- Get ioncore basic settings. For details see ioncore.set.
-
- Synopsis:
- table ioncore.get_paths(table tab)
- Description:
- Get important directories (the fields userdir,
sessiondir, searchpath in the returned table).
-
- Synopsis:
- bool ioncore.goto_activity()
- Description:
- Go to first region on activity list.
-
- Synopsis:
- WRegion ioncore.goto_first(WRegion reg, string dirstr, table param)
- Description:
- Go to first region within reg in direction dirstr.
For information on param, see ioncore.navi_next.
Additionally this function supports the boolean nofront field,
for not bringing the object to front.
-
- Synopsis:
- WRegion ioncore.goto_next(WRegion reg, string dirstr, table param)
- Description:
- Go to region next from reg in direction dirstr.
For information on param, see ioncore.navi_next.
Additionally this function supports the boolean nofront
field, for not bringing the object to front.
-
- Synopsis:
- WScreen ioncore.goto_next_screen()
- Description:
- Switch focus to the next screen and return it.
Note that this function is asynchronous; the screen will not
actually have received the focus when this function returns.
-
- Synopsis:
- WScreen ioncore.goto_nth_screen(integer id)
- Description:
- Switch focus to the screen with id id and return it.
Note that this function is asynchronous; the screen will not
actually have received the focus when this function returns.
-
- Synopsis:
- WScreen ioncore.goto_prev_screen()
- Description:
- Switch focus to the previous screen and return it.
Note that this function is asynchronous; the screen will not
actually have received the focus when this function returns.
-
- Synopsis:
- WRegion ioncore.goto_previous()
- Description:
- Go to and return to a previously active region (if any).
Note that this function is asynchronous; the region will not
actually have received the focus when this function returns.
-
- Synopsis:
- bool ioncore.is_i18n()
- Description:
- Is Ion supporting locale-specifically multibyte-encoded strings?
-
- Synopsis:
- bool ioncore.load_module(string modname)
- Description:
- Attempt to load a C-side module.
-
- Synopsis:
- WClientWin ioncore.lookup_clientwin(string name)
- Description:
- Attempt to find a client window with name name.
-
- 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:
- WRegion ioncore.navi_first(WRegion reg, string dirstr, table param)
- Description:
- Find first region within reg in direction dirstr.
For information on param, see ioncore.navi_next.
-
- Synopsis:
- WRegion ioncore.navi_next(WRegion reg, string dirstr, table param)
- Description:
- Find region next from reg in direction dirstr
(`up', `down', `left', `right',
`next', `prev', or `any'). The table param
may contain the boolean field nowrap, instructing not to wrap
around, and the WRegions no_ascend and no_descend,
and boolean functions ascend_filter and descend_filter
on WRegion pairs (to, from), are used to decide when
to descend or ascend into another region.
-
- Synopsis:
- integer ioncore.popen_bgread(string cmd, function h, function errh)
- Description:
- Run cmd with a read pipe connected to its stdout and stderr.
When data is received through one of these pipes, h or errh
is called with that data. When the pipe is closed, the handler is called
with nil argument. The PID of the new process is returned, or
-1 on error.
-
- Synopsis:
- string ioncore.progname()
- Description:
- Returns the name of program using Ioncore.
-
- Synopsis:
- bool ioncore.region_i(function fn, string typenam)
- Description:
- Iterate over all non-client window regions with (inherited) class
typenam until iterfn returns false.
The function itself returns true if it reaches the end of list
without this happening.
-
- Synopsis:
- void ioncore.request_selection(function fn)
- Description:
- Request (string) selection. The function fn will be called
with the selection when and if it is received.
-
- Synopsis:
- void ioncore.resign()
- Description:
- Causes the window manager to simply exit without saving
state/session.
-
- Synopsis:
- void ioncore.restart()
- Description:
- Restart, saving session first.
-
- Synopsis:
- void ioncore.restart_other(string cmd)
- Description:
- Attempt to restart another window manager cmd.
-
- Synopsis:
- void ioncore.set(table tab)
- Description:
- Set ioncore basic settings. The table tab may contain the
following fields.
| Field |
Description |
| opaque_resize |
(boolean) Controls whether interactive move and
resize operations simply draw a rubberband during
the operation (false) or immediately affect the
object in question at every step (true). |
| warp |
(boolean) Should focusing operations move the
pointer to the object to be focused? |
| switchto |
(boolean) Should a managing WMPlex switch
to a newly mapped client window? |
| screen_notify |
(boolean) Should notification tooltips be displayed
for hidden workspaces with activity? |
| frame_default_index |
(string) Specifies where to add new regions
on the mutually exclusive list of a frame. One of
`last', `next', (for after current),
or `next-act'
(for after current and anything with activity right
after it). |
| dblclick_delay |
(integer) Delay between clicks of a double click. |
| kbresize_delay |
(integer) Delay in milliseconds for ending keyboard
resize mode after inactivity. |
| kbresize_t_max |
(integer) Controls keyboard resize acceleration.
See description below for details. |
| kbresize_t_min |
(integer) See below. |
| kbresize_step |
(floating point) See below. |
| kbresize_maxacc |
(floating point) See below. |
| framed_transients |
(boolean) Put transients in nested frames. |
| float_placement_method |
(string) How to place floating frames.
One of `udlr' (up-down, then left-right),
`lrud' (left-right, then up-down), or
`random'. |
| mousefocus |
(string) Mouse focus mode:
`disable' or `sloppy'. |
| unsqueeze |
(boolean) Auto-unsqueeze transients/menus/queries/etc. |
| autoraise |
(boolean) Autoraise regions in groups on goto. |
When a keyboard resize function is called, and at most kbresize_t_max
milliseconds has passed from a previous call, acceleration factor is reset
to 1.0. Otherwise, if at least kbresize_t_min milliseconds have
passed from the from previous acceleration update or reset the squere root
of the acceleration factor is incremented by kbresize_step. The
maximum acceleration factor (pixels/call modulo size hints) is given by
kbresize_maxacc. The default values are (200, 50, 30, 100).
-
- Synopsis:
- bool ioncore.set_paths(table tab)
- Description:
- Set important directories (the fields sessiondir, searchpath
of tab).
-
- Synopsis:
- void ioncore.set_selection(string p)
- Description:
- Set primary selection and cutbuffer0 to p.
-
- Synopsis:
- void ioncore.shutdown()
- Description:
- End session saving it first.
-
- Synopsis:
- void ioncore.snapshot()
- Description:
- Save session.
-
- Synopsis:
- void ioncore.tagged_clear()
- Description:
- Untag all regions.
-
- Synopsis:
- WRegion ioncore.tagged_first(bool untag)
- Description:
- Returns first tagged object, untagging it as well if untag is set.
-
- Synopsis:
- bool ioncore.tagged_i(function iterfn)
- Description:
- Iterate over tagged regions until iterfn returns false.
The function itself returns true if it reaches the end of list
without this happening.
-
- Synopsis:
- void ioncore.unsqueeze(WRegion reg, bool override)
- Description:
- Try to detach reg if it fits poorly in its
current location. This function does not do anything,
unless override is set or the unsqueeze option
of ioncore.set is set.
-
- Synopsis:
- 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.
-
- Synopsis:
- void ioncore.warn_traced(string str)
- Description:
- Similar to ioncore.warn, but also print Lua stack trace.
-
- Synopsis:
- void ioncore.x_change_property(integer win, integer atom, integer atom_type, integer format, string mode, table tab)
- Description:
- Modify a window property. The mode is one of
`replace', `prepend' or `append', and format
is either 8, 16 or 32. Also see ioncore.x_get_window_property
and the XChangeProperty(3) manual page.
-
- Synopsis:
- void ioncore.x_delete_property(integer win, integer atom)
- Description:
- Delete a window property.
-
- Synopsis:
- string ioncore.x_get_atom_name(integer atom)
- Description:
- Get the name of an atom. See XGetAtomName(3) manual page for
details.
-
- Synopsis:
- table ioncore.x_get_text_property(integer win, integer atom)
- Description:
- Get a text property for a window. The fields in the returned
table (starting from 1) are the null-separated parts of the property.
See the XGetTextProperty(3) manual page for more information.
-
- Synopsis:
- table ioncore.x_get_window_property(integer win, integer atom, integer atom_type, integer n32expected, bool more)
- Description:
- Get a property atom of type atom_type for window win.
The n32expected parameter indicates the expected number of 32bit
words, and more indicates whether all or just this amount of data
should be fetched. Each 8, 16 or 32bit element of the property, as
deciphered from atom_type is a field in the returned table.
See XGetWindowProperty(3) manual page for more information.
-
- Synopsis:
- integer ioncore.x_intern_atom(string name, bool only_if_exists)
- Description:
- Create a new atom. See XInternAtom(3) manual page for details.
-
- Synopsis:
- void ioncore.x_set_text_property(integer win, integer atom, table tab)
- Description:
- Set a text property for a window. The fields of tab starting from
1 should be the different null-separated parts of the property.
See the XSetTextProperty(3) manual page for more information.
-
- Synopsis:
- ioncore.kpress(keyspec, cmd, guard)
- Description:
- Creates a binding description table for the action of pressing a key given
by keyspec (with possible modifiers) to the function cmd.
The guard controls when the binding can be called.
For more informationp see Section 3.3.
-
- Synopsis:
- ioncore.kpress_wait(keyspec, cmd, guard)
- Description:
- This is similar to ioncore.kpress but after calling cmd,
Ioncore waits for all modifiers to be released before processing
any further actions.
For more information on bindings, see Section 3.3.
-
- Synopsis:
- bool ioncore.defer(function fn)
- Description:
- Defer execution of fn until the main loop.
-
- Synopsis:
- WHook ioncore.get_hook(string name)
- Description:
- Find named hook name.
-
- Synopsis:
- ioncore.match_winprop_dflt(prop, cwin, id)
- Description:
- The basic name-based winprop matching criteria.
-
- Synopsis:
- ioncore.mclick(buttonspec, cmd, guard)
- Description:
- Creates a binding description table for the action of clicking a mouse
button while possible modifier keys are pressed,
both given by buttonspec, to the function cmd.
For more information, see Section 3.3.
-
- Synopsis:
- ioncore.mdblclick(buttonspec, cmd, guard)
- Description:
- Similar to ioncore.mclick but for double-click.
Also see Section 3.3.
-
- Synopsis:
- ioncore.mdrag(buttonspec, cmd, guard)
- Description:
- Creates a binding description table for the action of moving the mouse
(or other pointing device) while the button given by buttonspec
is held pressed and the modifiers given by buttonspec were pressed
when the button was initially pressed.
Also see section 3.3.
-
- Synopsis:
- ioncore.menuentry(name, cmd, guard_or_opts)
- Description:
- Use this function to define normal menu entries. The string name
is the string shown in the visual representation of menu. The
parameter cmd and guard_or_opts (when string) are similar
to those of ioncore.defbindings. If guard_or_opts is
a table, it may contains the guard field, and the priority
field, for controlling positioning of entries in context menus.
(The default priority is 1 for most entries, and -1 for auto-generated
submenus.)
-
- Synopsis:
- ioncore.mpress(buttonspec, cmd, guard)
- Description:
- Similar to ioncore.mclick but for just pressing the mouse button.
Also see Section 3.3.
-
- Synopsis:
- ioncore.refresh_stylelist()
- Description:
- Refresh list of known style files.
-
- Synopsis:
- ioncore.submap(keyspec, list)
- Description:
- Returns a function that creates a submap binding description table.
When the key press action keyspec occurs, Ioncore will wait for
a further key presse and act according to the submap.
For details, see Section 3.3.
-
- Synopsis:
- ioncore.submap_enter(cmd, guard)
- Description:
- Submap enter event for bindings.
-
- Synopsis:
- ioncore.submap_wait(cmd, guard)
- Description:
- Submap modifier release event for bindings.
-
- Synopsis:
- ioncore.submenu(name, sub_or_name, options)
- Description:
- Use this function to define menu entries for submenus. The parameter
sub_or_name is either a table of menu entries or the name
of an already defined menu. The initial menu entry to highlight can be
specified by options.initial as either an integer starting from 1,
or a function that returns such a number. Another option supported is
options.noautoexpand that will cause mod_query.query_menu
to not automatically expand this submenu.
-
- Synopsis:
- ioncore.tabnum.clear()
- Description:
- Clear all tab numbers set by ioncore.tabnum.show.
-
- Synopsis:
- ioncore.tabnum.show(frame, delay)
- Description:
- Show tab numbers on frame, clearing them when submap
grab is released the next time. If delay is given, in
milliseconds, the numbers are not actually displayed until this
time has passed.
-
- Synopsis:
- ioncore.tagged_attach(reg, param)
- Description:
- Attach tagged regions to reg. The method of attach
depends on the types of attached regions and whether reg
implements attach_framed and attach. If param
is not set, the default of
{switchto=true} is used.
The function returns true if all tagged regions were
succesfully attached, and false otherwisse.
-
- Synopsis:
- table WClientWin.get_ident(WClientWin cwin)
- Description:
- Returns a table containing the properties WM_CLASS (table entries
instance and class) and WM_WINDOW_ROLE (role)
properties for cwin. If a property is not set, the corresponding
field(s) are unset in the table.
-
- Synopsis:
- void WClientWin.kill(WClientWin cwin)
- Description:
- Attempt to kill (with XKillWindow) the client that owns
the X window correspoding to cwin.
-
- Synopsis:
- void WClientWin.nudge(WClientWin cwin)
- Description:
- Attempts to fix window size problems with non-ICCCM compliant
programs.
-
- Synopsis:
- void WClientWin.quote_next(WClientWin cwin)
- Description:
- Send next key press directly to cwin.
-
- Synopsis:
- double WClientWin.xid(WClientWin cwin)
- Description:
- Return the X window id for the client window.
-
- Synopsis:
- bool WFrame.is_shaded(WFrame frame)
- Description:
- Is frame shaded?
-
- Synopsis:
- void WFrame.maximize_horiz(WFrame frame)
- Description:
- Attempt to toggle horizontal maximisation of frame.
-
- Synopsis:
- void WFrame.maximize_vert(WFrame frame)
- Description:
- Attempt to toggle vertical maximisation of frame.
-
- Synopsis:
- string WFrame.mode(WFrame frame)
- Description:
- Get frame mode.
-
- Synopsis:
- void WFrame.p_switch_tab(WFrame frame)
- Description:
- Display the region corresponding to the tab that the user pressed on.
This function should only be used by binding it to a mouse action.
-
- Synopsis:
- void WFrame.p_tabdrag(WFrame frame)
- Description:
- Start dragging the tab that the user pressed on with the pointing device.
This function should only be used by binding it to mpress or
mdrag action with area `tab'.
-
- Synopsis:
- bool WFrame.set_grattr(WFrame frame, string attr, string how)
- Description:
- Set extra drawing engine attributes for the frame.
The parameter attr is the attribute, and how is
one of `set', `unset', or `toggle'.
-
- Synopsis:
- bool WFrame.set_mode(WFrame frame, string modestr)
- Description:
- Set frame mode.
-
- Synopsis:
- bool WFrame.set_shaded(WFrame frame, string how)
- Description:
- Set shading state according to the parameter how
(`set', `unset', or `toggle').
Resulting state is returned, which may not be
what was requested.
-
- Synopsis:
- WRegion WGroup.attach(WGroup ws, WRegion reg, table param)
- Description:
- Attach and reparent existing region reg to ws.
The table param may contain the fields index and
switchto that are interpreted as for WMPlex.attach_new.
-
- Synopsis:
- WRegion WGroup.attach_new(WGroup ws, table param)
- Description:
- Create a new region to be managed by ws. At least the following
fields in param are understood:
| Field |
Description |
| type |
(string) Class of the object to be created. Mandatory. |
| name |
(string) Name of the object to be created. |
| switchto |
(boolean) Should the region be switched to? |
| level |
(integer) Stacking level; default is 1. |
| modal |
(boolean) Make object modal; ignored if level is set. |
| sizepolicy |
(string) Size policy; see Section 6.10.1. |
| bottom |
(boolean) Mark the attached region as the
``bottom'' of ws. |
In addition parameters to the region to be created are passed in this
same table.
-
- Synopsis:
- WRegion WGroup.bottom(WGroup ws)
- Description:
- Returns the `bottom' of ws.
-
- Synopsis:
- bool WGroup.is_fullscreen(WGroup grp)
- Description:
- Is reg in full screen mode?
-
- Synopsis:
- bool WGroup.managed_i(WGroup ws, function iterfn)
- Description:
- Iterate over managed regions of ws until iterfn returns
false.
The function itself returns true if it reaches the end of list
without this happening.
-
- Synopsis:
- bool WGroup.set_bottom(WGroup ws, WRegion reg)
- Description:
- Sets the `bottom' of ws. The region reg must already
be managed by ws, unless nil.
-
- Synopsis:
- bool WGroup.set_fullscreen(WGroup grp, string how)
- Description:
- Set client window reg full screen state according to the
parameter how (one of `set', `unset', or
`toggle'). Resulting state is returned, which may not be
what was requested.
-
- Synopsis:
- bool WGroupWS.attach_framed(WGroupWS ws, WRegion reg, table t)
- Description:
- Attach region reg on ws.
At least the following fields in t are supported:
| Field |
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:
- bool WHook.add(WHook hk, function efn)
- Description:
- Add efn to the list of functions to be called when the
hook hk is triggered.
-
- Synopsis:
- bool WHook.listed(WHook hk, function efn)
- Description:
- Is fn hooked to hook hk?
-
- Synopsis:
- bool WHook.remove(WHook hk, function efn)
- Description:
- Remove efn from the list of functions to be called when the
hook hk is triggered.
-
- Synopsis:
- void WInfoWin.set_text(WInfoWin p, string str, integer maxw)
- Description:
- Set contents of the info window.
-
- Synopsis:
- WRegion WMPlex.attach(WMPlex mplex, WRegion reg, table param)
- Description:
- Attach and reparent existing region reg to mplex.
The table param may contain the fields index and
switchto that are interpreted as for WMPlex.attach_new.
-
- Synopsis:
- WRegion WMPlex.attach_new(WMPlex mplex, table param)
- Description:
- Create a new region to be managed by mplex. At least the following
fields in param are understood (all but type are optional).
| Field |
Description |
| type |
(string) Class name (a string) of the object to be created. |
| name |
(string) Name of the object to be created (a string). |
| switchto |
(boolean) Should the region be switched to (boolean)? |
| unnumbered |
(boolean) Do not put on the numbered mutually
exclusive list. |
| index |
(integer) Index on this list, same as for
WMPlex.set_index. |
| level |
(integer) Stacking level. |
| modal |
(boolean) Shortcut for modal stacking level. |
| hidden |
(boolean) Attach hidden, if not prevented
by e.g. the mutually exclusive list being empty.
This option overrides switchto. |
| passive |
(boolean) Skip in certain focusing operations. |
| pseudomodal |
(boolean) The attached region is ``pseudomodal''
if the stacking level dictates it to be modal.
This means that the region may be hidden to display
regions with lesser stacking levels. |
| sizepolicy |
(string) Size policy; see Section 6.10.1. |
| geom |
(table) Geometry specification. |
In addition parameters to the region to be created are passed in this
same table.
-
- Synopsis:
- void WMPlex.dec_index(WMPlex mplex, WRegion r)
- Description:
- Move r ``left'' within objects managed by mplex on list 1.
-
- Synopsis:
- integer WMPlex.get_index(WMPlex mplex, WRegion reg)
- Description:
- Get index of reg on the mutually exclusive list of mplex.
The indices begin from zero.. If reg is not on the list,
-1 is returned.
-
- Synopsis:
- table WMPlex.get_stdisp(WMPlex mplex)
- Description:
- Get status display information. See WMPlex.get_stdisp for
information on the fields.
-
- Synopsis:
- void WMPlex.inc_index(WMPlex mplex, WRegion r)
- Description:
- Move r ``right'' within objects managed by mplex on list 1.
-
- Synopsis:
- bool WMPlex.is_hidden(WMPlex mplex, WRegion reg)
- Description:
- Is reg on within mplex and hidden?
-
- Synopsis:
- bool WMPlex.managed_i(WMPlex mplex, function iterfn)
- Description:
- Iterate over managed regions of mplex until iterfn returns
false.
The function itself returns true if it reaches the end of list
without this happening.
-
- Synopsis:
- integer WMPlex.mx_count(WMPlex mplex)
- Description:
- Returns the number of objects on the mutually exclusive list of mplex.
-
- Synopsis:
- WRegion WMPlex.mx_current(WMPlex mplex)
- Description:
- Returns the managed object currently active within the mutually exclusive
list of mplex.
-
- Synopsis:
- bool WMPlex.mx_i(WMPlex mplex, function iterfn)
- Description:
- Iterate over numbered/mutually exclusive region list of mplex
until iterfn returns false.
The function itself returns true if it reaches the end of list
without this happening.
-
- Synopsis:
- WRegion WMPlex.mx_nth(WMPlex mplex, integer n)
- Description:
- Returns the n:th object on the mutually exclusive
list of mplex.
-
- Synopsis:
- bool WMPlex.set_hidden(WMPlex mplex, WRegion reg, string how)
- Description:
- Set the visibility of the region reg on mplex
as specified with the parameter how
(one of `set', `unset', or `toggle').
The resulting state is returned.
-
- Synopsis:
- void WMPlex.set_index(WMPlex mplex, WRegion reg, integer index)
- Description:
- Set index of reg to index within the mutually exclusive
list of mplex. Special values for index are:
-
- Synopsis:
- WRegion WMPlex.set_stdisp(WMPlex mplex, table t)
- Description:
- Set/create status display for mplex. Table is a standard
description of the object to be created (as passed to e.g.
WMPlex.attach_new). In addition, the following fields are
recognised:
| Field |
Description |
| pos |
(string) The corner of the screen to place the status
display in: one of `tl', `tr', `bl'
or `br'. |
| fullsize |
(boolean) Waste all available space. |
| action |
(string) If this field is set to `keep',
pos and fullsize are changed for the existing
status display. If this field is set to `remove',
the existing status display is removed. If this
field is not set or is set to `replace', a
new status display is created and the old, if any,
removed. |
-
- Synopsis:
- void WMPlex.switch_next(WMPlex mplex)
- Description:
- Have mplex display next (wrt. currently selected) object managed
by it.
-
- Synopsis:
- void WMPlex.switch_nth(WMPlex mplex, integer n)
- Description:
- Have mplex display the n:th object managed by it.
-
- Synopsis:
- void WMPlex.switch_prev(WMPlex mplex)
- Description:
- Have mplex display previous (wrt. currently selected) object
managed by it.
-
- Synopsis:
- void WMoveresMode.cancel(WMoveresMode mode)
- Description:
- Return from move/resize cancelling changes if opaque
move/resize has not been enabled.
-
- Synopsis:
- void WMoveresMode.finish(WMoveresMode mode)
- Description:
- Return from move/resize mode and apply changes unless opaque
move/resize is enabled.
-
- Synopsis:
- table WMoveresMode.geom(WMoveresMode mode)
- Description:
- Returns current geometry.
-
- Synopsis:
- void WMoveresMode.move(WMoveresMode mode, integer horizmul, integer vertmul)
- Description:
- Move resize mode target one step:
| horizmul/vertmul |
effect |
| -1 |
Move left/up |
| 0 |
No effect |
| 1 |
Move right/down |
-
- Synopsis:
- void WMoveresMode.resize(WMoveresMode mode, integer left, integer right, integer top, integer bottom)
- Description:
- Shrink or grow resize mode target one step in each direction.
Acceptable values for the parameters left, right, top
and bottom are as follows: -1: shrink along,
0: do not change, 1: grow along corresponding border.
-
- Synopsis:
- table WMoveresMode.rqgeom(WMoveresMode mode, table g)
- Description:
- Request exact geometry in move/resize mode. For details on parameters,
see WRegion.rqgeom.
-
- Synopsis:
- WMoveresMode WRegion.begin_kbresize(WRegion reg)
- Description:
- Enter move/resize mode for reg. The bindings set with
ioncore.set_bindings for WMoveresMode are used in
this mode. Of the functions exported by the Ion C core, only
WMoveresMode.resize, WMoveresMode.move,
WMoveresMode.cancel and WMoveresMode.end are
allowed to be called while in this mode.
-
- Synopsis:
- WRegion WRegion.current(WRegion mgr)
- Description:
- Return the object, if any, that is considered ``currently active''
within the objects managed by mplex.
-
- 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:
- table WRegion.get_configuration(WRegion reg, bool clientwins)
- Description:
- Get configuration tree. If clientwins is unset, client windows
are filtered out.
-
- Synopsis:
- bool WRegion.goto(WRegion reg)
- Description:
- Attempt to display reg, save region activity status and then
warp to (or simply set focus to if warping is disabled) reg.
Note that this function is asynchronous; the region will not
actually have received the focus when this function returns.
-
- Synopsis:
- WRegion WRegion.groupleader_of(WRegion reg)
- Description:
- Returns the group of reg, if reg is its bottom,
and reg itself otherwise.
-
- Synopsis:
- bool WRegion.is_active(WRegion reg)
- Description:
- Is reg active/does it or one of it's children of focus?
-
- Synopsis:
- bool WRegion.is_activity(WRegion reg)
- Description:
- Is activity notification set on reg.
-
- Synopsis:
- bool WRegion.is_mapped(WRegion reg)
- Description:
- Is reg visible/is it and all it's ancestors mapped?
-
- Synopsis:
- bool WRegion.is_tagged(WRegion reg)
- Description:
- Is reg tagged?
-
- Synopsis:
- WRegion WRegion.manager(WRegion reg)
- Description:
- Returns the region that manages reg.
-
- Synopsis:
- string WRegion.name(WRegion reg)
- Description:
- Returns the name for reg.
-
- Synopsis:
- WWindow WRegion.parent(WRegion reg)
- Description:
- Returns the parent region of reg.
-
- Synopsis:
- WRootWin WRegion.rootwin_of(WRegion reg)
- Description:
- Returns the root window reg is on.
-
- Synopsis:
- void WRegion.rqclose(WRegion reg, bool relocate)
- Description:
- Attempt to close/destroy reg. Whether this operation works
depends on whether the particular type of region in question has
implemented the feature and, in case of client windows, whether
the client supports the WM_DELETE protocol (see also
WClientWin.kill). The region will not be destroyed when
this function returns. To find out if and when it is destroyed,
use the `deinit' notification. If relocate is not set,
and reg manages other regions, it will not be closed. Otherwise
the managed regions will be attempted to be relocated.
-
- Synopsis:
- WRegion WRegion.rqclose_propagate(WRegion reg, WRegion maybe_sub)
- Description:
- Recursively attempt to close a region or one of the regions managed by
it. If sub is set, it will be used as the managed region, otherwise
WRegion.current(reg). The object to be closed is
returned, or NULL if nothing can be closed. For further details, see
notes for WRegion.rqclose.
-
- Synopsis:
- table WRegion.rqgeom(WRegion reg, table g)
- Description:
- Attempt to resize and/or move reg. The table g is a usual
geometry specification (fields x, y, w and h),
but may contain missing fields, in which case, reg's manager may
attempt to leave that attribute unchanged.
-
- Synopsis:
- bool WRegion.rqorder(WRegion reg, string ord)
- Description:
- Request ordering. Currently supported values for ord
are `front' and `back'.
-
- Synopsis:
- WScreen WRegion.screen_of(WRegion reg)
- Description:
- Returns the screen reg is on.
-
- Synopsis:
- bool WRegion.set_activity(WRegion reg, string how)
- Description:
- Set activity flag of reg. The how parameter must be
one of `set', `unset' or `toggle'.
-
- Synopsis:
- bool WRegion.set_name(WRegion reg, string p)
- Description:
- Set the name of reg to p. If the name is already in use,
an instance number suffix `<n>' will be attempted. If p has
such a suffix, it will be modified, otherwise such a suffix will be
added. Setting p to nil will cause current name to be removed.
-
- Synopsis:
- bool WRegion.set_name_exact(WRegion reg, string p)
- Description:
- Similar to WRegion.set_name except if the name is already in use,
other instance numbers will not be attempted. The string p should
not contain a `<n>' suffix or this function will fail.
-
- Synopsis:
- bool WRegion.set_tagged(WRegion reg, string how)
- Description:
- Change tagging state of reg as defined by how
(one of `set', `unset', or `toggle').
The resulting state is returned.
-
- Synopsis:
- table WRegion.size_hints(WRegion reg)
- Description:
- Returns size hints for reg. The returned table always contains the
fields min_?, base_? and sometimes the fields max_?,
base_? and inc_?, where ?=w, h.
-
- Synopsis:
- WScreen WRootWin.current_scr(WRootWin rootwin)
- Description:
- Returns previously active screen on root window rootwin.
-
- 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.
-
- Synopsis:
- bool WTimer.is_set(WTimer timer)
- Description:
- Is timer set?
-
- Synopsis:
- void WTimer.reset(WTimer timer)
- Description:
- Reset timer.
-
- Synopsis:
- void WTimer.set(WTimer timer, integer msecs, function fn)
- Description:
- Set timer to call fn in msecs milliseconds.
-
- Synopsis:
- void WWindow.p_move(WWindow wwin)
- Description:
- Start moving wwin with the mouse or other pointing device.
This function should only be used by binding it to mpress or
mdrag action.
-
- Synopsis:
- void WWindow.p_resize(WWindow wwin)
- Description:
- Start resizing wwin with the mouse or other pointing device.
This function should only be used by binding it to mpress or
mdrag action.
-
- Synopsis:
- double WWindow.xid(WWindow wwin)
- Description:
- Return the X window id for wwin.
-
- Synopsis:
- export(lib, ...)
- Description:
- Export a list of functions from lib into global namespace.
-
- Synopsis:
- void gr.read_config()
- Description:
- Read drawing engine configuration file look.lua.
-
- Synopsis:
- void gr.refresh()
- Description:
- Refresh objects' brushes to update them to use newly loaded style.
-
- Synopsis:
- bool gr.select_engine(string engine)
- Description:
- Future requests for ``brushes'' are to be forwarded to the drawing engine
engine. If no engine of such name is known, a module with that name
is attempted to be loaded. This function is only intended to be called from
colour scheme etc. configuration files and can not be used to change the
look of existing objects; for that use gr.read_config.
-
- Synopsis:
- string.shell_safe(str)
- Description:
- Make str shell-safe.
-
- Synopsis:
- table.append(t1, t2)
- Description:
- Add entries that do not exist in t1 from t2 to t1.
-
- Synopsis:
- table.copy(t, deep)
- Description:
- Make copy of table. If deep is unset, shallow one-level
copy is made, otherwise a deep copy is made.
-
- Synopsis:
- table.icat(t1, t2)
- Description:
- Insert all positive integer entries from t2 into t1.
-
- Synopsis:
- table.join(t1, t2)
- Description:
- Create a table containing all entries from t1 and those from
t2 that are missing from t1.
-
- Synopsis:
- table.map(f, t)
- Description:
- Map all entries of t by f.
6.2 Functions defined in mod_tiling
-
- Synopsis:
- table mod_tiling.get()
- Description:
- Get parameters. For details see mod_tiling.set.
-
- Synopsis:
- bool mod_tiling.mkbottom(WRegion reg)
- Description:
- Create a new WTiling 'bottom' for the group of reg,
consisting of reg.
-
- Synopsis:
- void mod_tiling.set(table tab)
- Description:
- Set parameters. Currently only raise_delay (in milliseconds)
is supported.
-
- Synopsis:
- bool mod_tiling.untile(WTiling tiling)
- Description:
- If tiling is managed by some group, float the frames in
the tiling in that group, and dispose of tiling.
-
- Synopsis:
- table WSplit.geom(WSplit split)
- Description:
- Returns the area of workspace used by the regions under split.
-
- Synopsis:
- WSplitInner WSplit.parent(WSplit split)
- Description:
- Return parent split for split.
-
- Synopsis:
- table WSplit.rqgeom(WSplit node, table g)
- Description:
- Attempt to resize and/or move the split tree starting at node.
Behaviour and the g parameter are as for WRegion.rqgeom
operating on node (if it were a WRegion).
-
- Synopsis:
- void WSplit.transpose(WSplit node)
- Description:
- Transpose contents of node.
-
- Synopsis:
- WSplit WSplitInner.current(WSplitInner node)
- Description:
- Returns the most previously active child node of split.
-
- Synopsis:
- WRegion WSplitRegion.reg(WSplitRegion node)
- Description:
- Returns the region contained in node.
-
- Synopsis:
- WSplit WSplitSplit.br(WSplitSplit split)
- Description:
- Returns the bottom or right child node of split depending
on the direction of the split.
-
- Synopsis:
- string WSplitSplit.dir(WSplitSplit split)
- Description:
- Returns the direction of split; either `vertical' or
`horizontal'.
-
- Synopsis:
- void WSplitSplit.flip(WSplitSplit split)
- Description:
- Flip contents of split.
-
- Synopsis:
- WSplit WSplitSplit.tl(WSplitSplit split)
- Description:
- Returns the top or left child node of split depending
on the direction of the split.
-
- Synopsis:
- bool WTiling.flip_at(WTiling ws, WRegion reg)
- Description:
- Flip ws at reg or root if nil.
-
- Synopsis:
- bool WTiling.transpose_at(WTiling ws, WRegion reg)
- Description:
- Transpose ws at reg or root if nil.
-
- Synopsis:
- WRegion WTiling.farthest(WTiling ws, string dirstr, bool any)
- Description:
- Return the most previously active region on ws with no
other regions next to it in direction dirstr
(`left', `right', `up', or `down').
If any is not set, the status display is not considered.
-
- Synopsis:
- bool WTiling.managed_i(WTiling ws, function iterfn)
- Description:
- Iterate over managed regions of ws until iterfn returns
false.
The function itself returns true if it reaches the end of list
without this happening.
-
- Synopsis:
- WRegion WTiling.nextto(WTiling ws, WRegion reg, string dirstr, bool any)
- Description:
- Return the most previously active region next to reg in
direction dirstr (`left', `right', `up',
or `down'). The region reg
must be managed by ws. If any is not set, the status display
is not considered.
-
- Synopsis:
- WSplitRegion WTiling.node_of(WTiling ws, WRegion reg)
- Description:
- For region reg managed by ws return the WSplit
a leaf of which reg is.
-
- Synopsis:
- bool WTiling.set_floating_at(WTiling ws, WRegion reg, string how, string dirstr)
- Description:
- Toggle floating of the sides of a split containin reg as indicated
by the parameters how (`set', `unset', or
`toggle') and dirstr (`left', `right',
`up', or `down'). The new status is returned
(and false also on error).
-
- Synopsis:
- WSplitSplit WTiling.set_floating(WTiling ws, WSplitSplit split, string how)
- Description:
- Toggle floating of a split's sides at split as indicated by the
parameter how (`set', `unset', or `toggle').
A split of the appropriate is returned, if there was a change.
-
- Synopsis:
- WFrame WTiling.split(WTiling ws, WSplit node, string dirstr)
- Description:
- Create a new frame on ws `above', `below'
`left' of, or `right' of node as indicated
by dirstr. If dirstr is prefixed with
`floating:' a floating split is created.
-
- Synopsis:
- WFrame WTiling.split_at(WTiling ws, WFrame frame, string dirstr, bool attach_current)
- Description:
- Split frame creating a new frame to direction dirstr
(one of `left', `right', `top' or
`bottom') of frame.
If attach_current is set, the region currently displayed in
frame, if any, is moved to thenew frame.
If dirstr is prefixed with `floating:', a floating
split is created.
-
- Synopsis:
- WFrame WTiling.split_top(WTiling ws, string dirstr)
- Description:
- Same as WTiling.split at the root of the split tree.
-
- Synopsis:
- WSplit WTiling.split_tree(WTiling ws)
- Description:
- Returns the root of the split tree.
-
- Synopsis:
- void WTiling.unsplit_at(WTiling ws, WRegion reg)
- Description:
- Try to relocate regions managed by reg to another frame
and, if possible, destroy it.
6.3 Functions defined in mod_query
-
- Synopsis:
- mod_query.defcmd(cmd, fn)
- Description:
- Define a command override for the query_exec query.
-
- Synopsis:
- mod_query.message(mplex, str)
- Description:
- Display a message in mplex.
-
- Synopsis:
- table mod_query.get()
- Description:
- Get module configuration. For more information see
mod_query.set.
-
- 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:
- bool mod_query.history_push(string str)
- Description:
- Push an entry into line editor history.
-
- Synopsis:
- integer mod_query.history_search(string s, integer from, bool bwd, bool exact)
- Description:
- Try to find matching history entry. Returns -1 if none was
found. The parameter from specifies where to start
searching from, and bwd causes backward search from
that point. If exact is not set, s only required
to be a prefix of the match.
-
- Synopsis:
- table mod_query.history_table()
- Description:
- Return table of history entries.
-
- Synopsis:
- void mod_query.set(table tab)
- Description:
- Set module configuration. The following are supported:
| Field |
Description |
| autoshowcompl |
(boolean) Is auto-show-completions enabled?
(default: true). |
| autoshowcompl_delay |
(integer) auto-show-completions delay
in milliseconds (default: 250). |
| caseicompl |
(boolean) Turn some completions case-insensitive
(default: false). |
-
- Synopsis:
- mod_query.popen_completions(cp, cmd, fn, reshnd)
- Description:
- This function can be used to read completions from an external source.
The parameter cp is the completion proxy to be used,
and the string cmd the shell command to be executed. To its stdout,
the command should on the first line write the common_beg
parameter of WComplProxy.set_completions (which fn maybe used
to override) and a single actual completion on each of the successive lines.
The function reshnd may be used to override a result table
building routine.
-
- Synopsis:
- mod_query.query(mplex, prompt, initvalue, handler, completor,
context)
- Description:
- Low-level query routine. mplex is the WMPlex to display
the query in, prompt the prompt string, and initvalue
the initial contents of the query box. handler is a function
that receives (mplex, result string) as parameter when the
query has been succesfully completed, completor the completor
routine which receives a (cp, str, point) as parameters.
The parameter str is the string to be completed and point
cursor's location within it. Completions should be eventually,
possibly asynchronously, set with WComplProxy.set_completions
on cp.
-
- Synopsis:
- mod_query.query_attachclient(mplex)
- Description:
- This query asks for the name of a client window and attaches
it to the frame the query was opened in. It uses the completion
function ioncore.complete_clientwin.
-
- Synopsis:
- mod_query.query_editfile(mplex, script, prompt)
- Description:
- Asks for a file to be edited. This script uses
run-mailcap -mode=edit by default, but you may provide an
alternative script to use. The default prompt is "Edit file:" (translated).
-
- Synopsis:
- mod_query.query_exec(mplex)
- Description:
- This function asks for a command to execute with /bin/sh.
If the command is prefixed with a colon (':'), the command will
be run in an XTerm (or other terminal emulator) using the script
ion-runinxterm. Two colons ('::') will ask you to press
enter after the command has finished.
-
- Synopsis:
- mod_query.query_gotoclient(mplex)
- Description:
- This query asks for the name of a client window and switches
focus to the one entered. It uses the completion function
ioncore.complete_clientwin.
-
- Synopsis:
- mod_query.query_lua(mplex)
- Description:
- This query asks for Lua code to execute. It sets the variable '_'
in the local environment of the string to point to the mplex where the
query was created. It also sets the table arg in the local
environment to {_, _:current()}.
-
- Synopsis:
- mod_query.query_man(mplex, prog)
- Description:
- This query asks for a manual page to display. By default it runs the
man command in an xterm using ion-runinxterm,
but it is possible to pass another program as the prog argument.
-
- Synopsis:
- mod_query.query_menu(mplex, sub, themenu, prompt)
- Description:
- This query can be used to create a query of a defined menu.
-
- Synopsis:
- mod_query.query_renameframe(frame)
- Description:
- This function asks for a name new for the frame where the query
was created.
-
- Synopsis:
- mod_query.query_renameworkspace(mplex, ws)
- Description:
- This function asks for a name new for the workspace ws,
or the one on which mplex resides, if it is not set.
If mplex is not set, one is looked for.
-
- Synopsis:
- mod_query.query_restart(mplex)
- Description:
- This query asks whether the user wants restart Ioncore.
If the answer is 'y', 'Y' or 'yes', so will happen.
-
- Synopsis:
- mod_query.query_runfile(mplex, script, prompt)
- Description:
- Asks for a file to be viewed. This script uses
run-mailcap -action=view by default, but you may provide an
alternative script to use. The default prompt is "View file:" (translated).
-
- Synopsis:
- mod_query.query_shutdown(mplex)
- Description:
- This query asks whether the user wants to exit Ion (no session manager)
or close the session (running under a session manager that supports such
requests). If the answer is 'y', 'Y' or 'yes', so will happen.
-
- Synopsis:
- mod_query.query_ssh(mplex, ssh)
- Description:
- This query asks for a host to connect to with SSH.
Hosts to tab-complete are read from ~/.ssh/known_hosts.
-
- Synopsis:
- mod_query.query_workspace(mplex)
- Description:
- This query asks for the name of a workspace. If a workspace
(an object inheriting WGroupWS) with such a name exists,
it will be switched to. Otherwise a new workspace with the
entered name will be created and the user will be queried for
the type of the workspace.
-
- Synopsis:
- mod_query.query_yesno(mplex, prompt, handler)
- Description:
- This function query will display a query with prompt prompt in
mplex and if the user answers affirmately, call handler
with mplex as parameter.
-
- Synopsis:
- mod_query.show_about_ion(mplex)
- Description:
- Display an "About Ion" message in mplex.
-
- Synopsis:
- mod_query.show_tree(mplex, reg, max_depth)
- Description:
- Show information about a region tree
-
- Synopsis:
- mod_query.warn(mplex, str)
- Description:
- Display an error message box in the multiplexer mplex.
-
- Synopsis:
- bool WComplProxy.set_completions(WComplProxy proxy, table compls)
- Description:
- Set completion list of the WEdln that proxy refers to to
compls, if it is still waiting for this completion run. The
numerical indexes of compls list the found completions. If the
entry common_beg (common_end) exists, it gives an extra
common prefix (suffix) of all found completions.
-
- Synopsis:
- void WEdln.back(WEdln wedln)
- Description:
- Move backward one character.
-
- Synopsis:
- void WEdln.backspace(WEdln wedln)
- Description:
- Delete previous character.
-
- Synopsis:
- void WEdln.bkill_word(WEdln wedln)
- Description:
- Starting from the previous characters, delete possible whitespace and
preceding alphanumeric characters until previous non-alphanumeric character.
-
- Synopsis:
- void WEdln.bol(WEdln wedln)
- Description:
- Go to the beginning of line.
-
- Synopsis:
- void WEdln.bskip_word(WEdln wedln)
- Description:
- Go to to beginning of current sequence of alphanumeric characters
followed by whitespace.
-
- Synopsis:
- void WEdln.clear_mark(WEdln wedln)
- Description:
- Clear mark.
-
- Synopsis:
- void WEdln.complete(WEdln wedln, string cycle, string mode)
- Description:
- Call completion handler with the text between the beginning of line and
current cursor position, or select next/previous completion from list if in
auto-show-completions mode and cycle is set to `next' or
`prev', respectively.
The mode may be `history' or `normal'. If it is
not set, the previous mode is used. Normally next entry is not cycled to
despite the setting of cycle if mode switch occurs. To override
this, use `next-always' and `prev-always' for cycle.
-
- Synopsis:
- string WEdln.contents(WEdln wedln)
- Description:
- Get line editor contents.
-
- Synopsis:
- string WEdln.context(WEdln wedln)
- Description:
- Get history context for wedln.
-
- Synopsis:
- void WEdln.copy(WEdln wedln)
- Description:
- Copy text between mark and current cursor position to clipboard.
-
- Synopsis:
- void WEdln.cut(WEdln wedln)
- Description:
- Copy text between mark and current cursor position to clipboard
and then delete that sequence.
-
- Synopsis:
- void WEdln.delete(WEdln wedln)
- Description:
- Delete current character.
-
- Synopsis:
- void WEdln.eol(WEdln wedln)
- Description:
- Go to the end of line.
-
- Synopsis:
- void WEdln.finish(WEdln wedln)
- Description:
- Close wedln and call any handlers.
-
- Synopsis:
- void WEdln.forward(WEdln wedln)
- Description:
- Move forward one character.
-
- Synopsis:
- void WEdln.history_next(WEdln wedln, bool match)
- Description:
- Replace line editor contents with next entry in history if one exists.
If match is true, the initial part of the history entry
must match the current line from beginning to point.
-
- Synopsis:
- void WEdln.history_prev(WEdln wedln, bool match)
- Description:
- Replace line editor contents with previous in history if one exists.
If match is true, the initial part of the history entry
must match the current line from beginning to point.
-
- Synopsis:
- void WEdln.insstr(WEdln wedln, string str)
- Description:
- Input str in wedln at current editing point.
-
- Synopsis:
- bool WEdln.is_histcompl(WEdln wedln)
- Description:
- Get history completion mode.
-
- Synopsis:
- void WEdln.kill_line(WEdln wedln)
- Description:
- Delete the whole line.
-
- Synopsis:
- void WEdln.kill_to_bol(WEdln wedln)
- Description:
- Delete all characters from previous to beginning of line.
-
- Synopsis:
- void WEdln.kill_to_eol(WEdln wedln)
- Description:
- Delete all characters from current to end of line.
-
- Synopsis:
- void WEdln.kill_word(WEdln wedln)
- Description:
- Starting from the current point, delete possible whitespace and
following alphanumeric characters until next non-alphanumeric character.
-
- Synopsis:
- integer WEdln.mark(WEdln wedln)
- Description:
- Get current mark (start of selection) for wedln.
Return value of -1 indicates that there is no mark, and
0 is the beginning of the line.
-
- Synopsis:
- bool WEdln.next_completion(WEdln wedln)
- Description:
- Select next completion.
-
- Synopsis:
- void WEdln.paste(WEdln wedln)
- Description:
- Request selection from application holding such.
Note that this function is asynchronous; the selection will not
actually be inserted before Ion receives it. This will be no
earlier than Ion return to its main loop.
-
- Synopsis:
- integer WEdln.point(WEdln wedln)
- Description:
- Get current editing point.
Beginning of the edited line is point 0.
-
- Synopsis:
- bool WEdln.prev_completion(WEdln wedln)
- Description:
- Select previous completion.
-
- Synopsis:
- void WEdln.set_context(WEdln wedln, string context)
- Description:
- Set history context for wedln.
-
- Synopsis:
- void WEdln.set_mark(WEdln wedln)
- Description:
- Set mark to current cursor position.
-
- Synopsis:
- void WEdln.skip_word(WEdln wedln)
- Description:
- Go to to end of current sequence of whitespace followed by alphanumeric
characters..
-
- Synopsis:
- void WEdln.transpose_chars(WEdln wedln)
- Description:
- Transpose characters.
-
- Synopsis:
- void WEdln.transpose_words(WEdln wedln)
- Description:
- Transpose words.
-
- Synopsis:
- void WInput.cancel(WInput input)
- Description:
- Close input not calling any possible finish handlers.
-
- Synopsis:
- void WInput.scrolldown(WInput input)
- Description:
- Scroll input input text contents down.
-
- Synopsis:
- void WInput.scrollup(WInput input)
- Description:
- Scroll input input text contents up.
6.4 Functions defined in mod_menu
-
- Synopsis:
- mod_menu.grabmenu(mplex, sub, menu_or_name, param)
- Description:
- This function is similar to mod_menu.menu, but input
is grabbed and the key used to active the menu can be used to
cycle through menu entries.
-
- Synopsis:
- mod_menu.menu(mplex, sub, menu_or_name, param)
- Description:
- Display a menu in the lower-left corner of mplex.
The variable menu_or_name is either the name of a menu
defined with mod_menu.defmenu or directly a table similar
to ones passesd to this function. When this function is
called from a binding handler, sub should be set to
the second argument of to the binding handler (_sub)
so that the menu handler will get the same parameters as the
binding handler. Extra options can be passed in the table
param. The initial entry can be specified as the field
initial as an integer starting from 1. Menus can be made
to use a bigger style by setting the field big to true.
-
- Synopsis:
- table mod_menu.get()
- Description:
- Get module basic settings. For details, see mod_menu.set.
-
- Synopsis:
- void mod_menu.set(table tab)
- Description:
- Set module basic settings. The parameter table may contain the
following fields:
| Field |
Description |
| scroll_amount |
Number of pixels to scroll at a time
pointer-controlled menus when one extends
beyond a border of the screen and the pointer
touches that border. |
| scroll_delay |
Time between such scrolling events in
milliseconds. |
-
- Synopsis:
- mod_menu.pmenu(win, sub, menu_or_name)
- Description:
- This function displays a drop-down menu and should only
be called from a mouse press handler. The parameters are
similar to those of mod_menu.menu.
-
- Synopsis:
- void WMenu.cancel(WMenu menu)
- Description:
- Close menu not calling any possible finish handlers.
-
- Synopsis:
- void WMenu.finish(WMenu menu)
- Description:
- If selected entry is a submenu, display that.
Otherwise destroy the menu and call handler for selected entry.
-
- Synopsis:
- void WMenu.select_next(WMenu menu)
- Description:
- Select next entry in menu.
-
- Synopsis:
- void WMenu.select_nth(WMenu menu, integer n)
- Description:
- Select n:th entry in menu.
-
- Synopsis:
- void WMenu.select_prev(WMenu menu)
- Description:
- Select previous entry in menu.
-
- Synopsis:
- void WMenu.typeahead_clear(WMenu menu)
- Description:
- Clear typeahead buffer.
6.5 Functions defined in mod_dock
-
- Synopsis:
- void mod_dock.set_floating_shown_on(WMPlex mplex, string how)
- Description:
- Toggle floating docks on mplex.
-
- Synopsis:
- bool WDock.attach(WDock dock, WRegion reg)
- Description:
- Attach reg to dock.
-
- Synopsis:
- table WDock.get(WDock dock)
- Description:
- Get dock's configuration table. See WDock.set for a
description of the table.
-
- Synopsis:
- void WDock.resize(WDock dock)
- Description:
- Resizes and refreshes dock.
-
- Synopsis:
- void WDock.set(WDock dock, table conftab)
- Description:
- Configure dock. conftab is a table of key/value pairs:
| Key |
Values |
Description |
| name |
string |
Name of dock |
| pos |
string in
 |
Dock position.
Can only be used in floating mode. |
| grow |
up/down/left/right |
Growth direction where new dockapps are added. Also
sets orientation for dock when working as WMPlex status
display (see WMPlex.set_stdisp). |
| is_auto |
bool |
Should dock automatically manage new dockapps? |
Any parameters not explicitly set in conftab will be left unchanged.
6.6 Functions defined in mod_sp
-
- Synopsis:
- bool mod_sp.set_shown(WFrame sp, string how)
- Description:
- Toggle displayed status of sp.
The parameter how is one of
`set', `unset', or `toggle'.
The resulting status is returned.
-
- Synopsis:
- bool mod_sp.set_shown_on(WMPlex mplex, string how)
- Description:
- Change displayed status of some scratchpad on mplex if one is
found. The parameter how is one of
`set', `unset', or `toggle'.
The resulting status is returned.
6.7 Functions defined in mod_statusbar
-
- Synopsis:
- mod_statusbar.create(param)
- Description:
- Create a statusbar. The possible parameters in the
table param are:
| Variable |
Type |
Description |
| template |
string |
The template; see
Section 3.6. |
| pos |
string |
Position: `tl', `tr',
`bl' or `br'
(for the obvious combinations of
top/left/bottom/right). |
| screen |
integer |
Screen number to create the statusbar on. |
| fullsize |
boolean |
If set, the statusbar will waste
space instead of adapting to layout. |
| systray |
boolaen |
Swallow (KDE protocol) systray icons. |
-
- Synopsis:
- mod_statusbar.inform(name, value)
- Description:
- Inform of a value.
-
- Synopsis:
- mod_statusbar.launch_statusd(cfg)
- Description:
- Load modules and launch ion-statusd with configuration
table cfg. The options for each ion-statusd monitor
script should be contained in the corresponding sub-table of cfg.
-
- Synopsis:
- table mod_statusbar.statusbars()
- Description:
- Returns a list of all statusbars.
-
- Synopsis:
- mod_statusbar.update(update_templates)
- Description:
- Update statusbar contents. To be called after series
of mod_statusbar.inform calls.
-
- Synopsis:
- table WStatusBar.get_template_table(WStatusBar sb)
- Description:
- Get statusbar template as table.
-
- Synopsis:
- bool WStatusBar.is_systray(WStatusBar sb)
- Description:
- Is sb used as a systray?
-
- Synopsis:
- bool WStatusBar.set_systray(WStatusBar sb, string how)
- Description:
- Enable or disable use of sb as systray.
The parameter how can be one of
`set', `unset', or `toggle'.
Resulting state is returned.
-
- Synopsis:
- void WStatusBar.set_template(WStatusBar sb, string tmpl)
- Description:
- Set statusbar template.
-
- Synopsis:
- void WStatusBar.set_template_table(WStatusBar sb, table t)
- Description:
- Set statusbar template as table.
-
- Synopsis:
- void WStatusBar.update(WStatusBar sb, table t)
- Description:
- Set statusbar template.
6.8 Functions defined in de
-
- Synopsis:
- bool de.defstyle(string name, table tab)
- Description:
- Define a style.
-
- Synopsis:
- bool de.defstyle_rootwin(WRootWin rootwin, string name, table tab)
- Description:
- Define a style for the root window rootwin.
-
- Synopsis:
- void de.reset()
- Description:
- Clear all styles from drawing engine memory.
-
- Synopsis:
- table de.substyle(string pattern, table tab)
- Description:
- Define a substyle.
6.9 Hooks
-
- Hook name:
- clientwin_do_manage_alt
- Parameters:
- (WClientWin, table)
- Description:
- Called when we want to manage a new client window.
The table argument contains the following fields:
| Field |
Type |
Description |
| switchto |
bool |
Do we want to switch to the client window. |
| jumpto |
bool |
Do we want to jump to the client window. |
| userpos |
bool |
Geometry set by user. |
| dockapp |
bool |
Client window is a dock-app. |
| maprq |
bool |
Map request (and not initialisation scan). |
| gravity |
number |
Window gravity. |
| geom |
table |
Requested geometry; x, y, w, h. |
| tfor |
WClientWin |
Transient for window. |
This hook is not called in protected mode and can be used for
arbitrary placement policies (deciding in which workspace a new
WClientWin should go). In this case, you can call
reg:attach(cwin)
where reg is the region where the window should go, and
cwin is the first argument of the function added to the
hook.
-
- Hook name:
- clientwin_mapped_hook
- Parameters:
- WClientWin
- Description:
- Called when we have started to manage a client window.
-
- Hook name:
- clientwin_property_change_hook
- Parameters:
- (WClientWin, integer)
- Description:
- Called when the property identified by the parameter atom id
(integer) has changed on a client window.
-
- Hook name:
- clientwin_unmapped_hook
- Parameters:
- number
- Description:
- Called when we no longer manage a client window. The parameter
is the X ID of the window; see WClientWin.xid.
-
- Hook name:
- frame_managed_changed_hook
- Parameters:
- table
- Description:
- Called when there are changes in the objects managed by a frame
or their order. The table parameter has the following fields:
| Field |
Type |
Description |
| reg |
WFrame |
The frame in question |
| mode |
string |
`switchonly', `reorder',
`add' or `remove' |
| sw |
bool |
Switch occurred |
| sub |
WRegion |
The managed region (primarily) affected |
-
- Hook name:
- ioncore_sigchld_hook
- Parameters:
- integer
- Description:
- Called when a child process has exited. The parameter
is the PID of the process.
-
- Hook name:
- ioncore_deinit_hook
- Parameters:
- ()
- Description:
- Called when Ion is deinitialising and about to quit.
-
- Hook name:
- ioncore_post_layout_setup_hook
- Parameters:
- ()
- Description:
- Called when Ion has done all initialisation and is almost ready to
enter the main-loop, except no windows are yet being managed.
-
- Hook name:
- ioncore_snapshot_hook
- Parameters:
- ()
- Description:
- Called to signal scripts and modules to save their state (if any).
-
- Hook name:
- ioncore_submap_ungrab_hook
- Parameters:
- ()
- Description:
- This hook is used to signal whenever Ion leaves the submap grab mode.
-
- Hook name:
- tiling_placement_alt
- Parameters:
- table
- Description:
- Called when a client window is about to be managed by a WTiling
to allow for alternative placement policies. The table has the
following fields:
| Field |
Type |
Description |
| tiling |
WTiling |
The tiling |
| reg |
WRegion |
The region (always a WClientWin at
the moment) to be placed |
| mp |
table |
This table contains the same fields as
the parameter of clientwin_do_manage_alt |
| res_frame |
WFrame |
A successful handler should
return the target frame here. |
This hook is just for placing within a given workspace after the
workspace has been decided by the default workspace selection
policy. It is called in protected mode. For arbitrary placement
policies, clientwin_do_manage_alt should be used; it
isn't called in protected mode,
-
- Hook name:
- region_do_warp_alt
- Parameters:
- WRegion
- Description:
- This alt-hook exist to allow for alternative pointer warping
implementations.
-
- Hook name:
- screen_managed_changed_hook
- Parameters:
- table
- Description:
- Called when there are changes in the objects managed by a screen
or their order. The table parameter is similar to that of
frame_managed_changed_hook.
-
- Hook name:
- region_notify_hook
- Parameters:
- (WRegion, string)
- Description:
- Signalled when something (minor) has changed in relation to
the first parameter region. The string argument gives the
change:
| String |
Description |
| deinit |
The region is about to be deinitialised. |
| activated |
The region has received focus. |
| inactivated |
The region has lost focus. |
| activity |
There's been activity in the region itself. |
| sub_activity |
There's been activity in some sub-region. |
| name |
The name of the region has changed. |
| unset_manager |
The region no longer has a manager. |
| set_manager |
The region now has a manager. |
| tag |
Tagging state has changed. |
| pseudoactivated |
The region has become pseudo-active
(see below). |
| pseudoinactivated |
The region is no longer pseudo-active. |
A region is pseudo-active, when a) it is itself not active (does
not not have the focus, and may not even have a window that could
have it), but b) some region managed by it is active.
6.10 Miscellaneous
6.10.1 Size policies
Some functions accept a sizepolicy parameter. The possible
values are:
`default',
`full',
`full_bounds',
`free',
`free_glue',
`northwest',
`north',
`northeast',
`west',
`center',
`east',
`southwest',
`south',
`southeast',
`stretch_top',
`stretch_bottom',
`stretch_left',
`stretch_right',
`free_glue_northwest',
`free_glue_north',
`free_glue_northeast',
`free_glue_west',
`free_glue_center',
`free_glue_east',
`free_glue_southwest',
`free_glue_south', and
`free_glue_southeast'.
The ``free'' policies allow the managed
object to be moved around, whereas the other versions do not.
The ``glue'' policies glue the object to some border, while allowing
it to be moved away from it by user action, but not automatically.
The ``stretch'' policies stretch the object along the given border,
while the coordinate-based policies simply place the object along
that border.
