# The K Window Manager Handbook

The KDE Team
29/11/1998
0.19.15

This documentation was last updated for kwm version 0.19.15. Please make any comments and additions to the author.

KDE
window manager

## Introduction

This document contains general information about kwm, a feature reference, and technical information useful for the developers of the kwm control module and the system sound module.

For further information how to customize kwm at the low level (only interesting for the kwinconfig developers) please have a look at the generated kwmrc and the source code.

For all programmers: check out `kwm.h` in libkdecore for information how to use kwm for your purposes. For modules, the class `KWMModuleApplication` is a good example on how to write modules.

### Features

kwm is the window manager of choice for KDE. Among other things, it offers:

- Complete integration into KDE.

- Complete keyboard control.

- Modern look and feel with unique window titles and icons which do not need to be defined in cryptic resource files.

- A convenient mini command-line window with history for quick access to a shell prompt.

- Ability to be reconfigured at runtime without restarting. This includes look and feel issues as well as keyboard shortcuts.

- Second generation window manager. KWM uses a modern GUI toolkit for its widgets (buttons, menus, listboxes, etc.) instead of bloating the code with a proprietary or plain Xlib implementation.

- Excellent focus handling even if you work on different virtual desktops (no longer desktop-switching-and-losing-focus like it is standard with other window managers).

- `kstart` utiliy to launch legay applications with special KDE window properties such as iconified, maximized, a certain virtual desktop, a special decoration or sticky. Simply run `kstart -help` for further informations.

- Includes session management and a working session management proxy for legacy applications. This proxy is able to restore your applications to their previous state, including window properties (maximized, sticky, iconified, etc.) and on the correct virtual desktop.

- Modern module concept that uses the X Server where it is possible. KWM modules are also very independent: they can be started before or after kwm. KWM can be restarted while the modules are still running and will reconnect them automatically.

- Some powerful modules, such as the KDE desktop panel (which also includes a taskbar) and an extremely fancy desktop pager .

- Offers some extensions to the X Server in `kwm.h`: Now applications can even maximize themselves (or sticky, or decorate/undecorate or whatever) and define mini icons. This works also for mapped (visible) windows.

## Using kwm

### Command line options

kwm provides the following command line options:

-version

  Shows the version number including the patchlevel; does not start kwm

-nosession

  Starts kwm without restoring the previous session

### Shortcuts

The global shortcuts are configurable in the control center. This is the list of the defined default shortcuts, others are possible.

Alt-Esc or Control-Esc

  "Current Session"-manager with logout-button

Alt-Tab and Alt-Shift-Tab

  Traverse the windows of the current desktop

Ctrl-Tab and Ctrl-Shift-Tab

  Traverse the virtual desktops (can be switched off in kwmrc)

Alt-F2

  Open mini command-line window

Alt-F3

  Window operation menu

Alt-F4

  Close window

Ctrl-F&lsqb;1..8&rsqb;

  Switch to virtual desktop

Ctrl-Alt-Esc

  Destroy window mode (cursor becomes a pirate)

### Mouse Control

The Mouse Control is like the keyboard shortcuts configurable in the control center. This is the list of the default settings.

Click onto the border or the titlebar

- left mouse button activate and raise the window

- middle mouse button activate and lower the window

- right mouse button show windows operation menu if the window is active, otherwise activate it without raising

Double-click on title bar toggles maximize

Drag of the titlebar

- left mouse button moves the window and raises it

- middle mouse button moves the window without raising it

Drag of corners or edges

- left mouse button resizes the window and raises it

- middle mouse button resizes the window without raising it

The entire window

- Alt-left mouse button moves the window

- Alt-middle mouse button lowers the window if it is already on top

- Alt-right mouse button resizes the window

Title bar buttons (configurable)

- Menu displays a list of window operations

- Sticky toggles sticky mode on/off (window stays on screen as you move from desktop to desktop)

- Iconify iconifies the window

- Maximize

  - left mouse button maximize

  - middle mouse button maximize vertically

  - right mouse button maximize horizontally

