User Manuals



wmtheme - window manager theme utility


wmtheme [options] [theme]
wmtheme -i|-I archive


wmtheme is a perl program to manage themes of popular window managers. It may be used to install, remove, and activate themes. It uses its invocation name to determine the appropriate window manager.

Support for some window managers may not be enabled in the default installation. To enable one, create the appropriate symbolic link to the wmtheme program. The following command would enable Golem support:

    ln -s `which wmtheme` ~/bin/gotheme

Window manager notes

Blackbox (bbtheme)
rootCommands using an unapproved utility, or containing characters ;|`&()<> will be disabled unless the configuration setting disable_rootcommands is set to no (see the configuration section for more information).

Blackbox themes aren't installed to their own directory. Because of this, any extra files like text files or fonts are normally discarded. Font files may be retained by enabling experimental font support: see the configuration section.

Enlightenment (etheme)
Theme archives must be tarred, gzipped files ending in .etheme. They will be extracted into a subdirectory of the appropriate theme directory.
Golem (gotheme)
GTK+ (gtktheme)
Only GTK+ version 2 themes are supported.
IceWM (itheme)
The themes submenu won't be updated until a theme is activated or the window manager is restarted.
Oroborus (ortheme)
Sawfish (sftheme)
Sawfish allows themes to exist as directories or tarballs, but wmtheme will always install them as tarballs.
Window Maker (wmtheme)
When installing, a theme will be repackaged into a name.themed directory.

Settings related to behavior, rather than appearance, will normally be removed from the style file during installation. This can be turned off by adding ``normalize_wmaker_styles no'' to the configuration file (see below for more about the configuration file).

xmms (xmtheme)
The Perl Xmms module is required for activation.


theme [theme...]
When a theme name is given with no options, it is activated. That is, an already installed theme is made visible. The \fBtheme\fP need not be exact. Multiple themes will be shown one after another, with prompting.
-b, --backout
Uninstall the most recently installed theme. May activate the favorite theme as well, depending on the configuration file.
-B, --backmany
Ask about uninstalling each recently installed theme in turn. May activate each theme as it's asked about, depending on the configuration file.
-f, --favorite [theme]
If a theme name is supplied, it is remembered as the favorite. Otherwise, the previously specified favorite theme is activated.
-h, --help
Displays a short help summary.
-i, --install archive
The specified archive file (e.g., a tarball) is evaluated. If the necessary files can be identified, the theme is installed according to the rules of the window manager. Finally, it is activated.
-I, --justinstall archive
Install a theme from an archive file as -i/--install, but do not activate it.
-l, --list
Shows a list of available, installed themes, under one or more of the following headings:
The theme is visible to all user accounts. Only root can install or uninstall such a theme.
The theme is installed for the current user only, and the current user can uninstall it.
The theme is installed for another user, but the window manager has been configured to make it available. The current user cannot uninstall it.
-r, --rename oldname newname
Rename a theme to newname. The old name need not be exact.
-R, --random
Activate a randomly chosen theme.
-u, --uninstall theme
Uninstall and permanently remove an installed theme. The name of the theme need not be exact. The user will be prompted if the given name matches more than one theme, and will be asked to verify this action.
-V, --version
Print the program's version.
-D, --debug
Enable debugging output.
--info [theme...]
Print the specified themes' (or all if none are supplied) update records in a humanly readable manner.
Creates the directory ~/.wmtheme and copies a sample configuration file into it. Theme installation/removal will then be recorded in a file in this directory, so that options -b, -B, and -f may be used. It's a good idea to edit ~/.wmtheme/conf soon after using this option.
Show every theme, one after the other, with the option to uninstall.


The file ~/.wmtheme/conf contains user preferences. Run wmtheme --setup to create the ~/.wmtheme directory and copy a sample configuration file into it.

The following settings apply to specific window managers:

Whether to strip settings from Window Maker styles that aren't related to appearance. Also, inserts a default value of 0 for the following three settings if the style doesn't specify them: MenuTextExtendSpace, MenuTitleExtendSpace, WindowTitleExtendSpace. This prevents a theme from modifying your focus behavior, among many other potential annoyances.

Default: yes

Whether to disable suspicious rootcommands found in Blackbox styles. A rootcommand is considered suspicious when its command isn't a recognized background setting utility (from the valid_rootcommands setting), and/or it contains any of these characters: ;|`&()<>. If this setting is ``yes'', such rootcommands will be commented out.

Default: yes

A space-delimited list of utilities which are ok to use when setting the background from a Blackbox theme. When the rootCommand uses something else, it will be considered suspicious.

Default: bsetbg bsetroot xv wmsetbg Esetroot xsetroot xpmroot

Whether to install GTK+ theme engines. It may be ``yes'', ``no'', or ``ask''.

Default: ask

Where to put any font files found when installing a theme. This setting is part of the experimental font support. See README.fonts for more information.

Default: font files remain in a theme's directory or archive (where they are useless), except that fonts found in Blackbox themes will be discarded.

A shell command to install fonts that were copied to tempfontdir.

Default: If any font files were copied to tempfontdir, a message will be printed.

The remaining settings are defined once per window manager, using wmtheme's invocation name to identify the WM. They appear in the following form:

   setting  invocation  value

The invocation may be ``default''.

Whether to confirm removing a theme when the -b/--backout option is used just after a theme was installed. This setting has no effect on subsequent backouts, which will always require confirmation.

Default: yes

Whether to activate the favorite theme when the -b/--backout option is used. For window managers that take a long time to switch themes, such as Enlightenment, it might be a good idea to say ``no'' here.

Default: no

Whether to activate each theme as it's presented for possible removal, during -B/--backmany.

Default: no


Additional program files and a sample configuration file, which is copied to ~/.wmtheme when the --setup option is used.
The user preferences configuration file.
List of recently installed themes, last action taken, some interactively set user preferences, and theme updating records.
A utility to cause GTK+ to reread its configuration files, in order to activate themes.


Some window managers may have several distinct themes of the same name, which can be individually selected. wmtheme will only recognize one of these.

Multiple conflicting installations of a window manager may leave global theme directories stranded, and may not change individual users' active theme directories. wmtheme checks for global directories starting with the location used by window managers' maintainer's source distributions. Since there is no good way to determine which global directory is in use by a particular user, cruft of this nature can result in a mismatch between what wmtheme thinks is installed, and what a user's theme selection menu displays.

Operations that depend on knowing whether the window manager is running work only in select operating systems. These include:

  * activation - all window managers
  * updating the theme/style menu - Enlightenment


Joshua Swink <yathster@yahoo.com>


blackbox(1), enlightenment(1), wmaker(1x), setstyle(1x), xmms(1)


June 12, 2004