wmtheme(1)

NAME
wmtheme - window manager theme utility

SYNOPSIS
wmtheme [-D] [-d|-f|-g|-r|-u] theme
wmtheme [-D] -i|-I archive
wmtheme [-D] [-h|-l|-V|-f|-b|-B|-R|--setup|--manage]

DESCRIPTION
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 AfterStep:
    ln -s `which wmtheme` ~/bin/astheme Window manager notes
AfterStep (astheme) 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)
    Unlike the other invocations, gtktheme cannot be used by root. The insecurity of compiling and installing GTK theme engines is just too great. It will in fact refuse to do anything as root. Therefore, in order to install the engines as a user, the directory ~/.themes/theme-engines will be created to hold them. Theme engines will be installed if and only if they are provided in source form with a configure script. Also, confirmation will normally be required first. The configuration file setting "install_gtk_engines" can be set so that they will be installed without asking, or ignored.
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.

OPTIONS

theme [theme...]
    When a theme name is given with no options, it is activated. That is, an already installed theme is made visible. The theme 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 (i.e., 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:

    Global
        The theme is visible to all user accounts. Only root can install or uninstall such a theme.

    Local
        The theme is installed for the current user only, and the current user can uninstall it.

    (username)
        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 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.

--setup
    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.

--review
    Show every theme, one after the other, with the option to uninstall.

CONFIGURATION
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:

normalize_wmaker_styles
    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

disable_rootcommands
    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 ;|`&()<>. If this setting is "yes", such rootcommands will be commented out.
    Default: yes

valid_rootcommands
    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

install_gtk_engines
    Whether to install GTK+ theme engines. It may be "yes", "no", or "ask".
    Default: ask

tempfontdir
    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.

installfontcmd
    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_name value
The invocation name may be "default".

confirm_first_backout
    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

set_favorite_on_backout
    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

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

version_mismatch
    What to do when downloading with -d or -g, and themes are found which may be incompatible with the current window manager version. The value may be "ask", to ask the user whether to install it or not, "no", to just quit, or "yes", to install themes without regard to possible version problems. When more than one theme is found, a "no" value will prevent any questionable ones from appearing in the choice list.
    Default: ask

FILES

/usr/lib/wmtheme/*
    Additional program files and a sample configuration file, which is copied to ~/.wmtheme when the --setup option is used.

~/.wmtheme/conf
    The user preferences configuration file.

~/.wmtheme/*.data
    List of recently installed themes, last action taken, some interactively set user preferences, and theme updating records.

/usr/bin/apply-gtk-theme
    A utility to cause GTK+ to reread its configuration files, in order to activate themes.

BUGS
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

AUTHOR
Joshua Swink <jswink@pacbell.net>

SEE ALSO
afterstep(1x), blackbox(1), enlightenment(1), wmaker(1x), setstyle(1x), xmms(1)