- Close closes the window (applications may ask if they have something to save)

### Mini Command-line Window

Press `Alt-F2` to display a small command-line window. Enter a Unix shell command (the SHELL environment variable is used to determine which shell executes the command), or one of the following:

- Enter a URL to open a kfm window with the specified URL. You can omit the http:// or ftp:// if the server's name starts with www. or ftp., respectively.

- Enter `man:command` to open a kfm window displaying the Unix man page for command.

You can use the up-arrow key to recall previously entered commands. Also, you can use the tab key to complete partially entered filenames, as in many shells.

### Commands

You can send commands to kwm with either:

`KWM::sendKWMCommand(QString)` (in KDE applications) or `kwmcom` command (from the command line)

This is especially of interest for kglobalshortcut developers.

At present kwm understands the following commands:

- refreshScreen refreshes the screen

- darkenScreen turns the screen dark. Careful: this one makes the desktop unresponsive to keyboard/mouse input.

- logout displays the logout dialog.

- commandLine opens the mini command-line window

- taskManager displays the "Current Session" manager.

- configure reloads configuration from kwmrc.

- - winMove

  - winResize

  - winRestore

  - winIconify

  - winClose

  - winShade

  - winSticky

  - winOperations

  These commands affect the currently active window and do pretty much what you would expect. (`winOperations` displays the window operations menu.)

- - deskUnclutter

  - deskCascade

  These commands reorganize windows on the desktop

- desktop&lsqb;1-8&rsqb; switches to the specified desktop

- - desktop+1

  - desktop+2

  - desktop-1

  - desktop-2

  - desktop&percnt;2

  These commands switch between desktops. `desktop&percnt;2` toggles between an odd desktop and the next higher even number. That means between 1 and 2 or between 3 and 4. This is useful to emulate "Up" and "Down" in a virtual n*2 matrix, which is used by the KDE pager. Similarly, `desktop+2` means "Right"; `desktop-1` means "Left".

- go:other The go command exits kwm and all its modules and launches other instead. other can for example be the name of another window manager such as fvwm. Note: you cannot pass a path to the go-command but only the executable name, since `kwmcom` is limited to 20 characters.

## Configuration

kwm can be configured using the KDE Control Center (application starter > KDE Control Center). Open the Windows tree to work with the various configuration options. The keyboard shortcuts can be configure in the Global Keys section.

To configure virtual desktops, open the Applications tree and choose Panel.

For those who prefer to edit a configuration file, this section explains the options in the `kwmrc` file, located in ˜/.kde/share/config.

### kwmrc

The kwmrc configuration file is divided into the following sections:

- Buttons

- General

- Session

- Desktop

- Decoration

- Focus

- Sticky

#### &lsqb;Buttons&rsqb;

This section controls placement of window control buttons in the titlebar. It contains lines of the form

ButtonX=button-name

where X is a letter A-F, and button-name is one of `Menu, Sticky, Iconify, Maximize, Close, Off`. Buttons A, B, and C appear on the left-hand side of the window title, and D, E, and F appear on the right-hand side.

#### &lsqb;General&rsqb;

This section defines a number of miscellaneous configuration items:

`AltTabStyle`=KDE&verbar;CDE

  (default is KDE)

  CDE style AltTab-Feature to be usable with the classic focus policies. The CDE style is default with the classic focus policies, since KDE style does not make much sense under these circumstances. For all other focus policies you may choose the style.

`AutoRaise`=value (in milliseconds)

  If `FocusPolicy` is `FocusFollowMouse`, this item determines the delay between the time a window gains focus when the mouse enters it and the time the window is raised to the top.

`BorderSnapZone`=value (in pixels)

  When the user is positioning a window, and one of the window borders approaches the desktop border, the window will snap to the border. value determines how close the window must be to the desktop border to snap to it.

`Button3Grab`=on&verbar;off

  When `off`, window operations involving the right mouse button are disabled so that application windows can receive right mouse button events.

`ControlTab`=on&verbar;off

  When `on`, allows the user to press `Ctrl+Tab` to switch between virtual desktops.

