Dim is a pure-Python window manager for the X window system written by Alex Plotnick. It currently runs under Python 2.6 or 2.7, and uses xpyb (the Python XCB bindings) to communicate with the X server. It was designed to be:
- Correct (especially with regard to sloppy focus)
- Simple
- Extensible
- Unobtrusive
It was not designed to support desktop environments or eye candy.
To use Dim, you'll first need to install xpyb; packages are available
for all major Unix-like systems. Once you've got that, you can download
Dim and try running it directly from the source directory. First run
./setup.py generate_py to auto-generate a few modules from the
Xlib C headers (if those aren't in any of the usual places, you can use
the --source-dirs option to tell the setup script where to find them),
then run ./bin/dim to start it up. If you decide you like it,
you can install it via ./setup.py install.
The main script bin/dim takes a variety of options that control various
aspects of its behavior; --help gives a summary. For example, the default
focus mode is sloppy focus (i.e., focus-follows-mouse except for the root
window), but if you prefer click-to-focus (like Windows or Mac OS), you can
use the --focus-mode=click option. If you don't like the standard fixed
font for your window titles, you can provide an XLFD font name with the
--title-font option (Dim currently supports only core X fonts, so don't
give it an Xft-style name). Dim can also be asked to exit, restart itself,
invoke another window manager, or switch tagsets from the
command line; see Control Options in the help message.
While Dim is running, it decorates visible windows with a titlebar and a
thin border. You can move a window around by clicking and dragging on the
titlebar, or by holding down the Alt key and clicking anywhere in the window.
If you hold down Alt and right-click (i.e., press button 3) in a window,
you can resize the window; where you initially click in the window
determines which side or corner is adjusted during the resize, but you can
use the space bar to switch between modes. Pressing escape during a resize
or move aborts the operation and returns the window to its original size
and position. Other windows and the screen edges (and CRTC edges, if the
RandR extension is enabled) offer resistance to window movement and
resizing. Notice also that guide lines appear along with resistance due
to adjacent window edges; this helps you easily line up windows.
A set of window maximization shortcuts is also defined. By default, the
bindings use the prefix Control-Alt-=, followed by Return to toggle
fullscreen mode (no titlebar or other decorations), Left or Right to
maximize horizontally, Up or Down to maximize vertically, Space to
toggle maximization, and - to unmaximize. The example user-customization
file includes further bindings for multitouch gestures (e.g., swipe down
to maximize vertically, left for horizontally, &c.); see
Customization below.
One of Dim's distinguishing features is its use of tagsets instead of traditional virtual desktops. Each window managed by Dim may tagged with any number of tags (non-whitespace-containing strings), and windows that share a tag are implicitly grouped into a tagset. A small but powerful tagset specification language allows you to select which windows are visible.
To tag a window, middle-click (i.e., press button 2) in the titlebar.
The title will be replaced with a Tags: prompt; enter a space-separated
list of tag names, followed by return to commit, or escape to abort.
(A small set of Emacs-like keybindings is supported in this and the other
text entry fields discussed below.)
To switch between tagsets, press Control-Alt-Tab, and type a tagset
specification into the minibuffer that appears. (You can also switch
tagsets using the dim script with the -t option.) If you gave each
window exactly one tag and simply switched between those tagsets,
you'd have a scheme very similar to most implementations of virtual desktops.
But tagsets are more general than virtual desktops, because (a) windows
can have more than one tag, and (b) tagset specifications can include
arbitrary set operations over tagsets. The tagset specification language
is a very small infix language where alphanumeric strings represent tagsets,
and the operators |, \, &, and ~ represent set union, difference,
intersection, and complement, respectively (in increasing order of
precedence). Parenthesis may be used to group sub-expressions, and
whitespace may be used to separate tokens, but is otherwise ignored.
Thus, a tagset specification of (work \ docs) | mail says to display
all of the windows tagged work except those also tagged docs, along
with any windows tagged mail. The special tag . represents the set of
windows currently visible, so if you followed the last example with .\mail,
you'd get everything currently visible except your mail window. The special
tag * means all tags, and 0 represents the empty set, i.e., the set of
no windows. (* and ~0 are not, in general, equivalent, because the latter
includes windows with no tags, whereas the former does not.) If you tag
a window as *, it will implicitly become a part of every tagset, thus
becoming "sticky".
Pressing Control-Alt-space prompts you for a command line to execute
using /bin/sh. At present, no output from such commands is displayed,
so this should only be used for launching X clients or commands with
side-effects.
Dim is designed to be customized & extended with Python code. This has the disadvantage of requiring a certain level of skill and an understanding of some (maybe too much) of its internals, but is much more flexible than a static configuration language. The code is highly modular, and should be reasonably easy to understand given a solid grounding in [protocol-level X] (http://www.x.org/releases/X11R7.6/doc/xproto/x11protocol.html) programming and the [ICCCM] (http://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/ICCCM/icccm.html).
The modules in the dim package define the core window manager functionality,
but many important user-facing variables and classes are defined in the main
script bin/dim, so that's a good place to begin customizing Dim's behavior.
For instance, all of the key & mouse button bindings described in this
document are merely defaults established by the global bindings dictionaries
defined therein. A simple but reasonably powerful bindings language is used
for those definitions, expressed as Python dictionaries; see dim/bindings.py
for details.
You can modify bin/dim, but may prefer not to. To support customization
on a per-user basis, it loads the contents of the file ~/.dim.py, which
on the author's system is a link to the sample etc/user-dim.py. In that
script you will find several examples of the kinds of customizations that
are easy with Dim: augmentation & overriding of button and key bindings,
launching pre-specified commands, changing fonts & colors, pre-defining
tagsets, customizing client decorations, &c. More complex customizations
or extensions generally require adding or modifying modules in the dim
package.
Pressing Break (i.e., Control-Pause) while Dim is running brings up a
debugging console (an xterm in slave mode) with the Python debugger (PDB)
attached to the window manager process. In the (unlikely) event of a crash,
an emergency debugging console will be launched automatically; the exception
that caused the crash may thus be examined and the window manager restarted
without disrupting running clients.
Dim also has extensive support for logging. Running bin/dim with the -v
option causes it to output informational messages:
INFO: wm: Spawning command: ['/usr/local/bin/zsh', '-i', '-c', 'xterm'].
INFO: manager: Shutting down.
INFO: manager: Executing command /home/alex/src/dim/bin/dim --verbose.
The -d option enables full debugging output:
INFO: manager: Executing command dim -d.
DEBUG: wm: Using sloppy focus policy.
DEBUG: manager: Screen geometry: 640x480+0+0.
DEBUG: randr: Using RANDR extension for multi-head support.
DEBUG: randr: CRTC geometries: {0x5e: 640x480+0+0}.
DEBUG: manager: Registering event handler for window 0x54.
DEBUG: tags: Tagset stack: [set([])].
DEBUG: tags: Tagset stack: [set([])].
DEBUG: manager: Adopting window 0x400003.
DEBUG: manager: Managing client window 0x400003.
DEBUG: properties.0x400003: Requesting property WM_CLASS (STRING).
DEBUG: properties.0x400003: Requesting property _NET_WM_STATE (ATOM).
DEBUG: properties.0x400003: Requesting property WM_NORMAL_HINTS (WM_SIZE_HINTS).
DEBUG: client.0x400003: Creating frame 0x60001c.
DEBUG: manager: Registering event handler for window 0x400003.
DEBUG: manager: Registering event handler for window 0x60001c.
DEBUG: properties.0x400003: Requesting property WM_TRANSIENT_FOR (WINDOW).
DEBUG: properties.0x400003: Requesting property _DIM_TAGS (ATOM).
The -l option can be used to enable logging for specific modules; e.g.,
if you're tracking down a focus issue (after alerting the author, who takes
such bugs very seriously) you might not care about property updates.
Dim is still missing many features that some may consider important, such as full EWMH support, colormap handling (does anyone actually care anymore?), tiling support, compositing, and non-code-based configuration. There are surely still many bugs lurking, and certainly bits of the code that could be cleaner. Perhaps most importantly, this document is currently the closest thing to an end-user manual. If you would like to help out on any of these fronts, please feel free to contact the author. Other comments, questions, complaints, praises, and suggestions are also welcome.