Up: Notion homepage
Configuring and extending Notion with Lua
Copyright © 2010–2011 The Notion Team.
Copyright © 2003–2009 Tuomo Valkonen.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.
The latest version of this document can be found at https://notionwm.net. Updates are welcome, preferably in the form of patches against the LATEX sources which can be found in the git repository at git://github.com/raboof/notion-doc (https://github.com/raboof/notion-doc)
This document is an “advanced user” manual for the X11 window manager Notion. It is an attempt at documenting things that go into Notion's configuration files, how to configure Notion by simple modifications to these files and how to write more complex extensions in Lua, the lightweight configuration and scripting language used by Notion.
Readers unfamiliar with Lua might first want to first glance at some Lua documentation at
although this should not be strictly necessary for basic modifications of configuration files for anyone with at least some familiarity with programming languages.
Back in this document, first in chapter ![[*]](crossref.png)
some key
concepts and relations are explained. These include the module system,
and Notion's object (or “region”) and class hierarchies. While it may
not be necessary to study the latter for basic copy-paste modifications
of configuration files – for that you should not really need this
manual either – it is, however, essential to for more extensive
customisation, due to the semi-object-oriented nature of most of
Notion's scripting interface. Knowing the different object types also
helps dealing with the different binding “contexts” (see
Section ) that to some extent mirror these classes.
The new user, fed up with the default key bindings and eager to
just quickly configure Notion to his liking, may therefore just want
to skip to Chapter , and attempt to work from therefore.
That chapter provides the very basic Notion configuration know-how
is provided: all the different configuration files and their locations
are explained, instructions are given to allow the reader to
configure bindings and so-called “winprops”, and the statusbar
templates are also explained.
Next, Chapter explains the notion of drawing engines
and graphical styles and how to write new looks for Notion. More advanced
aspects of Notion's scripting interface are documented in Chapter
.
Finally, most of the functions provided by Notion's scripting interface
are listed and documented in the Function reference in Chapter
. At the end of the document an alphabetical
listing of all these functions may be found.
The purpose of this chapter to explain some of key concepts and
relations you need to understand before reading the following
chapters. These include modules explained in section
and the Notion class and object hierarchies, section .
Notion has been designed so that the 'notion' executable only implements some basic services on top of which very different kinds of window managers could be build by loading the appropriate 'modules'. On modern system these modules are simply dynamically loaded .so libraries. On more primitive systems, or if you want to squeeze total size of the executable and libraries, the modules can optionally be statically linked to the main binary, but must nevertheless be loaded with the dopath function. Modules may also include Lua code.
Currently Notion provides the following modules:
So-called drawing engines are also implemented as a modules,
but they are not discussed here; see chapter .
The stock configuration for the notion executable loads all of the modules mentioned above except mod_dock. The stock configuration for the pwm3 executable (which differs from the notion executable in a few configuration details) loads another set of modules.
While Notion does not have a truly object-oriented design2.1, things that appear on the computer screen are, however, quite naturally expressed as such “objects”. Therefore Notion implements a rather primitive OO system for these screen objects and some other things.
It is essential for the module writer to learn this object system, but also people who write their own binding configuration files necessarily come into contact with the class and object hierarchies – you need to know which binding setup routines apply where, and what functions can be used as handlers in which bindings. It is the purpose of this section to attempt to explain these hierarchies. If you do not wish the read the full section, at least read the summary at the end of it, so that you understand the very basic relations.
For simplicity we consider only the essential-for-basic-configuration
Notioncore, mod_tiling and mod_query classes.
See Appendix for the full class hierarchy visible
to Lua side.
One of the most important principles of object-oriented design methodology is inheritance; roughly how classes (objects are instances of classes) extend on others' features. Inheritance gives rise to class hierarchy. In the case of single-inheritance this hierarchy can be expressed as a tree where the class at the root is inherited by all others below it and so on. The tree below lists out the Notion class hierarchy and below we explain what features of Notion the classes implement.
Obj
|-->WRegion
| |-->WClientWin
| |-->WWindow
| | |-->WRootWin
| | |-->WMPlex
| | | |-->WFrame
| | | `-->WScreen
| | `-->WInput (mod_query)
| | |-->WEdln (mod_query)
| | `-->WMessage (mod_query)
| |-->WGroup
| | |-->WGroupWS
| | `-->WGroupCW
| `-->WTiling (mod_tiling)
`-->WSplit (mod_tiling)
Classes implemented by the mod_tiling module:
Classes implemented by the mod_query module:
There are also some other “proxy” classes that do not refer to objects on the screen. The only important one of these for basic configuration is WMoveresMode that is used for binding callbacks in the move and resize mode.
Even though it often indicates a design mistake, sometimes it can be useful to have run-time access to the types of objects.
For example, to check wether a given object is of type WMPlex, the following C code can be used:
if(obj_is((Obj*)cwin, &CLASSDESCR(WMPlex)))
....
Its lua counterpart is:
if(obj_is(cwin, "WMPlex"))
....
While there's also an 'obj_cast' method available, C structs can be freely cast to their 'superclass' using a regular C cast, for example:
bool input_fitrep(WInput *input, WWindow *par, const WFitParams *fp)
{
if(par!=NULL && !region_same_rootwin((WRegion*)input, (WRegion*)par))
return FALSE;
...
To get the object type as a string, for example for diagnostic logging, you can use OBJ_TYPESTR:
#include <libtu/objp.h>
...
warn(TR("Unable to reparent this %s."), OBJ_TYPESTR(reg));
.
WRootWins
|-->WGroupWSs
|-->WTilings
|-->WClientWins in full screen mode
`-->WFrames
|-->WGroupCWs
|-->WClientWins
|-->WFrames for transients
`-->a possible WEdln or WMessage
WRegions have very little control over their children as a parent.
The manager WRegion has much more control over its
managed WRegions. Managers, for example, handle resize requests,
focusing and displaying of the managed regions. Indeed the manager—managed
relationship gives a better picture of the logical ordering of objects on
the screen. Again, there are generally few limits, but the most common
hierarchy is given in Figure . Note that sometimes
the parent and manager are the same object and not all regions may have
a manager, but all non-screen regions have a parent—a screen if not
anything else.
WRootWins
|-->WGroupCWs for full screen WClientWins
| |-->WClientWins
| `-->WFrames for transients (dialogs)
| `--> WClientWin
|-->WGroupWSs for workspaces
| |-->WTiling
| | |-->WFrames
| | | `-->WGroupCWs (with contents as above)
| | `-->possibly a WStatusBar or WDock
| |-->WFrames for floating content
| |-->possibly a WEdln, WMessage or WMenu
| `-->possibly a WStatusBar or WDock (if no tiling)
`-->WFrames for sticky stuff, such as the scratchpad
Note that a workspace can manage another workspace. This can be achieved with the WGroup.attach_new function, and allows you to nest workspaces as deep as you want.
In the presense of Xinerama there may be WScreen objects at the top of the manager–managed tree instead of WRootWin.
In the standard setup, keeping queries, messages and menus out of consideration:
This chapter should help your configure Notion to your liking. As you probably already know, Notion uses Lua as a configuration and extension language. If you're new to it, you might first want to read some Lua documentation as already suggested and pointed to in the Introduction before continuing with this chapter.
Section is an overview of the multiple configuration
files Notion uses and as a perhaps more understandable introduction to the
general layout of the configuration files, a walk-through of the main
configuration file cfg_notion.lua is provided in section
.
How keys and mouse action are bound to functions is described in detail
in and in section winprops are
explained. Finally, the statusbar is explained in .
For a reference on exported functions, see section .
Notion stores its stock configuration files in /usr/local/etc/notion/ unless you, the OS package maintainer or whoever installed the package on the system has modified the variables PREFIX or ETCDIR in system.mk before compiling Notion. In the first case you probably know where to find the files and in the other case the system administrator or the OS package maintainer should have provided documentation to point to the correct location. If these instructions are no help in locating the correct directory, the command locate cfg_notion.lua might help provided updatedb has been run recently.
User configuration files go in /.notion/. Notion always searches the user configuration file directory before the stock configuration file directory for files. Therefore, if you want to change some setting, it is advised against that you modify the stock configuration files in-place as subsequent installs of Notion will restore the stock configuration files. Instead you should always make a copy of the stock file in /.notion/ and modify this file. For sake of maintainability of your customised configuration, it is recommended against copying all of the files there. Only copy those files you actually need to modify. Most simple customisations, such as changes in a few bindings, are best done entirely within cfg_notion.lua.
All the configuration files are named cfg_*.lua with the “*” part varying. The configuration file for each module mod_modname is cfg_modname.lua, with modname varying by the module in question. Configuration files can also be compiled into .lc files, and these are attempted by the configuration file search routines before .lua files.
The following table summarises these and other configuration files:
| File | Description | ||||||||||||||
| cfg_notion.lua | The main configuration file | ||||||||||||||
| cfg_notioncore.lua | Configuration file for Notion's core library.
Most of the bindings and menus are configured here. Bindings that are
specific to some module are configured in the module's configuration
file. For details, see section . |
||||||||||||||
| cfg_kludges.lua | Settings to get some applications behave more nicely have been
collected here. See section . |
||||||||||||||
| cfg_layouts.lua | Some workspace layouts are defined here. | ||||||||||||||
| cfg_tiling.lua cfg_query.lua cfg_menu.lua cfg_dock.lua cfg_statusbar.lua ... | Configuration files for different modules. |
Additionally, there's the file look.lua that configures the
drawing engine, but it is covered in chapter .
As already mentioned cfg_notion.lua is Notion's main configuration
file. Some basic 'feel' settings are usually configured there and
the necessary modules and other configuration files configuring some
more specific aspects of Notion are loaded there. In this section we
take a walk through the stock cfg_notion.lua.
Notice that most of the settings are commented-out (-- is a
line comment in Lua) in the actual file, as they're the defaults
nevertheless.
The first thing done in the file, is to set
META="Mod1+" ALTMETA=""These settings cause most of Notion's key bindings to use Mod1 as the modifier key. If ALTMETA is set, it is used as modifier for the keys that don't normally use a modifier. Note that these two are Lua variables used in the configuration files only, and not Notion settings. For details on modifiers and key binding setup in general, see section
.
Next we do some basic feel configuration:
ioncore.set{
dblclick_delay=250,
kbresize_delay=1500,
}
These two will set the delay between button presses in a double click, and the timeout to quit resize mode in milliseconds.
ioncore.set{
opaque_resize=true,
warp=true
}
The first of these two settings enables opaque resize mode: in move/resize move frames and other objects mirror you actions immediately. If opaque resize is disabled, a XOR rubber band is shown during the mode instead. This will, unfortunately, cause Notion to also grab the X server and has some side effects.
There are some other options as well; see the documentation for ioncore.set for details.
As a next step, in the actual cfg_notion.lua file, we load cfg_defaults.lua. However, it is merely a convenience file for doing exactly what we will going through below, and what is commented out in the actual file. If you do not want to load what cfg_defaults.lua loads, just comment out the corresponding line, and uncomment the lines for the files that you want:
--dopath("cfg_defaults")
dopath("cfg_notioncore")
dopath("cfg_kludges")
dopath("cfg_layouts")
Most bindings and menus are defined in cfg_ioncore.lua.
Details on making such definitions follow in sections
and , respectively.
some kludges or “winprops” to make some applications behave better
under Notion are collected in cfg_kludges.lua; see section
for details. In addition to these, this file
lists quite a few statements of the form
ioncore.defshortening("[^:]+: (.*)(<[0-9]+>)", "$1$2$|$1$<...$2")
These are used to configure how Notion attempts to shorten window titles
when they do not fit in a Tab. The first argument is a POSIX regular
expression that is used to match against the title and the next is
a rule to construct a new title of a match occurs. This particular
rule is used to shorten e.g. 'Foo: barbaz<3>' to 'barba...<3>'; for
details see the function reference entry for ioncore.defshortening.
Finally, cfg_layouts.lua defines some workspace layouts, available
through the F9 workspace creation query.
To actually be able to do something besides display windows in full screen mode, we must next load some modules:
dopath("mod_query")
dopath("mod_menu")
dopath("mod_tiling")
dopath("mod_statusbar")
--dopath("mod_dock")
dopath("mod_sp")
In the stock configuration file setup, most key and mouse bindings are set from the file cfg_notioncore.lua while module-specific bindings are set from the modules' main configuration files (cfg_modname.lua). This, however, does not have to be so as long as the module has been loaded prior to defining any module-specific bindings.
Bindings are defined by calling the function
defbindings with the “context” of the
bindings and the a table of new bindings to make. The context is simply
string indicating one of the classes of regions (or modes such as
WMoveresMode) introduced in section , and fully
listed in appendix , although not all define
a binding map. For example, the following skeleton would be used to
define new bindings for all frames:
defbindings("WFrame", {
-- List of bindings to make goes here.
})
There has been some confusion among users about the need to define the “context” for each binding, so let me try to explain this design decision here. The thing is that if there was a just a simple 'bind this key to this action' method without knowledge of the context, some limitations would have to be made on the available actions and writing custom handlers would be more complicated. In addition one may want to bind the same function to different key for different types of objects. Indeed, the workspace and frame tab switching functions are the same both classes being based on WMPlex, and in the stock configuration the switch to n:th workspaces is bound to Mod1+n while the switch to n:th tab is bound to the sequence Mod1+k n.
Currently known contexts include: `WScreen', `WMPlex', `WMPlex.toplevel', `WFrame', `WFrame.toplevel', `WFrame.floating', `WFrame.tiled', `WFrame.transient', `WMoveresMode', `WGroup', `WGroupCW', `WGroupWS', `WClientWin', `WTiling', and `WStatusBar'. Most of these should be self-explanatory, corresponding to objects of class with the same name. The ones with `.toplevel' suffix refer to screens and “toplevel” frames, i.e. frames that are not used for transient windows. Likewise `.transient' refers to frames in transient mode, and `.tiled' and `.floating' to frames in, respectively, tiled and floating modes.
The following subsections describe how to construct elements of the binding table. Note that defbindings adds the the newly defined bindings to the previous bindings of the context, overriding duplicates. To unbind an event, set the handler parameter to nil for each of the functions to be described in the following subsections.
Also note that when multiple objects want to handle a binding, the
innermost (when the root window is considered the outermost) active object
in the parent–child hierarchy (see Figure ) of objects
gets to handle the action.
Unlike in Ion2, in Notion binding handlers are not normally passed as “anonymous functions”, although this is still possible. The preferred method now is to pass the code of the handler as a string. Two following special variables are available in this code.
| Variable | Description |
| _ (underscore) | Reference to the object on which the binding was triggered. The object is of the same class as the the context of the defbindings call defining the binding. |
| _sub | Usually, the currently active managed object of the object referred to by _, but sometimes (e.g. mouse actions on tabs of frames) something else relevant to the action triggering the binding. |
| _chld | Object corresponding to the currently active child window of the object referred to by _. This should seldom be needed. |
For example, supposing _ (underscore) is a WFrame, the following handler should move the active window to the right, if possible:
"_:inc_index(_sub)"
To suppress error messages, each binding handler may also be accompanied by a “guard” expression that blocks the handler from being called when the guard condition is not met. Currently the following guard expressions are supported (for both _sub and _chld):
| Guard | Description |
| `_sub:non-nil' | The _sub parameter must be set. |
| `_sub:SomeClass' | The _sub parameter must be member of class SomeClass. |
The descriptions of the individual bindings in the binding table argument to defbindings should be constructed with the following functions.
Key presses:
The actions that most of these functions correspond to should be clear and as explained in the reference, kpress_wait is simply kpress with a flag set instructing Notioncore wait for all modifiers to be released before processing any further actions. This is to stop one from accidentally calling e.g. WRegion.rqclose multiple times in a row. The submap function is used to define submaps or “prefix maps”. The second argument to this function is table listing the key press actions (kpress) in the submap.
The parameters keyspec and buttonspec are explained below in detail. The parameter handler is the handler for the binding, and the optional parameter guard its guard. These should normally be strings as explained above.
For example, to just bind the key Mod1+1 to switch to the first workspace and Mod1+Right to the next workspace, you would make the following call
defbindings("WScreen", {
kpress("Mod1+Right", "_:switch_next()"),
kpress("Mod1+1", "_:switch_nth(1)"),
})
Note that _:switch_nth(1) is the same as calling WMPlex.switch_next(_, 1) as WScreen inherits WMPlex and this is where the function is actually defined.
Similarly to the above example, to bind the key sequence Mod1+k n switch to the next managed object within a frame, and Mod1+k 1 to the first, you would issue the following call:
defbindings("WFrame", {
submap("Mod1+K", {
kpress("Right", "_:switch_next()"),
kpress("1", "_:switch_nth(1)"),
}),
})
As seen above, the functions that create key binding specifications require a keyspec argument. This argument should be a string containing the name of a key as listed in the X header file keysymdef.h3.1 without the XK_ prefix. Most of the key names are quite intuitive while some are not. For example, the Enter key on the main part of the keyboard has the less common name Return while the one the numpad is called KP_Enter.
The keyspec string may optionally have multiple “modifier” names followed by a plus sign (+) as a prefix. X defines the following modifiers:
Shift, Control, Mod1 to Mod5, AnyModifier and Lock.
X allows binding all of these modifiers to almost any key and while this list of modifiers does not explicitly list keys such as Alt that are common on modern keyboards, such keys are bound to one of the ModN. On systems running XFree86 Alt is usually Mod1. On Suns Mod1 is the diamond key and Alt something else. One of the “flying window” keys on so called Windows-keyboards is probably mapped to Mod3 if you have such a key. Use the program xmodmap to find out what exactly is bound where.
Notion defaults to AnyModifier in submaps. This can sometimes lead to unwanted effects when the same key is used with and without explicitly specified modifiers in nested regions. For this reason, Notion recognises NoModifier as a special modifier that can be used to reset this default.
Notion ignores the Lock modifier and any ModN ( N = 1...5) bound to NumLock or ScrollLock by default because such3.2 locking keys may otherwise cause confusion.
Button specifications are similar to key definitions but now instead of specifying modifiers and a key, you specify modifiers and one of the button names Button1 to Button5. Additionally the specification may end with an optional area name following an @-sign. Only frames currently support areas, and the supported values in this case are `border', `tab', `empty_tab', `client' and nil (for the whole frame).
For example, the following code binds dragging a tab with the first button pressed to initiate tab drag&drop handling:
defbindings("WFrame", {
mdrag("Button1@tab", "_:p_tabdrag()"),
})
The default binding configuration contains references to the variables
META and ALTMETA instead of directly using the default
values of `Mod1+' and `' (nothing). As explained in
section , the definitions of these variables
appear in cfg_notion.lua. This way you can easily change the the
modifiers used by all bindings in the default configuration without
changing the whole binding configuration. Quite a few people prefer
to use the Windows keys as modifiers because many applications already
use Alt. Nevertheless, Mod1 is the default as a key bound
to it is available virtually everywhere.
Caps Lock is rarely used for its original purpose. For this reason, you might want to put it to different use, and bind it to some window management feature. However, if you would simply bind Caps_Lock to some functionality, each time you would access it it would switch case.
You can use the X Keyboard Extension to disable the 'Lock' feature of Caps Lock, without disabling or swapping the key wholesale. To this end, create a /usr/share/X11/xkb/symbols/misc file with the following contents:
partial modifier_keys
xkb_symbols "capsoff" {
key <CAPS> {
type[Group1] = "ONE_LEVEL",
symbols[Group1] = [ Caps_Lock ],
actions[Group1] = [ NoAction() ]
};
};
Then load it with:
$ setxkbmap -symbols 'pc+us+misc(capsoff)'
To make this change persistent, put it in your startup script.
In the stock configuration file setup, menus are defined in the file cfg_menus.lua as previously mentioned. The mod_menu module must be loaded for one to be able to define menus, and this is done with the function defmenu provided by it.
Here's an example of the definition of a rather simple menu with a submenu:
defmenu("exitmenu", {
menuentry("Restart", "ioncore.restart()"),
menuentry("Exit", "ioncore.shutdown()"),
})
defmenu("mainmenu", {
menuentry("Lock screen", "ioncore.exec('xlock')"),
menuentry("Help", "mod_query.query_man(_)"),
submenu("Exit", "exitmenu"),
})
The menuentry function is used to create an entry in the menu with a title and an entry handler to be called when the menu entry is activated. The parameters to the handler are similar to those of binding handlers, and usually the same as those of the binding that opened the menu.
The submenu function is used to insert a submenu at that point in the menu. (One could as well just pass a table with the menu entries, but it is not encouraged.)
The menu module predefines the following special menus. These can be used just like the menus defined as above.
| Menu name | Description |
| `windowlist' | List of all client windows. Activating an entry jumps to that window. |
| `workspacelist' | List of all workspaces. Activating an entry jumps to that workspaces. |
| `focuslist' | List of client windows with recent activity in them, followed by previously focused client windows. |
| `focuslist_' | List of previously focused client windows. |
| `stylemenu' | List of available look_*.lua style files. Activating an entry loads that style and ask to save the selection. |
| `ctxmenu' | Context menu for given object. |
The “ctxmenu” is a special menu that is assembled from a defined context menu for the object for which the menu was opened for, but also includes the context menus for the manager objects as submenus.
Context menus for a given region class are defined with the defctxmenu function. This is other ways similar to defmenu, but the first argument instead being the name of the menu, the name of the region class to define context menu for. For example, here's part of the stock WFrame context menu definition:
defctxmenu("WFrame", {
menuentry("Close", "WRegion.rqclose_propagate(_, _sub)"),
menuentry("Kill", "WClientWin.kill(_sub)", "_sub:WClientWin"),
})
Some of the same “modes” as were available for some bindings may also be used: `WFrame.tiled', `WFrame.floating', and `WFrame.transient'.
The following functions may be used to display menus from binding handlers (and elsewhere):
| Function | Description |
| mod_menu.menu | Keyboard (or mouse) operated menus that open in the bottom-left corner of a screen or frame. |
| mod_menu.pmenu | Mouse-operated drop-down menus. This function can only be called from a mouse press or drag handler. |
| mod_menu.grabmenu | A special version of mod_menu.menu that grabs the keyboard and is scrolled with a given key until all modifiers have been released, after which the selected entry is activated. |
Each of these functions takes three arguments, which when called from a binding handler, should be the parameters to the handler, and the name of the menu. For example, the following snippet of of code binds the both ways to open a context menu for a frame:
defbindings("WFrame", {
kpress(MOD1.."M", "mod_menu.menu(_, _sub, 'ctxmenu')"),
mpress("Button3", "mod_menu.pmenu(_, _sub, 'ctxmenu')"),
})
The so-called “winprops” can be used to change how specific windows are handled and to set up some kludges to deal with badly behaving applications. They are defined by calling the function defwinprop with a table containing the properties to set and the necessary information to identify a window. The currently supported winprops are listed below, and the subsequent subsections explain the usual method of identifying windows, and how to obtain this information.
These properties can be used to tell Notion how to treat the matched windows:
Additionally, the winprops max_size, min_size, aspect, resizeinc, and ignore_max_size, ignore_min_size, ignore_aspect, ignore_resizeinc, may be used to override application-supplied size hints. The four first ones are tables with the fields w and h, indicating the width and height size hints in pixels, and the latter ignore winprop is a boolean.
Finally, the boolean userpos option may be used to override the USPosition flag of the size hints. Normally, when this flag is set, Notion tries to respect the supplied window position more than when it is not set. Obviously, this makes sense only for floating windows.
The primary identification information supported is the class, role and instance of the window.
Secondary filters are the name, is_transient and is_dockapp fields, or a custom matching algorithm.
Notion first filters the winprops based on the primary identification fields. Of those winprops that match the primary identification fields, the most recently defined winprop that also matches the secondary filters is used.
The primary identification fields are strings, and must exactly match the corresponding information obtained from the window's properties.
Notion looks for a winprop in the order listed by the following table. An 'E' indicates that the field must be set in the winprop and it must match the window's corresponding property exactly. An asterisk '*' indicates that a winprop where the field is not specified (or is itself an asterisk in case of the first three fields) is tried.
| class | role | instance |
| E | E | E |
| E | E | * |
| E | * | E |
| E | * | * |
| &vellip#vdots; | &vellip#vdots; | etc. |
The name field is a Lua-style regular expression matched against the window's title. The is_transient field is a boolean that can be used to include or exclude transients only, while the is_dockapp field is set by Notion for the dock windows of Window Maker dockapp protocol dockapps. Usually this is the only information available for these icon windows.
If a custom matching algorithm is used, the secondary filters are ignored.
A custom matching algorithm can be specified by simple adding a lua function named match to the winprop table. This function will be passed 3 parameters: the winprop itself, the client window against which the winprop must be matched, and the identification information of this client window.
The identification information of the client window is a table containing the class, role, instance, is_transient and is_dockapp fields of the window.
The 'Window info' context menu entry (Mod1+M or Button3 on a tab) can be used to list the identification information required to set winprops for a window and all the transient windows managed within it.
Another way to get the identification information is to use xprop. Simply run To get class and instance, simply run xprop WM_CLASS and click on the particular window of interest. The class is the latter of the strings while the instance is the former. To get the role – few windows have this property – use the command xprop WM_ROLE. This method, however, will not work on transients.
So-called “transient windows” are usually short-lived dialogs (although some programs abuse this property) that have a parent window that they are “transient for”. On tiled workspaces Notion displays these windows simultaneously with the parent window at the bottom of the same frame. Unfortunately xprop is stupid and can't cope with this situation, returning the parent window's properties when the transient is clicked on. For this reason you'll have to do a little extra work to get the properties for that window.3.3
Finally, it should be mentioned that too many authors these days “forget” to set this vital identification to anything meaningful: everything except name is the same for all of the program's windows, for example. Some other programs only set this information after the window has been mapped, i.e. the window manager has been told to start managing it, which is obviously too late. Gtk applications in particular are often guilty on both counts.
The following is absolutely necessary for Acrobat reader:
defwinprop{
class = "AcroRead",
instance = "documentShell",
acrobatic = true,
}
The following winprop should place xterm started with command-line parameter -name sysmon and running a system monitoring program in a particular frame:
defwinprop{
class = "XTerm",
instance = "sysmon",
target = "sysmonframe",
}
For this example to work, we have to somehow create a frame named `sysmonframe'. One way to do this is to make the following call in the Mod1+F3 Lua code query:
mod_query.query_renameframe(_)
Recall that _ points to the multiplexer (frame or screen) in which the query was opened. Running this code should open a new query prefilled with the current name of the frame. In our example we would change the name to `sysmonframe', but we could just as well have used the default name formed from the frame's class name and an instance number.
Most window managers have some kind of 'dock' or statusbar/panel to give a quick overview of running processes and system status. Notion is no different - actually we have several options.
When a part of the screen is reserved for this purpose, in Notion this is called a “status display” or “stdisp”. You can have one stdisp per Screen - it is independent of the current workspace or tiling.
Notion has 2 kinds of stdisp's: if you want to use one or more existing panel/dock applications, you can use mod_dock with the “embedded” mode. Alternatively, you can use the built-in mod_statusbar. Since a Screen can only hold one stdisp, you can have either - not both.
Notion 4+ loads mod_dock by default via “cfg_defaults.lua“; previous versions loaded mod_statusbar. To switch, simply adjust this line to load the other module instead.
Generally, if you want to use some panel application like the xfce4-panel, fbpanel or the gnome-panel, use an embedded dock. When used in this way, it is common to add only one panel to the dock and have it span the entire width of the screen. However, the dock does support adding multiple applications to it, so if you prefer WindowMaker-style dockapps, mod_dock (either embedded or floating) is also the way to go.
Given the high quality of 3rd-party panels, mod_statusbar is mostly a legacy part of Notion.
The mod_statusbar module provides a statusbar that adapts to layouts of tilings, using only the minimal space needed.
The statusbar is configured in cfg_statusbar.lua. Typically,
the configuration consists of two steps: creating a statusbar with
mod_statusbar.create, and then launching the separate
ion-statusd status daemon process with
mod_statusbar.launch_statusd. This latter phase is done
automatically, if it was not done by the configuration file, but
the configuration file may pass extra parameters to ion-statusd
monitors. (See Section for more information on
writing ion-statusd monitors.)
A typical cfg_statusbar.lua configuration might look as follows:
-- Create a statusbar
mod_statusbar.create{
screen = 0, -- First screen,
pos = 'bl', -- bottom left corner
systray = true, -- Swallow systray windows
-- The template
template = "[ %date || load:% %>load || mail:% %>mail_new/%>mail_total ]"
.. " %filler%systray",
}
-- Launch ion-statusd.
mod_statusbar.launch_statusd{
-- Date meter
date={
-- ISO-8601 date format with additional abbreviated day name
date_format='%a %Y-%m-%d %H:%M',
},
}
The template specifies what is shown on the statusbar; for information on the other options to mod_statusbar.create, see the reference. Strings of the form `%spec' tokens specially interpreter by the statusbar; the rest appears verbatim. The spec typically consists of the name of the value/meter to display (beginning with a latin alphabet), but may be preceded by an alignment specifier and a number specifying the minimum width. The alignment specifiers are: `>' for right, `<' for left, and `|' for centring. Additionally, space following `%' (that is, the string `% '), adds “stretchable space” at that point. The special string `%filler' may be used to flush the rest of the template to the right end of the statusbar.
The stretchable space works as follows: mod_statusbar remembers the widest string (in terms of graphical presentation) that it has seen for each meter, unless the width has been otherwise constrained. If there is stretchable space in the template, it tries to make the meter always take this much space, by stretching any space found in the direction indicated by the alignment specifier: the opposite direction for left or right alignment, and both for centring.
The special `%systray' and `%systray_*' (`*' varying) monitors indicate where to place system tray windows. There may be multiple of these. KDE-protocol system tray icons are placed in `%systray' automatically, unless disabled with the systray option. Otherwise the statusbar winprop may be used to place any window in any particular `%systray_*'.
The part before the first underscore of each monitor name, describes the script/plugin/module that provides the meter, and any configuration should be passed in the a corresponding sub-table mod_statusbar.launch_statusd. Notion comes with date, load and mail (for plain old mbox) ion-statusd monitor scripts. More may be obtained from the scripts repository [1]. These included scripts provide the following monitors and their options
Options: date_format: The date format in as seen above, in the usual strftime format. formats: table of formats for additional date monitors, the key being the name of the monitor (without the `date_' prefix).
Monitors: `date' and other user-specified ones with the `date_' prefix.
Options: update_interval: Update interval in milliseconds (default 10s). important_threshold: Threshold above which the load is marked as important (default 1.5), so that the drawing engine may be suitably hinted. critical_threshold: Threshold above which the load is marked as critical (default 4.0).
Monitors: `load' (for all three values), `load_1min', `load_5min' and `load_15min'.
Options: update_interval: Update interval in milliseconds
(default 1min). mbox: mbox-format mailbox location
(default $MAIL).
files: list of additional mailboxes, the key giving the
name of the monitor.
Monitors: `mail_new', `mail_unread', `mail_total', and corresponding `mail_*_new', `mail_*_unread', and `mail_*_total' for the additional mailboxes (`*' varying).
The default location of the style is `look.lua'. To select a different predefined look, select one of the `look_*.lua' styles from `etc' and copy it to ` /.notion/look.lua'. This will override the default look on the next Notion restart, and can be a starting point for further more detailed customization.
Notion's drawing routines are abstracted into so-called drawing engine modules that can, again depending on the system, be dynamically loaded as needed. The drawing engine modules provide “brushes” that objects can use to draw some high-level primitives such as borders and text boxes (in addition to simple text and rectangle drawing) on their windows and configure e.g. the shape and background of the window. While the drawing engines therefore do not directly implement looks for each possible object (that would hardly be maintainable), different brush styles can be used to give a distinctive look to different objects and engines could interpret some styles as special cases. Style specifications are strings of the form
element1-element2-...-elementn
An example of such a style specification is `tab-frame';
see the table in subsection for more styles.
When an object asks for a brush of certain style, the selected drawing engine will attempt to find the closest match to this specification. The styles/brushes defined by the drawing engines may have asterisks (`*') as some of the elements indicating a match to anything. Exact matches are preferred to asterisk matches and longer matches to shorter. For example, let a brush for style `foo-bar-baz' be queried, then the following brushes are in order of preference:
foo-bar-baz foo-*-baz foo-bar *
Some of the drawing primitives allow extra attributes to be specified, also in the form
attr1-attr2-...-attrnThese extra attributes are called substyles and allow, for example, the state of the object to be indicated by different colour sets while keeping the interface at an abstract level and the drawing engine completely ignorant of the semantics – only the writer of the drawing engine configuration file has to know them. However the drawing engine can again interpret known substyles as special cases and the default engine indeed does so with frame tab tag and drag states.)
| Style name | Description |
| `frame' | Style for frames. Substyle attributes: `active'/`inactive' (mutually exclusive), and `quasiactive'. A frame is “quasiactive” when an active region has a back-link to it, such as a detached window. |
| `frame-tiled' | A more specific style for tiled frames. Substyle attributes as for `frame'. |
| `frame-tiled-alt' | An alternative style for tiled frames. Often used to disable the tab-bar. |
| `frame-floating' | A more specific style for floating frames. |
| `frame-transient' | A more specific style for frames containing transient windows. |
| Style name | Description |
| `tab' | Style for frames' tabs and menu entries. Substyle attributes: `active'/`inactive' and `selected'/`unselected' |
| `tab-frame' | A more specific style for frames' tabs. Additional substyle attributes include those of the `frame' style, as well as tab-specific `tagged'/`not_tagged', `dragged'/`not_dragged', and `activity'/`no_activity'. |
| `tab-frame-tiled', | |
| `tab-frame-tiled-alt', | |
| `tab-frame-floating', | |
| `tab-frame-transient' | More specific styles for frames in the different modes. |
| `tab-menuentry' | A more specific style for entries in WMenus. Additional substyle attributes include `submenu' and occasionally also `activity' is used. |
| `tab-menuentry-bigmenu' | An alternate style for entries in WMenus. |
| `tab-info' | Extra information tab (displayed e.g. for tagged workspaces). |
| Style name | Description |
| `input' | A style for WInputs. |
| `input-edln' | A more specific style for WEdlns. Substyle attributes: `selection' for selected text and `cursor' for the cursor indicating current editing point. |
| `input-message' | A more specific style for WMessages. |
| `input-menu' | A more specific style for WMenus. |
| `input-menu-bigmenu' | An alternate style for WMenus. |
| `moveres_display' | The box displaying position/size when moving or resizing frames. |
| `actnotify' | Actification notification box. |
| `stdisp' | Any status display. |
| `stdisp-dock' | The dock. |
| `stdisp-statusbar' | The statusbar. Substyles include: the name of any monitor/meter (such as `date'), and the supplied hint. Typical hints are: `normal', `important', and `critical'. |
Drawing engine style files are usually named look_foo.lua where foo is the name of the style. The file that Notion loads on startup or when gr.read_config is called, however, is look.lua and should usually be symlinked to or a copy of of some look_foo.lua.
The first thing to do in a style file is to choose the drawing engine, possibly loading the module as well. This is done with the following chunk of code.
if not gr.select_engine("de") then
return
end
The gr.select_engine function sees if the engine given as argument is registered (the default drawing engine is simply called “de”). If the engine could not be found, it tries to load a module of the same name. If the engine still is not registered, gr.select_engine returns `false' and in this case we also exit the style setup script. If the engine was found, gr.select_engine sees that further requests for brushes are forwarded to that engine and returns `true'.
Before defining new styles it may be a good idea to clear old styles from memory so if the old configuration defines more specific styles than the new, the old styles don't override those specified by the new configuration. That can be done by calling
de.reset()
After this the new styles can be defined with de.defstyle as explained in the next subsection. Finally, after the styles have been defined we must ask objects on the screen to look up new brushes to reflect the changes in configuration. This is done with
gr.refresh()
Styles for the default drawing engine are defined with the function de.defstyle. It has two arguments the first being a style specification as explained in previous sections and the second a table whose fields describe the style:
de.defstyle("some-style", {
attribute = value,
...
})
The supported attributes are described in tables below. The different border elements and styles referred to there are explained in the following sketch of different border styles and elements:
Elevated: Inlaid: Ridge: Groove: hhhhhhhhhhhs ............ hhhhhhhhhhhs sssssssssssh h..........s .sssssssssh. h..........s s..........h h. .s .s h. h.sssssssh.s s.hhhhhhhs.h h. .s .s h. h.s h.s s.h s.h h. .s .s h. h.shhhhhhh.s s.hsssssss.h h..........s .shhhhhhhhh. h..........s s..........h hsssssssssss ............ hsssssssssss shhhhhhhhhhh h = highlight, s = shadow, . = padding
Each of these fields a string of the form that can be passed to XAllocNamedColor. Valid strings are e.g. hexadecimal RGB specifications of the form #RRGGBB and colour names as specified in /usr/X11R6/lib/X11/rgb.txt (exact path varying).
| Field | Description |
| highlight_colour | Colour for the “highlight” part of a border. |
| shadow_colour | Colour for the “shadow” part of a border. |
| foreground_colour | Colour for the normal drawing operations, e.g. text. |
| background_colour | Window background colour (unless transparency is enabled) and background colour boxes. |
| padding_colour | Colour for the “padding” part of a border border. Set to background_colour if unset. |
All other fields below except border_style are non-negative integers indicating a number of pixels.
| Field | Description |
| border_style | A string indicating the style of border; one of `elevated'/`inlaid'/`ridge'/`groove' as seen in the above sketch. |
| border_sides | A string indicating which sides of the border to draw: `all'/`tb'/`lr' for all, top and bottom, and left and right. To control between left/right and top/bottom, use the pixel options below. |
| highlight_pixels | Width of the highlight part of the border in pixels. |
| shadow_pixels | Width of the shadow part of the border in pixels. |
| padding_pixels | Width of the padding part of the border in pixels. |
| spacing | Space to be left between all kinds of boxes. |
| Field | Description |
| font | Font to be used in text-drawing operations; standard X font name. |
| text_align | How text is to be aligned in text boxes/tabs; one of the strings `left'/`right'/`center'. |
| Field | Description |
| transparent_background | Should windows' that use this style background be transparent? true/false. |
| based_on | The name of a previously defined style that this style should be based on. |
As discussed in previous sections, styles may have substyles to e.g. indicate different states of the object being drawn. The “de” engine limits what can be configured in substyles to the set of colours in the first table above, but also specifically interprets for the main style `tab-frame' the substyles `*-*-tagged' and `*-*-*-dragged' by, respectively, drawing a right angle shape at the top right corner of a tab and by shading the tab with a stipple pattern. Also for menus the substyles `*-*-submenu' are handled as a special case.
Substyles are defined with the function de.substyle within the table defining the main style. The parameters to this function are similar to those of de.defstyle.
de.defstyle("some-style", {
...
de.substyle("some-substyle", {
...
}),
...
})
The following shortened segment from look_cleanviolet.lua should help to clarify the matters discussed in the previous subsection.
de.defstyle("*", {
-- Gray background
highlight_colour = "#eeeeee",
shadow_colour = "#eeeeee",
background_colour = "#aaaaaa",
foreground_colour = "#000000",
shadow_pixels = 1,
highlight_pixels = 1,
padding_pixels = 1,
spacing = 0,
border_style = "elevated",
font = "-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-*-*",
text_align = "center",
})
de.defstyle("tab-frame", {
based_on = "*",
de.substyle("active-selected", {
-- Violet tab
highlight_colour = "#aaaacc",
shadow_colour = "#aaaacc",
background_colour = "#666699",
foreground_colour = "#eeeeee",
}),
-- More substyles would follow ...
})
The function WFrame.set_grattr may be used to give frames (and their tabs) arbitrary extra attributes to be passed to the drawing engine. Hence, by configuring such substyles in the style configuration files, and turning on the attribute when needed, scripts may display visual cues related to the frame. There is also one extra attribute specially interpreted by the default drawing engine: the `numbered' attribute, which causes numbers to be displayed on the tabs.
The following style fields are independent of the drawing engine used, but are related to objects' styles and therefore configured in the drawing engine configuration file.
| Field | Description |
| bar | Controls the style of the tab-bar. Possible values are the strings `none', `inside', `outside' and `shaped', with the last providing the PWM-style tab-bars for floating frames. |
| frame_tab_width_alg | Algorithm used to determine tab sizes for non-shaped frames. `equal' is the default. `elastic' wants equal sized tabs, with long titles longer. `proportional' wants distribute free space equally among the tabs. |
| frame_tab_min_w | Minimum size of a tab. This size is maintained as long as no other tab has to be truncated in the case of the `proportional' or `elastic' algorithm. Also minimum size of a tab in shaped frame (for all algorithms). |
| floatframe_tab_min_w | Alias for frame_tab_min_w. This is an old name of the variable from times when the only algorithm was `equal'. |
| frame_propor_tab_min_w | Absolute minimum size of an elastic or proportional tab, `elastic' and `proportional' algorithms truncate other tabs rather than shortening a short tab below this size. |
| floatframe_bar_max_w_q | Maximum tab-bar width quotient of frame width for the shaped styles. A number in the interval (0, 1]. This quotient is maintained even if the tabs have to be smaller than frame_tab_min_w or frame_propor_tab_min_w to fit. |
| Field | Description |
| outline_style | How borders are drawn: `none' – no border, `all' – border around whole dock, `each' – border around each dockapp. |
| tile_size | A table with entries `width' and `height', indicating the width and height of tiles in pixels. |
Hopefully that's enough to get you started in writing new style configuration files for Notion. When in doubt, study the existing style configuration files.
This chapter documents some additional features of the Notion configuration
and scripting interface that can be used for more advanced scripting than
the basic configuration explained in chapter .
Some of Notion's functions call other functions in so-called “protected mode”.
In particular this is true for all the iterator functions mentioned in
. If a function fn is called in protected mode, the call
will only succeed if fn is considered “safe”, and will otherwise fail
with the message “Ignoring call to unsafe function fn in restricted
mode.”.
Let us try to explain the rationale behind this behavior and the heuristic for deciding when a function can be considered safe through an example. The function WMPlex.managed_i iterates over all regions managed by an mplex and calls iterfn on each of these regions. If iterfn was able to alter the list of regions managed by mplex, say by adding additional regions, this iteration could easily turn into an infinite loop or lead to inconsistent behavior.
To avoid situations like this, in order to be considered safe, a function must not alter any of the internal data structures of Notion.
If you ever need to use an unsafe function in combination with an iterator, there is a simple workaround. In the example above, instead of writing WMPlex.managed_i(mplex, iterfn), which fails if iterfn is unsafe, you can use the following code snippet to achieve the same result:
managed_regions={}
mplex:managed_i(function(reg)
table.insert(managed_regions, reg) return true
end)
for _,reg in ipairs(managed_regions) do
iterfn(reg)
end
Hooks are lists of functions to be called when a certain event occurs. There are two types of them; normal and “alternative” hooks. Normal hooks do not return anything, but alt-hooks should return a boolean indicating whether it handled its assigned task successfully. In the case that true is returned, remaining handlers are not called.
Hook handlers are registered by first finding the hook with ioncore.get_hook and then calling WHook.add on the (successful) result with the handler as parameter. Similarly handlers are unregistered with WHook.remove. For example:
ioncore.get_hook("ioncore_snapshot_hook"):add(
function() print("Snapshot hook called.") end
)
In this example the hook handler has no parameters, but many hook
handlers do. The types of parameters for each hook are listed in
the hook reference, section .
Note that many of the hooks are called in “protected mode” and can not use any functions that modify Notion's internal state.
All Notion objects are passed to Lua scripts as 'userdatas', and you may safely store such object references for future use. The C-side object may be destroyed while Lua still refers to the object. All exported functions gracefully fail in such a case, but if you need to explicitly test that the C-side object still exists, use obj_exists.
As an example, the following short piece of code implements bookmarking:
local bookmarks={}
-- Set bookmark bm point to the region reg
function set_bookmark(bm, reg)
bookmarks[bm]=reg
end
-- Go to bookmark bm
function goto_bookmark(bm)
if bookmarks[bm] then
-- We could check that bookmarks[bm] still exists, if we
-- wanted to avoid an error message.
bookmarks[bm]:goto()
end
end
If you want to a single non-WClientWin region with an exact known name, use ioncore.lookup_region. If you want a list of all regions, use ioncore.region_list. Both functions accept an optional argument that can be used to specify that the returned region(s) must be of a more specific type. Client windows live in a different namespace and for them you should use the equivalent functions ioncore.lookup_clientwin and ioncore.clientwin_list.
To get the name of an object, use WRegion.name. Please be aware, that the names of client windows reflect their titles and are subject to changes. To change the name of a non-client window region, use WRegion.set_name.
It is possible to write more complex winprop selection routines than
those described in section . To match a particular
winprop using whatever way you want to, just set the match
field of the winprop to a function that receives the as its parameters
the triple (prop, cwin, id), where prop is the table for
the winprop itself, cwin is the client window object,
and id is the WClientWin.get_ident result.
The function should return true if the winprop matches,
and false otherwise. Note that the match function
is only called after matching against class/role/instance.
The title of a client window can be obtained with WRegion.name. If you want to match against (almost) arbitrary window properties, have a look at the documentation for the following functions, and their standard Xlib counterparts: ioncore.x_intern_atom (XInternAtom), ioncore.x_get_window_property (XGetWindowProperty), and ioncore.x_get_text_property (XGetTextProperty).
All statusbar meters that do not monitor the internal state of Notion should go in the separate ion-statusd program.
Whenever the user requests a meter `%foo' or `%foo_bar' to be inserted in a statusbar, mod_statusbar asks ion-statusd to load statusd_foo.lua on its search path (same as that for Notion-side scripts). This script should then supply all meters with the initial part `foo'.
To provide this value, the script should simply call statusd.inform with the name of the meter and the value as a string. Additionally the script should provide a 'template' for the meter to facilitate expected width calculation by mod_statusbar, and may provide a 'hint' for colour-coding the value. The interpretation of hints depends on the graphical style in use, and currently the stock styles support the `normal', `important' and `critical' hints.
In our example of the 'foo monitor', at script initialisation we might broadcast the template as follows:
statusd.inform("foo_template", "000")
To inform mod_statusbar of the actual value of the meter and indicate that the value is critical if above 100, we might write the following function:
local function inform_foo(foo)
statusd.inform("foo", tostring(foo))
if foo>100 then
statusd.inform("foo_hint", "critical")
else
statusd.inform("foo_hint", "normal")
end
end
To periodically update the value of the meter, we must use timers. First we must create one:
local foo_timer=statusd.create_timer()
Then we write a function to be called whenever the timer expires. This function must also restart the timer.
local function update_foo()
local foo= ... measure foo somehow ...
inform_foo(foo)
foo_timer:set(settings.update_interval, update_foo)
end
Finally, at the end of our script we want to do the initial measurement, and set up timer for further measurements:
update_foo()
If our scripts supports configurable parameters, the following code (at the beginning of the script) will allow them to be configured in cfg_statusbar.lua and passed to the status daemon and our script:
local defaults={
update_interval=10*1000, -- 10 seconds
}
local settings=table.join(statusd.get_config("foo"), defaults)
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.
for details.
.
For GUI commands, you might prefer to use mod_query.exec_on_merr(), which monitors the process's stderr and shows any output as warnings on the screen instead of in notions own output.
Note that this function is asynchronous; the region will not actually have received the focus when this function returns.
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. |
Note that this function is asynchronous; the screen will not actually have received the focus when this function returns.
Note that this function is asynchronous; the screen will not actually have received the focus when this function returns.
Note that this function is asynchronous; the screen will not actually have received the focus when this function returns.
Note that this function is asynchronous; the region will not actually have received the focus when this function returns.
| 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? |
| warp_margin | (integer) Border offset in pixels to apply to the cursor when warping. |
| warp_factor | (double[2]) X and Y factor to offset the cursor. between 0 and 1, where 0.5 is the center. |
| 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), ”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”. |
| unsqueeze | (boolean) Auto-unsqueeze transients/menus/queries/etc. |
| window_dialog_float | (boolean) Float dialog type windows. |
| autoraise | (boolean) Autoraise regions in groups on goto. |
| autosave_layout | (boolean) Automatically save layout on restart and exit. |
| window_stacking_request | (string) How to respond to window-stacking requests. `ignore' to do nothing, `activate' to set the activity flag on a window requesting to be stacked Above. |
| focuslist_insert_delay | (integer) Time (in ms) that a window must stay focused in order to be added to the focus list. If this value is set <=0, this logic is disabled: the focus list is updated immediately |
| activity_notification_on_all_screens | (boolean) If enabled, activity notifiers are displayed on ALL the screens, not just the screen that contains the window producing the notification. This is only relevant on multi-head setups. By default this is disabled |
| workspace_indicator_timeout | (integer) If enabled, a workspace indicator comes up at the bottom-left of the screen when a new workspace is selected. This indicator stays active for only as long as indicated by this variable (in ms). Timeout values <=0 disable the indicator altogether. This is disabled by default |
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).
.
.
.
.
.
.
.
{switchto=true} is used.
| 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 . |
In addition parameters to the region to be created are passed in this same table.
| 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. |
| 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. |
| sizepolicy | (string) Size policy; see Section . |
| geom | (table) Geometry specification. |
In addition parameters to the region to be created are passed in this same table.
| -1 | Last. |
| -2 | After WMPlex.mx_current. |
| Field | Description |
| pos | The corner of the screen to place the status display in. One of tl, tr, bl or br. |
| action | If this field is set to keep, corner and orientation are changed for the existing status display. If this field is set to remove, the existing status display is removed. If this field is not set or is set to replace, a new status display is created and the old, if any, removed. |
| horizmul/vertmul | effect |
| -1 | Move left/up |
| 0 | No effect |
| 1 | Move right/down |
Note that this function is asynchronous; the region will not actually have received the focus when this function returns.
I'm not *entirely* sure what 'safe' means, but this doesn't change internal notion state, so I guess it's 'safe'... This function is considered safe.
| 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: true). |
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.
| 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. |
| Key | Values | Description |
| name | string | Name of dock |
| pos | string in {t, m, b}×{t, c, b} | Dock position. Can only be used in floating mode. |
| grow | up/down/left/right | Growth direction where new dockapps are added. Also sets orientation for dock when working as WMPlex status display (see WMPlex.set_stdisp). |
| is_auto | bool | Should dock automatically manage new dockapps? |
Any parameters not explicitly set in conftab will be left unchanged.
| Variable | Type | Description |
| template | string | The template; see
Section . |
| 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. |
| 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.
| 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 |
| 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. |
| 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.
Some functions accept a sizepolicy parameter. The possible values are:
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.
The purpose of this License is to make a manual, textbook, or other functional and useful document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
| A. | Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. |
| B. | List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. |
| C. | State on the Title page the name of the publisher of the Modified Version, as the publisher. |
| D. | Preserve all the copyright notices of the Document. |
| E. | Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. |
| F. | Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. |
| G. | Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. |
| H. | Include an unaltered copy of this License. |
| I. | Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. |
| J. | Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. |
| K. | For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. |
| L. | Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. |
| M. | Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version. |
| N. | Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section. |
| O. | Preserve any Warranty Disclaimers. |
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties–for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements”.
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright © YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with ... Texts.” line with this:
with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
Obj
|-->WHook
|-->WTimer
|-->WMoveresMode
|-->WRegion
| |-->WClientWin
| |-->WWindow
| | |-->WRootWin
| | |-->WMPlex
| | | |-->WFrame
| | | `-->WScreen
| | |-->WInfoWin
| | | `-->WStatusBar (mod_statusbar)
| | |-->WMenu (mod_menu)
| | `-->WInput (mod_query)
| | |-->WEdln (mod_query)
| | `-->WMessage (mod_query)
| |-->WGroup
| | |-->WGroupWS
| | `-->WGroupCW
| `-->WTiling (mod_tiling)
`-->WSplit (mod_tiling)
|-->WSplitInner (mod_tiling)
| `-->WSplitSplit (mod_tiling)
| `-->WSplitFloat (mod_tiling)
`-->WSplitRegion (mod_tiling)
`-->WSplitST (mod_tiling)
1#1
This document was generated using the LaTeX2HTML translator Version 2025 (Released January 1, 2025)
The command line arguments were:
latex2html -show_section_numbers -short_index -local_icons -noaddress -up_url https://notionwm.net -up_title 'Notion homepage' -nofootnode -style notion.css -html_version 4.0,math,table -split 0 -dir notionconf-onepage notionconf
The translation was initiated on 2025-06-11