`ElectricBorder`=value (in milliseconds)

  When you have more than one desktop, the ElectricBorder feature allows you to move between them by moving the mouse to the edge of the screen. value specifies the length of time you must keep the mouse pointer positioned at the border before the desktop changes. A value of -1 disables this feature.

`ElectricBorderPointerWarp`=NoWarp&verbar;MiddleWarp&verbar;FullWarp

  If the `ElectricBorder` option is `on`, turn this `on` to have the mouse moved to the corresponding position when the desktop changes.

`ElectricBorderNumberOfPushes`=value

  (default is 5 pushes)

  The number of pushes within the time frame given by the `ElectricBorder` property to switch to another virtual desktop without dragging a window.

`FocusPolicy`=ClickToFocus&verbar;FocusFollowMouse&verbar;ClassicFocusFollowsMouse&verbar;ClassicSloppyFocus

  `ClickToFocus` requires the user to click the mouse in a window to give the window focus. `FocusFollowMouse` always gives focus to the window under the mouse. `ClassicFocusFollowsMouse` no window without the mouse gets the focus. Kwm's focusFollowMouse used to put the focus to new windows or Alt-tab to allow better keyboard control.

`MaximizeOnlyVertically`=off&verbar;on

  When `on`, this setting restricts the window maximize to the vertical direction only.

`ResizeAnimation`=1..10 (maximum speed)

  When `on`, minimizing and maximizing windows involves graphical animation. (default is 1)

`RstartProtocol`=...

  (default is "rstart -v")

`ShapeMode`=off&verbar;on

  When ShapeMode is `on`, kwm uses user-defined pixmaps for window borders instead of the default (see below).

`ShapePixmapTop`=pixmap
`ShapePixmapBottom`=pixmap
`ShapePixmapLeft`=pixmap
`ShapePixmapRight`=pixmap
`ShapePixmapTopLeft`=pixmap
`ShapePixmapTopRight`=pixmap
`ShapePixmapBottomLeft`=pixmap
`ShapePixmapBottomRight`=pixmap

  These options specify what images are displayed at the respective sides/corners of windows when `ShapeMode` is `on`. pixmap should be the name of a pixmap file (.xpm) which must be located in share/apps/kwm/pics.

  The kwm sources include a subfolder "images", which contains an example for the the shape extensions.

`TitlebarLook`=shaded&verbar;plain&verbar;pixmap

  This setting determines the appearance of window title bars. Choose `pixmap` to have kwm display a user-defined image in the title bar, as specified by the following items.

`TitlebarPixmapActive`=pixmap

  TitlebarPixmapInactive=pixmap

  These options specify what images are displayed in titlebars of active and inactive windows, respectively, when TitleBarLook is `pixmap`.

`TitleAnimation`=value (in milliseconds)

  Enabling TitleAnimation tells kwm to cause long window titles (too long to fit in the colored area of the titlebar) to slide back and forth in order to be visible. value specifies the speed of the animation. Set to 0 to disable the animation.

`TitlebarDoubleClickCommand`=winMaximize&verbar;winShade&verbar;winMove&verbar; winResize&verbar;winRestore&verbar;winIconify&verbar;winClose&verbar;winSticky&verbar; winOperations

  This option allows you to specify what window behavior should occur when the user double-clicks the titlebar.

`TraverseAll`=on&verbar;off

  When `on`, the `Alt-tab` operation cycles through all windows on all desktops. When `off`, `Alt-tab` cycles through windows on the current desktop only.

`WindowMoveType`=Opaque&verbar;Transparent

  This option controls the visual feedback that occurs while the user drags a window from one place to another on the desktop. `Transparent` shows only a window outline during a drag, while `Opaque` shows the entire window.

`WindowsPlacement`=cascade&verbar;interactive&verbar;manual&verbar;random&verbar;smart

  This option determines how kwm places windows on the desktop when they are first opened. `manual` allows the user to place the window. `interactive` takes an additional percentage value, like this:

  With `interactive` placement, kwm uses the `smart` placement algorithm to place the window unless the placement would overlap existing windows more than the specified percentage, in which case `manual` placement is used to allow the user to place the window. The percentage can be greater than 100.

  The other options let kwm place the window.

