MatWM 2 - Manual



matwm2 − Window manager for X11


matwm2 [−display display]

matwm2 −defaults

matwm2 −version


matwm2 is a simple window manager for X11. It features window frames with titlebar and buttons, configurable key bindings and mouse buttons, support for EWMH and motif hints, focus-follows-mouse and click-to-focus focus models, virtual desktops, Xft fonts and xinerama support.

To exit matwm2 send it SIGINT signal. At exit matwm2 will place the windows back on the root window in stacking order, iconic windows on the bottom, above that the windows from all inactive desktops in reverse order and then above those the windows from the current desktop and sticky windows shown on it. If matwm2 receives a SIGUSR1 signal it will reload all configuration files.

When a focussed window dissapears the window that was focussed before will be focused (unless the "click_focus" option is set to "false" and the cursor is above another window due to the window dissapearing), and if no previous window is there (if it has dissapeared for example) then the topmost window will be focused.

Further, explanition of the various options in the configuration file(s) below combined with the default configuration, should give you an idea of how to use matwm2. Just keep in mind there is no default built-in way of launching applications except the ctrl-mod1-return key binding, which spawns an xterm.



Specify the X display to use.


Show wich version of matwm this is and exit. As of version 0.0.97 this will also print some information on the options matwm was compiled with.


Print built-in default configuration to stdout and exit.



System wide configuration file.


Per user configuration file.

Both of these config files share the same format, and can be considered a list of "commands" that may or may not have arguments, separated by spaces. The commands themselves are separated by newlines. If matwm2 encounters a ’#’ character in one of these files, the rest of the line is ignored. To use a literal ’#’ or ’"’ you can precede it with the escape character ’\’, and for a literal ’\’, "\\" will do. For arguments of type [string] double quotes (as in the character ’"’) can be used to omit whitespace being stripped.

Any value set last overrides previous values for the setting, matwm2 reads the default configuration first, after that it reads the global configuration file and last the the user’s personal configuration file (if these exist).

Following is a list of possible commands for matwm2 configuration files and their explanation. Valid modifier keys are "shift", "lock", "control" and "mod1" to "mod5" (see: output of xmodmap).

background [X11 color name]

Sets the background color of window frames when they are focussed.

inactive_background [X11 color name]

Sets the background color of window frames when they are not focussed.

foreground [X11 color name]

Sets the foreground (text, border) color of window frames when they are focussed.

inactive_foreground [X11 color name]

Sets the foreground (text, border) color of window frames when they are not focussed.

border_color [X11 color name]

Sets the color for borders around focussed windows.

inactive_border_color [X11 color name]

Sets the color for the borders of not focussed windows.

font [font name]

Sets the font used for drawing text. Will take both X11 font names and - if compiled with Xft support (run "matwm2 -version" to find out) - fontconfig patterns.

no_title [string]

Set the title for window’s that don’t have a title to [string], or if used without an argument use an empty title.

doubleclick_time [integer]

With this option you can specify how much time there can be between two clicks at most while still considering it a double click, in miliseconds.

border_width [integer]

Sets the width of window frame borders to [integer] pixels.

border_spacing [integer]

Sets the space between the window border and the actual client window to [interger] pixels.

title_spacing [integer]

Sets how much space there is to be between the bottom of the title text and the actual client window.

button_spacing [integer]

Sets the amount of space that goes between buttons (and the left buttons and title if center_title is false) to [integer] pixels.

wlist_margin [integer]

Sets how much space goes around text in window list items to [integer] pixels.

wlist_maxwidth [integer]

Sets the maximum with for items in the window list to [integer] pixels, if set to 0 or bigger then the display’s width the window list will be restricted to the width of the display.

snap [integer]

Snap windows together or to screen edges when they are [integer] pixels away from eachother, set to 0 to disable snapping.

desktops [integer]

Sets the amount of virtual desktops.

exec [command]

Invoke "sh -c [command]" when matwm2 starts. Doesn’t override previous occurences of this command.

exec_onload [command]

Invoke "sh -c [command]" whenever the configuration file it is in is read. This also can’t be overriden.

ignore_modifier [modifier key] [...]

Ignore the state of specified modifier key(s). Set to "none" to disable.

mouse_modifier [modifier key] [...]

If specified modifier key(s) are down, user can use the same button actions as set for the window frame in the client window itself.

no_snap_modifier [modifier key] [...]

If specified modifier key(s) are down while dragging a window (either to move or resize it) windows will not snap to eachother or window edges.

click_focus [boolean]

Sets the focus model, if set to "true" matwm2 will focus windows when they are clicked. If set to "false" windows will be focussed when the mouse cursor moves over them. If it is false and the window under the mouse somehow hasn’t got focus anymore, and windows that have EWMH hints set to specify they are a desktop will always be focussed only when clicked.

click_raise [boolean]

If set to "true" windows will be risen when they (meaning the window itself, not its frame) are clicked, if set to "false" this behavior is disabled.

focus_new [boolean]

If set to "true" new windows will be focussed when they appear and accordingly a value of "false" disables this behaviour. If you are dragging a window or in window list mode at the time of the window apearing the new window shall not be focussed even with this option set to "true".

center_title [boolean]

If set to "true" the title of windows will apear in the center of the titlebar, if set to "false" it will be at the left.

