IceWM Manual

Marko Macek
version 2.2.1, 2021 March 17


Introduction

This document is the manual for the IceWM X11 window manager. The IceWM manpages provide additional documentation.

The goal of IceWM is to provide a small, fast and familiar window manager for the X11 window system, which is compatible with the EWMH and ICCCM window manager protocols. Generally, it tries to make all functions available both by keyboard and by mouse (this is not currently possible when using mouse focus).

IceWM originally was designed to emulate the look of Motif, OS/2 Warp 4, OS/2 Warp 3 and Windows 95. Since it has a theming engine others styles are possible. A large number of original themes have been created and published by users.

Further information can be found at the IceWM website, at the current site of development, which includes the support requests.


Copying

IceWM and its documentation are covered by a GNU LGPL license, which is included in the distribution.


First steps

IceWM components

The IceWM suite consists of the following core applications provided by the main package:

Starting icewm

The icewm program alone is suitable for use with desktop environments like GNOME. If you wish to run the whole IceWM suite (WM, background changer, Docklet support, and startup/shutdown script handling), use the icewm-session binary instead of pure icewm. Note that this is not a complete Session Manager but it helps to automate the startup.

First make sure that you choose the correct X startup script in your home directory. For most distributions either the file $HOME/.xsession or $HOME/.xinitrc is honored by startx and X display managers like KDM. On RedHat, the $HOME/.Xclients may be used instead. In all cases, choose the one recommended by your distribution and make sure that there is no concurrency between the X startup scripts. Ensure that the script is executable. Mine looks something like this:

#!/bin/bash
# run profile to set $PATH and other env vars correctly
. $HOME/.bash_profile
# setup touchpad and the external mouse
xset m 7 2
xinput set-ptr-feedback 0 7 1.9 1

# start icewm-session
exec icewm-session
xterm

The xterm on the last line is there simply to make sure that your X session doesn’t crash if IceWM does (should never happen). You can restart IceWM from there or start some other window manager. The session will close if you close the xterm.

Startup and shutdown scripts

After initialization icewm-session will search the resource path for a startup script. If this file is found and if it is executable icewm-session will run this script. During termination of icewm-session the shutdown script is executed.

Example ~/.icewm/startup script:

#!/bin/bash

[ -x ~/.icewm/restart ] && source ~/.icewm/restart

gnome-terminal --geometry 80x25+217+235 &
xscreensaver &

On termination the shutdown script will be run first, then icewm-session will terminate icewm and icewmbg.

Tip

icewm-session is meant for easy desktop initialization and it is part of IceWM due to popular demand. For more sophisticated session management one could use a real session manager. IceWM supports the XSESSION protocol.

Extra session environment

Please note that if icewm-session is used as the only startup mechanism (without having .xsession involved), one can write additional environment settings into the file $HOME/.icewm/env. Expansion of simple shell style variables should be supported on most platforms. Shell command expansion is supported if wordexp was configured. This extra environment is only effective in applications started by icewm-session and their subprocesses.

Example env:

PATH=~/bin:$PATH
LANG=de_DE.UTF-8

Focus models

IceWM implements four general focus models:

Detailed configuration is possible using the configuration file options.


Mouse Commands

Frame Commands

Title Bar Commands

The Ctrl key can be used together with a mouse button to prevent a window from being raised to the top of the stack.

Taskbar commands


Keyboard Commands

The Alt key is assumed to be the key defined as the Mod1 modifier.


The Resource Path

IceWM looks in several locations for configuration information, themes and customization; together these locations are called the resource path. The resource path contains the following directories:

$ICEWM_PRIVCFG; $XDG_CONFIG_HOME/icewm; $HOME/.icewm The first of these which is defined and existent is used to search for the user’s personal customization.

/etc/icewm the system-wide defaults directory

/usr/share/icewm OR /usr/local/share/icewm the compiled-in default directory with default files

The directories are searched in the above order, so any file located in the system/install directory can be overridden by the user by creating the same directory hierarchy under $HOME/.icewm.

To customize icewm yourself, you could create the $HOME/.icewm directory and copy the files that you wish to modify, like preferences, keys or winoptions, from /etc/icewm, /usr/share/icewm or /usr/local/share/icewm and then modify as you like.

To customize the default themes, create the $HOME/.icewm/themes directory and copy all the theme files there and then modify as necessary. Each theme has its own subdirectory. Themes can be downloaded from https://themes.ice-wm.org.


Configuration Files

IceWM uses the following configuration files:


Theme

The theme file contains the currently selected theme. It will be overwritten automatically when a theme is selected from the Themes menu.


Preferences

This section shows preferences that can be set in preferences. Themes will not be able to override these settings. Default values are shown following the equal sign.

Focus and Behavior