`WindowSnapZone`=value (in pixels)

  When the user is positioning a window, and one of the window borders approaches the border of another window, the border of the window being positioned will snap to the other window's border. value determines how close the window must be to snap to another window's border.

#### &lsqb;Session&rsqb;

`proxyignore`=xemacs,xterm,...

  Comma delimited list of (non-KDE) applications whose application state (window properties) should not be saved when the user logs out. List the application name with any command line arguments.

#### &lsqb;Desktop&rsqb;

This section defines the number of virtual desktops, their names, and positions. It contains lines like the following:

`NumberOfDesktops`=value

  Specifies the number of virtual desktops. At the time of writing, kwm supports up to 8 desktops.

`Desktop&num;&lsqb;C&rsqb;`=name

  Specifies the name of Desktop &num;, for example,

  `Desktop1[C]=One`

  Desktops are numbered 1-8.

`Desktop&num;Region`=geometry

  Specifies the geometry for Desktop &num;; for example,

  `Desktop1Region=101+0+923+722`

Note that overwriting the regions in the config file will have very little effect, since kpanel will tell kwm reasonable values for the current desktop as soon as it starts up. When you logout, kwm will store these new settings.

#### &lsqb;Decoration&rsqb;

- noDecorationTitles=,

- tinyDecorationTitles=,

- noDecorationClasses=,

- tinyDecorationClasses=,

#### &lsqb;Focus&rsqb;

- noFocusTitles=,

- noFocusClasses=,

#### &lsqb;Sticky&rsqb;

- stickyTitles=,

- stickyClasses=,

Each property allows you to specify a comma separated list of regular expressions. A window whose title or class matches a specified expression will be decorated appropriately.

Note: These hints only affect NEW windows. Do not forget to call `kwmcom` configure or re-start `kwm` after you changed the kwmrc file.

Instead of hacking the config file you probabaly want to use the `kstart` utility.

## Sound Events

KWM raises a couple of sound events, which can be used in a system sound module. At present the following sound events are implemented:

- Window Iconify

- Window DeIconify

- Window Maximize

- Window UnMaximize

- Window Sticky

- Window UnSticky

- Window New

- Window Delete

- Window New Trans

- Window Delete Trans

- Window Shade Up

- Window Shade Down

- Logout

- Logout Message

## Frequently Asked Questions

### Why should I use kwm?

I spent several days in learning how to configure 10 different window mangers. Now that I have 678 lines of resource files doing exactly what I want, you are coming along and want to take my window manager away!

Answer: You should not, it is only a free offer. KDE supports all current window managers, but to get the full benefits it is recommended you use kwm. See the list of Features.

### Why can't I define new shortcuts for launching applications?

Answer: Because this is not the task of the window manager. However, you could write a small application who does this. Using the class KGlobalAccel from libkdecore, every KDE application has easy access to system wide shortcuts.

### Why does kwm look so much like Windows 95?

Answer: Ooops, does it? Let me see.... (Matthias trying to find somebody who has Windows 95 because he does not have Windows 95 on any his computers, ummm nobody has Windows 95 here. Well let's grab an old Linux distribution and install fvwm95-2.....) No, I can not verify that at all. KWM looks much prettier and offers more core window management functionality.

### Is it possible to add KDE extensions to other window managers?

Answer: Yes it is. You simply have to go through `kwm.h` and `kwm.C` from `libkdecore` and extend your favorite window manager to respond correctly to these requests. We got reports that some other window managers support some or most of the hints already.

### Does kwm support shaded windows a la OpenStep?

Answer: Yes.

## Epilogue

### Developer

`Matthias Ettrich`

### Authors

`Matthias Ettrich`

`Stephen Schaub` - Editor

`Kalle Dalheimer` - Editor

`Robert Williams` - Editor