center_wlist_items [boolean]

If set to "true" all titles in the window list are centered, if set to "false" they are aligned at the left.

map_center [boolean]

If set to "true" new windows will appear centered (unless they have a predefined position set). If set to "false" the windows will not be moved before mapping.

drag_warp [boolean]

If set to "true" moving a window over the right edge of the desktop will move it to the left of the next virtual desktop and vice versa.

buttons_left [button] [...]

Set a list of buttons (from left to right) to show at the left of the title of windows. Possible buttons are "iconify", "expand", "maximize", "close", "sticky", "ontop" and "below", they do the same as the actions with the same names described below. Can be set to "none" if you want no buttons there. Buttons can be clicked with either the first (left) or the third (right) mouse button.

buttons_right [button] [...]

Same as the "buttons_left" option but for buttons at the right of the titlebar.


If set to "true" taskbar windows that use EWMH hints will be kept ontop, if set to "false" windows can cover them.

ewmh_screen [integer]

Set the screen (in xinerama setups) to wich desktop windows etc go to [integer] (screens are in the order X11 places them).

fullscreen_stacking [stacking mode]

If set to "normal" fullscreen windows behave like other windows in terms of stacking, when this is set to "ontop" they can raise over always-on-top windows and if set to "always_ontop" fullscreened windows are always on top and new windows will not be focussed if theres a fullscreen window above them.

allow_focus_stealing [boolean]

If set to "false" matwm will confine input focus to the window you manually focussed (with exeption windows that use EWMH to focus windows, and newly mapped windows if focus_new is set to "true").

correct_center [boolean]

If this is set to "true" windows wich are placed in the center of the root window, are placed in the center of the current screen (for xinerama setups). This behaviour is omitted if the window is bigger then the current screen.

correct_center_unmanaged [boolean]

Same as above but for windows that set override_redirect.

correct_center_separate [boolean]

If set to "true" above two settings apply for x and y axis individually, else they only work for windows that are centered on both x and y axis.

click_root [boolean]

If this is set to "false" matwm will not choose to receive ButtonPress events from the root window, thus allowing other applications to do so (this breaks root_button[1-5] and root_double[1-5] options).

button[1-5] [action]

Sets the function mouse buttons have on window borders. Possible button actions are "move", "resize", and any of the actions listed below. "move" and "resize" raise the window and let the user drag it to resize or move it while the mouse button is held down.

double[1-5] [action]

Same as the above, but for double clicks.

root_button[1-5] [action]

To set what a click on the root window does.

root_double[1-5] [action]

And for double clicks on the root window.


Remove all previously defined key bindings from memory.

key [modifier key] [...] [X11 key name] [action]

Binds the specified modifier and key combination to [action]. Key names are obtained from <X11/keysymdef.h> by removing the XK_ prefix from each name.

Following is a list of possible actions and their explanation.

exec [command]

Invokes "sh -c [command]".


Focus the next window in the stacking. Pressing a key bound to this or the "prev" action will show you a list with all currently visible and iconic windows, wich will dissapear when all modifiers of either key action are released. Afterwards the window selected will be raised. If it is off screen it will be brought back on screen, also the mouse will be warped to the bottom right corner of the window. Between the last normal window and the first iconic window there will be slightly more spacing, to clarify what windows are iconic. Items in this list can also be focussed with the mouse in the same way as windows. This and the following option can only be bound to key combinations with at least one modifier key.


Focus the previous window in the stacking.


Iconify the current window (window will dissapear, but can be found in either a taskbar that complies with the EWMH specification, or the window list that apears if one of the two functions above is called). Iconified windows will be placed at the very bottom of the stack (so for icons top to bottom order in the window list complies with first to last window iconified).

maximise [direction] [...]

Maximise the current window, or revert a maximised window to its previous state. The optional argument [direction] can be h, v, l, r, d or u (respectively horizontal, vertical, left, right, up and down), or a combination of those to specify the action is to be comitted only in the specified direction(s).

expand [direction] [...]

This function serves to grow a window in size as much as is possible without overlapping any more windows then are currently already overlapped by it. The [direction] argument does exactly what is does for the maximise key action. By default it calculates available horizontal space first, to make it calculate vertical space first you can add and a to the direction argument.


Make the current window apear fullscreen, or revert a fullscreen window to its previous state.


Send a WM_DELETE_WINDOW the current window if the window supports it, else destroy it with XKillClient().


Make the current window sticky (appear on all desktops), or reverses this.


Toggle always-on-top mode for the current window.


Toggle stay-below mode for the current window.


Toggle display of title bar for the current window.


Iconify all windows. If no iconic windows are restored after the last call to this function, the next call to it will restore the windows iconified with it. If your taskbar uses EWMH and has a "show desktop" button, it can also be used to do this.


Go to the next virtual desktop.


Go to the previous virtual desktop.

to_border [border] [...]

Move the current window to a border or corner of the screen, argument is one or more of l, r, t and b (left, right, top and bottom respectively).


Raise the current window to the top of the stack.


Lower the current window to the bottom of the stack.


Exit matwm2


Mattis Michel

Many thanks to Kirn Gill and Matthew Turner for bug reports, suggestions and patches.


XQueryColor(3), XStringToKeysym(3), xmodmap(1)

Copyright © 2017-2020 Mattis Michel