The following settings can be set to value 1 (enabled) or value 0 (disabled).

Terminal emulator must accept -e option.

Quick Switch List

Edge Workspace Switching

Task Bar

The following settings can be set to value 1 (enabled) or value 0 (disabled).

Mailbox Monitoring (updated 2018-03-04)

This may contain a list of mailbox specifications. Mailboxes are separated by a space. If TaskBarShowMailboxStatus is enabled then IceWM will monitor each mailbox for status changes each MailCheckDelay seconds. For each mailbox IceWM will show an icon on the taskbar. The icon shows if there is mail, if there is unread mail, or if there is new mail. Hovering the mouse pointer over an icon shows the number of messages in this mailbox and also the number of unread mails. A mailbox can be the path to a file in conventional mbox format. If the path points to a directory then Maildir format is assumed. Remote mail boxes are specified by an URL using the Common Internet Scheme Syntax (RFC 1738):

scheme://user:password@server[:port][/path]

Supported schemes are pop3, pop3s, imap, imaps and file. The pop3s and imaps schemes depend on the presence of the openssl command for TLS/SSL encryption. This is also the case if port is either 993 for imap or 995 for pop3. When the scheme is omitted then file is assumed. IMAP subfolders can be given by the path component. Reserved characters like slash, at and colon can be specified using escape sequences with a hexadecimal encoding like %2f for the slash or %40 for the at sign. For example:

file:///var/spool/mail/captnmark
file:///home/captnmark/Maildir/
pop3://markus:%2f%40%3a@maol.ch/
pop3s://markus:password@pop.gmail.com/
imap://mathias@localhost/INBOX.Maillisten.icewm-user
imaps://mathias:password@imap.gmail.com/INBOX

To help solve network protocol errors for pop3 and imap set the environment variable ICEWM_MAILCHECK_TRACE. IceWM will then log communication details for POP3 and IMAP mailboxes. Just set export ICEWM_MAILCHECK_TRACE=1 before executing icewm, or set this in the env configuration file.

Note that for IceWM to access Gmail you must first configure your Gmail account to enable POP3 or IMAP access. To allow non-Gmail applications like IceWM to use it see the Gmail help site for "Let less secure apps use your account". Also set secure file permissions on your IceWM preferences file and the directory which contains it. It is unwise to store a password on file ever. Consider a wallet extension for IceWM. The following Perl snippet demonstrates how to hex encode a password like !p@a%s&s~:

perl -e 'foreach(split("", $ARGV[0])) { printf "%%%02x", ord($_);  }; print "\n";' '!p@a%s&s~'
%21%40%23%24%25%5e%26%2a%7e

Menus

Timings

Buttons and Keys

Workspaces

Paths

Programs

Window Menus

WinMenuItems Items to show in the window menus, possible values are:


Theme Settings

This section shows settings that can be set in theme files. They can also be set in preferences file but themes will override the values set there. To override the theme values the settings should be set in prefoverride file. Default values are shown following the equal sign.

Borders

The following settings can be set to a numeric value.

Fonts

The following settings can be set to a string value.

When IceWM is configured with --enable-xfreetype, only the settings with "Xft" suffix will be used. They specifiy the font name in fontconfig format:

MenuFontNameXft="sans-serif:size=12:bold"

Colors

Desktop Background

The following options are used by icewmbg:

Task Bar Style


Menus and Toolbar (updated 2018-05-06)

menu

Within the menu configuration file you can configure which programs are to appear in the root/start menu.

Submenus can be created with:

menu "title" icon_name {
# contained items
}
separator
menufile "title" icon_name filename
menuprog "title" icon_name program arguments
menuprogreload "title" icon_name timeout program arguments
include filename
includeprog program arguments

Menus can be populated with submenus and with program entries as explained below for the program configuration file. Comments start with a #-sign.

The menufile directive creates a submenu with a title and an icon, while menuprog and menuprogreload create a submenu with entries from the output of program arguments where the timeout of menuprogreload says to reload the submenu after the timeout expires. The include statement loads more configuration from the given filename, while includeprog runs program arguments to parse the output.

toolbar

The toolbar configuration file is used to put programs as buttons on the taskbar. It uses the same syntax as the menu file.

programs

Usually automatically generated menu configuration file of installed programs. The programs file should be automatically generated by wmconfig (Redhat), menu (Debian), or icewm-menu-fdo.

Programs can be added using the following syntax:

prog "title" icon_name program_executable options

Restarting another window manager can be done using the restart program:

restart "title" icon_name program_executable options

icon_name can be - if icon is not wanted, or ! if the icon name shall be guessed by checking the command (i.e. the real executable file, following symlinks as needed).

The "runonce" keyword allows to launch an application only when no window has the WM_CLASS hint specified. Otherwise the first window having this class hint is mapped and raised. Syntax:

runonce "title" icon_name "res_name.res_class" program_executable
options
runonce "title" icon_name "res_name" program_executable options
runonce "title" icon_name ".res_class" program_executable options

The class hint of an application window can be figured out by running

xprop WM_CLASS

Submenus can be added using the same keywords as the menu configuration file.

Only double quotes are interpreted by IceWM. IceWM doesn’t run the shell automatically, so you may have to do that.


Hot Keys

IceWM allows launching of arbitrary programs with any key combination. This is configured in the keys file. The syntax of this file is like:

key "key combination" program options…

For example:

key  "Alt+Ctrl+t"  xterm -rv
key "Ctrl+Shift+r" icewm --restart
runonce "Alt+F12"  "res_name.res_class" program_executable options

Window Options (updated 2018-03-04)

The winoptions file is used to configure settings for individual application windows. Each line in this file must have one of the following formats:

The last format sets a default option value for all windows. Each window on the desktop should have name and class resources associated with it. Some applications also have a window role resource. They can be determined using the xprop utility. When used on a toplevel window, xprop | grep -e CLASS -e ROLE should output a line like this:

WM_CLASS = "name", "Class"

and may also display a line like this:

WM_WINDOW_ROLE = "window role"

It’s possible that an application’s name and/or class contains a dot character (.), which is also used by IceWM to separate name, class and role values. In this case precede the dot with the backslash character. In the following example, we suppose an application’s window has the.name as its name value and The.Class as its class value and for this combination we set option to argument.

the\.name.The\.Class.option: argument

Options that can be set per window are as follows:


Icon handling

Generic

The window manager expects to find two XPM files for each icon specified in the configuration files as ICON. They should be named like this:

Other pixmap sizes like 20x20, 24x24, 40x40, 48x48, 64x64 might be used in the future. Perhaps we need a file format that can contain more than one image (with different sizes and color depths) like Windows’95 and OS/2 .ICO files.

It would be nice to have a feature from OS/2 that varies the icon size with screen resolution (16x16 and 32x32 icons are quite small on 4000x4000 screens ;-)

GDK-Pixbuf

When icewm was configured with the --enable-gdk-pixbuf option all of GdkPixbuf’s image formats are supported. Use them by specifying the full filename or an absolute path:


Mouse cursors

IceWM scans the theme and configuration directories for a subdirectory called cursors containing monochrome but transparent XPM files. To change the mouse cursor you have to use this filenames:


Themes

Themes are used to configure the way the window manager looks. Things like fonts, colors, border sizes, button pixmaps can be configured. Put together they form a theme.

Theme files are searched in the themes subdirectories.

These directories contain other directories that contain related theme files and their .xpm files. Each theme file specifies fonts, colors, border sizes, …

The theme to use is specified in ~/.icewm/theme file:

If the theme directory contains a file named fonts.dir created by mkfontdir the theme directory is inserted into the X servers font search path.

www.box-look.org has a very large number of themes which were created by users of IceWM.


Command Line Options

icewm supports the following options:

-d, --display=NAME
NAME of the X server to use.

--client-id=ID
Client id to use when contacting session manager.

--sync
Synchronize X11 commands.

-c, --config=FILE
Load preferences from FILE.

-t, --theme=FILE
Load theme from FILE.

--postpreferences
Print preferences after all processing.

-V, --version
Prints version information and exits.

-h, --help
Prints this usage screen and exits.

--replace
Replace an existing window manager.

-r, --restart
Tell the running icewm to restart itself.

--configured
Print the compile time configuration.

--directories
Print the configuration directories.

-l, --list-themes
Print a list of all available themes.

The restart option can be used to reload the IceWM configuration after modifications. It is the preferred way to restart IceWM from the command line or in scripts. To load a different theme from the command line, combine this with the --theme=NAME option like:

icewm -r -t CrystalBlue

The theme name will then be saved to the theme configuration file, before restarting IceWM.


Glossary

Resource Path A set of directories used by IceWM to locate resources like configuration files, themes, icons. See section The Resource Path.


Authors

Authors having contributed to this document include Gallium, Macek, Hasselmann, Gijsbers, Bidulock and Bloch.


See Also

icehelp(1), icesh(1), icesound(1), icewm-env(5), icewm-focus_mode(5), icewm-keys(5), icewm-menu-fdo(1), icewm-menu(5), icewm-preferences(5), icewm-prefoverride(5), icewm-programs(5), icewm-session(1), icewm-set-gnomewm(1), icewm-shutdown(5), icewm-startup(5), icewm-theme(5), icewm-toolbar(5), icewm-winoptions(5), icewm(1), icewmbg(1), icewmhint(1), icewmtray(1).


Version 2.2.1
Last updated 2023-04-09 21:35:26 UTC