<!DOCTYPE LINUXDOC SYSTEM>

<ARTICLE>

<TITLE>IceWM FAQ and Howto

<AUTHOR>
  Adam Pribyl, <HTMLURL URL="mailto:covex@ahoj.fsik.cvut.cz" NAME="covex@ahoj.fsik.cvut.cz">,
  <INST>Markus Ackermann, <HTMLURL URL="mailto:maol@gmx.net" NAME="maol@gmx.net">,
  <NEWLINE>
  Josef 'Jupp' Schugt, <HTMLURL URL="mailto:jupp@themes.org" NAME="jupp@themes.org">


<DATE>2004/03/01, 22:28 CEST

<ABSTRACT>
  This is the FAQ and Howto for the IceWindowManager (IceWM).
  The latest version of this FAQ is available
  at <HTMLURL URL="http://www.icewm.org/FAQ/" NAME="http://www.icewm.org/FAQ/">. At the same site is also <HTMLURL URL="IceWM-FAQ.sgml" NAME="SGML source">.
</ABSTRACT>

<TOC>


<SECT>General FAQ - ReadMeFirst

<P>
As IceWM is lightwieght it still does a lot. <BF>If you are looking for
some option go throught <EM>preferences</EM> file.</BF> It is well constructed
and you usually find what you are searching - e.g. you want to change some
quickswitch option then try to grep &quot;QuickSwitch&quot; from preferences.
Therefore it makes no sense to describe all of the preferences here.

<SECT1>Fulltext search
<P>
If you want fulltext search of this FAQ use a
<HTMLURL URL="IceWM-FAQ.txt" NAME="text version">.

<SECT1>The most Frequently Asked Questions with short answers

<P>
This is list of the most frequently asked quiestions with short answers.
Usually you can find more explaining answer in following chapers.

<SECT2>IceWM does not start icewmbg, startup etc. How should I start IceWM? <REF ID="icewmsess" name="icewm-session">
<SECT2>Is that possible to place icons on desktop using PURE IceWM? <REF ID="iconsondesk" name="No.">
<SECT2>Where are icewm files? <REF ID="conffiles" name="Depends - locate *icewm.">
<SECT2>How to change default theme? <REF ID="theme" name=".icewm/theme">, Theme="thenicest/default.theme".
<SECT2>Does IceWM knows dynamicly created desktops or 2D desktops? No.
<SECT2>Is there a way to group similar applications in the toolbar when minimized? No.
<SECT2>How can I disable the taskbar (or toolbar) in IceWM? preferences, ShowTaskBar=0
<SECT2>Is there any way to have the time and date show in the taskbar? <REF ID="timeformat" name="Yes. man date || strftime">
<SECT2>Is there a button to minimize all windows?  IceWM > 1.2.13 TaskBarShowShowDesktopButton or use alt+shift+F9.
<SECT2>How can I autostart apps at X && IceWM start? Use .Xsession || .xinitrc || .Xclients || <REF ID="startup" name=".icewm/startup.">
<SECT2>Is it possible to add submenus to the menu? <REF ID="menu" name="Yes. file menu; format: menu name icon {content}.">


<SECT>Introduction

<P>
In this section I give a short description of what IceWM is.

<SECT1>What is IceWM?

<P>
IceWM is a <BF>window manager for</BF> the <BF>X</BF> window system.
It is designed to be <BF>small, fast, lightweight,</BF> and to
emulate the <BF>look and feel of Motif, OS/2 and Windows.</BF>

While it is <BF>very configurable,</BF> it is not pathologically so
(like Enlightenment or FVWM). In short, IceWM provides a
<BF>customizable look</BF> with a relatively <BF>consistent
feel.</BF>

Now that you know what IceWM is and are still reading on you are
obviously interested in using it. To use a program you will first
need to have it. The obvious question is:

<SECT1>Where to get it?

<P>
Marko Macek (the author of IceWM) maintains a web page from which you
can download the latest development version as well as a
<EM>frozen</EM> version. It is located at

<TSCREEN>
    <HTMLURL URL="http://www.icewm.org"
    NAME="http://www.icewm.org">
</TSCREEN>

<SECT1>Under which operating systems does it run?

<P>
IceWM successfully ran under (in alphabetical order):

<ITEMIZE>
  <ITEM><BF>AIX 4.3.3</BF> (reported by <HTMLURL
  URL="mailto:griswold@acm.org" NAME="griswold@acm.org">)
  <ITEM><BF>Digital Unix (Compaq Tru64 Unix)</BF>
  <ITEM><BF>FreeBSD</BF>
        (reported by MJ Ray, <HTMLURL URL="mailto:h089@mth.uea.ac.uk"
        NAME="h089@mth.uea.ac.uk">)
  <ITEM><BF>Linux on DEC Alpha (64 bit architecture)</BF>
  <ITEM><BF>Linux on Intel compatibles (32 bit architecture)</BF>
  <ITEM><BF>NetBSD</BF>
        (reported by MJ Ray, <HTMLURL URL="mailto:h089@mth.uea.ac.uk"
        NAME="h089@mth.uea.ac.uk">)
  <ITEM><BF>OpenBSD</BF>
        (reported by MJ Ray, <HTMLURL URL="mailto:h089@mth.uea.ac.uk"
        NAME="h089@mth.uea.ac.uk">)
  <ITEM><BF>OS/2</BF>
  <ITEM><BF>Solaris</BF>
        (reported by MJ Ray, <HTMLURL URL="mailto:h089@mth.uea.ac.uk"
        NAME="h089@mth.uea.ac.uk">)
  <ITEM><BF>Windows</BF>
        (reported by Pavel Roskin, <HTMLURL
        URL="mailto:pavel_roskin@geocities.com"
        NAME="pavel_roskin@geocities.com">)
</ITEMIZE>

<SECT1>Minimal Requirements

<P>
A default IceWM installation just depends on the X window system (any X
window system will do, no matter how old or from which vendor)  and libXpm
and therefore should run sufficiently fast even on an old 386, a sparc IPC
or any other box capable of running X. For some of the nifty features like
shaped borders, gradient frames and gradient menus it might help to have a
computer which is slightly faster or which doesn't have an ancient X
version.

<SECT>Installation

<P>
Now you have the IceWM source package at hand and will want to
install it. So the next question will be:

<SECT1>How to install IceWM from RPM

<P>
The IceWM developers provide RPM packages for all new releases independently
from the distributions which use this package format. IceWM's RPM
distribution is split into several files. You need icewm-x.y.z-v.rpm.
Optionaly you can download others like icewm-themes, icewm-l10n and
icewm-menu-gnome.


<SECT1>How to compile and install IceWM from source?

<P>
IceWM (0.9.3x and up) uses the standard
GNU autoconf tool, so installation of IceWM is much the same as the
installation of any other package that uses this tool.

First you <BF>untar</BF> the package using

<TSCREEN><VERB>
    tar xzf icewm-1.2.x.tar.gz
</VERB></TSCREEN>

then you <BF>change</BF> to the created <BF>directory</BF> using

<TSCREEN><VERB>
    cd icewm-1.2.x
</VERB></TSCREEN>

IceWM comes with a configure script that can be supplied with several
compile-time options. To see them listed use

<TSCREEN><VERB>
    ./configure --help
</VERB></TSCREEN>

Some important options are

<DESCRIP>
  <TAG>--prefix</TAG>
    directory under which IceWM files are to be installed
  <TAG>--with-xpm</TAG>
    use the standard X pixmap package to render graphics
  <TAG>--with-imlib</TAG>
    use the more powerful imlib package to render images
  <TAG>--with-gnome-menus</TAG>
    automatically add the GNOME menus to the IceWM
    <TT>start</TT> menu
</DESCRIP>

After you have decided which (if any) options you want to set,
<BF>run</BF> the <TT>configure</TT> script:

<TSCREEN><VERB>
    ./configure [option ...]
</VERB></TSCREEN>

Assuming that the configure script exited successfully, you should
then <BF>compile</BF> IceWM using

<TSCREEN><VERB>
    make
</VERB></TSCREEN>

which will build IceWM with the options specified by the configure
script. If everything compiles successfully, you can now
<BF>install</BF> IceWM on your machine by entering

<TSCREEN><VERB>
    make install
</VERB></TSCREEN>

<BF>Note:</BF> To do so you will typically need to become
<BF>root</BF> (at least if you didn't supply an install directory you
as a user have write access to - this you can change in Makefile).

Now you have an IceWM binary sitting on your disk. Is that what you
really want? Obviously not, you want to <EM>run</EM> IceWM. The next
section describes how to set up IceWM as your default window manager.


<SECT1>How to make IceWM my default window manager?<LABEL ID="defwm">

<P>
In order to run IceWM, you must <BF>assure</BF> that the
<BF>executable</BF> (called <TT>icewm</TT>) <BF>is
in</BF> your <BF>path.</BF> You should then <BF>add IceWM to</BF>
your <BF>X start-up script</BF> (which could be
<TT>.xinitrc</TT>, <TT>.xsession</TT> or
<TT>.Xclients</TT>).

<BF>Note:</BF> Supplying the full path to IceWM isn't sufficient - if
IceWM isn't in your path, restarting it will fail (even if you don't do
this by hand it is done automatically on changing the theme).

Which of the scripts mentioned above is the right one mainly depends
on whether you manually start X (using <TT>startx</TT>)
or have X running all the time.

First I explain what you need to do if you manually start X. Then I
address the case &quot;X is running all the time&quot; (which means
that you log in via <TT>xdm</TT> or something like that).
Finally I describe what both cases have in common.

<SECT2>Running IceWM at X startup

<P>
If you use <TT>startx</TT> to start up X then you run
your window manager from the <TT>.xinitrc</TT> file.

<SECT2>Running IceWM after graphical login

<P>
If your system has a graphical login (X is already running while you
log in) you are using a display manager such as
<TT>xdm</TT>, <TT>kdm</TT> or
<TT>gdm</TT>. In this case <TT>.xinitrc</TT>
has no effect (it is not read in by <TT>xdm</TT>). You
must instead use a <TT>.xsession</TT> file.

<BF>Hint:</BF> It is absolutely no problem to have a
<TT>.xsession</TT> and a <TT>.xinitrc</TT>
file (which is especially useful for inhomogeneous networks).

Mandrake users repeatedly reported that their <TT>.xsession</TT> wasn't read
and no applications started. To work around that in the <TT>kdm</TT> login
interface choose <TT>Default</TT> and add IceWM as the last
entry to your <TT>.xsession</TT>.

<SECT2>Besides the differences

<P>
You might have noticed that - besides being  used in different
cases - <TT>.xsession</TT> and
<TT>.xinitrc</TT> are essentially the same. On some
systems they are in fact the very same file which is called
<TT>.Xclients</TT> with <TT>.xinitrc</TT> and
<TT>.xsession</TT> both being symbolic links to this
file.

Irrespective which start script you use (<TT>.xsession</TT>,
<TT>.xinitrc</TT> or <TT>.Xclients</TT>) it must
be executable. This may be achieved by issuing the following command:

<TSCREEN><VERB>
    chmod u+x ~/.filename
</VERB></TSCREEN>

A minimalist's start-up file consists of only the command to start
the window manager (in our case <TT>icewm</TT>). Most geeky people
add other stuff to the file to make it look more complicated and
confuse beginners &gt;;-&gt;

Though that may be the reason for some of us, the greater majority
add commands to customize X and to start some programs on login
(typical example: an <TT>xterm</TT>)

The following is a (reasonable) <TT>.xinitrc</TT> file
used as an example by Marko:

<TSCREEN><VERB>
    #-----------------------------------------------------------
    # .xinitrc
    #-----------------------------------------------------------

    # run profile to set $PATH and other env vars correctly
    . $HOME/.bash_profile

    # setup background
    xsetroot -solid '#056'

    # setup mouse acceleration
    xset m 7 2

    # run initial programs
    xterm &

    # start icewm, and run xterm if it crashes (just to be safe)
    exec icewm || exec xterm -fg red

    #-----------------------------------------------------------
</VERB></TSCREEN>

<BF>Note:</BF> To run IceWM, the <TT>icewm</TT> command
needs to be executed. This means that all programs that are run
before starting <TT>icewm</TT> either have to terminate
immediately or to run in background. Also, don't
<TT>exec</TT> them because that terminates execution of
<TT>.xinitrc.</TT>

<SECT2>IceWM > 1.2.13<LABEL ID="icewmsess">

<P>
Beginning with IceWM 1.2.13 there is a binary <TT>icewm-session</TT>.
This binary helps you to handle all IceWM subparts (icewmbg, icewm, icewmtray, startup, shutdown started in this order).
Therefore you can use <TT>icewm-session</TT> to start IceWM.
<TT>icewm</TT> now starts only window manager itself.

<P>
If you want to start only some parts of the IceWM, then you can add them to 
your <TT>.xsession</TT> or similar file before <TT>exec icewm</TT>, otherwise it is 
enough to use only <TT>exec icewm-session</TT>.

<SECT>Configuration

<P>
Congratulations! Now you have IceWM up and running. You don't like
the default look? Don't worry: This section is on customizing IceWM.

As it is the case with most Linux and Unix programs IceWM can be
configured using plain text config files. 

<SECT1>You mean I have to edit these files?

<P>There is a lot of utilities nowadays. See utilities section -
<REF ID="tools4icewm" name="Tools for IceWM">.
<P>
The config files need to be changed if you want to change IceWM's
behavior.  This does not necessarily mean that you have to use an
editor for this - graphical configuration tools for IceWM are
available, although IceWM doesn't feature in-built configuration. More
about these tools in the Utilities section. 
Still hand editing of these files is most effective and you can find even more
than you are looking for.
To notify IceWM about the
changes you've made just send it a SIGHUP or restart it from the Logout
menu.

<SECT1>Where are the configuration files?<LABEL ID="conffiles">

<P>
You could not find the config files? Maybe you were looking in wrong
places - the location depends upon the method you used to install
IceWM.

In a plain vanilla source install, the global version of the files
will be located in <TT>/usr/local/lib/Xll/icewm/</TT>. If
you installed the standard RPM, they will be in
<TT>/usr/X11R6/lib/X11/icewm/</TT> or <TT>/usr/local/share/icewm</TT>. The system wide
configuration files for the Debian package seem to be in
<TT>/etc/X11/icewm/</TT>.

However, if you wish to make a configuration of your own you should
not edit these global config files but create a subdirectory of your
home directory called <TT>~/.icewm/</TT>. Copy the system
wide files to your local <TT>.icewm</TT> directory and
edit these copies.

<BF>Note:</BF> You may have to alter the permissions of the copies in
order to read and write to them.

<SECT1>The configuration files

<P>
You can customize IceWM by editing the following configuration files:

<DESCRIP>
  <TAG><TT>&quot;menu&quot;</TT></TAG>
    Controls the contents of the <TT>start</TT> menu
  <TAG><TT>&quot;preferences&quot;</TT></TAG>
    Controls the general behavior of IceWM
  <TAG><TT>&quot;keys&quot;</TT></TAG>
    Controls which additional key combos are available to users
  <TAG><TT>&quot;toolbar&quot;</TT></TAG>
    Controls the row of launcher icons on the taskbar and has the
    same syntax as the menu file
  <TAG><TT>&quot;winoptions&quot;</TT></TAG>
    Controls the behavior of individual applications (as identified
    by the names of their respective windows)
  <TAG><TT>&quot;startup&quot;</TT></TAG>
    Applications that should be started at IceWM startup.
  <TAG><TT>&quot;theme&quot;</TT></TAG>
    IceWM theme path/name. 
  <TAG><TT>&quot;prefoverride&quot;</TT></TAG>
    To override theme preferences.
</DESCRIP>

<SECT2>menu<LABEL ID="menu">

<P>
The <TT>menu</TT> file controls the contents in your menu (You knew that,
right?). It has the following syntax:

<TSCREEN><VERB>
    prog Program Icon app -with -options
</VERB></TSCREEN>

<VERB>prog</VERB> is a keyword, telling IceWM that it's a program entry. Other keywords
are <VERB>separator</VERB> to draw a separator and <VERB>menu Xyz folder_icon {
  prog ...
}</VERB> to open a new sub menu called Xyz. <VERB>Program</VERB> is
the name which will be shown in the menu. Enclose it in apostrophes if you
need more than one word here. <VERB>Icon</VERB> will be used as the menu
entry's icon, if a corresponding image is found in IceWM's IconSearchPath.
And finally <VERB>app -with -options</VERB> is what's going to be started if
a user chooses this entry.

<P>
Note that the menu only shows entries which are found in your PATH, IceWM is
clever enough to omit non-usable entries.

<SECT2>preferences

<P>
The <TT>preferences</TT> file is the main configuration file. The default
file is pretty much self documenting, so go and have a look. In case you
ever wondered about themes: they can define all the options you can use in
this file - and their definitions <BF>override</BF> all your personal customization!

<SECT2>keys

<P>
In the <TT>keys</TT> file one can define shortcuts for starting programs.
The existing entries make clear what one has to define.

<SECT2>toolbar

<P>
The <TT>toolbar</TT> file defines some buttons which can be clicked next to
the menu in the toolbar. It uses the same format as the menu file. 
You can also have folders in the toolbar. The easiest way to do that 
is simply by copying a menu from the /menu file over to the /toolbar file. 

<SECT2>winoptions

<P>
The <TT>winoptions</TT> file can be used to define the appearance of X
applications like on which desktop they should appear, if should have a
border, menu, titlebar, etc.

<SECT2>startup<LABEL ID="startup">

<P>
The <TT>startup</TT> file can list apps you want to start at IceWM startup.
It can look like this:
<TSCREEN><VERB>
idesk& 
(sleep 2; psi&)&
</VERB></TSCREEN>
Do not forget to make this file executable
<TSCREEN><VERB>
chmod +x startup
</VERB></TSCREEN>
Note: Do not put shell specification (like #!/bin/bash) on the beginning of the file.
Also make sure all applications are starting at background (&).

<SECT2>theme<LABEL ID="theme">

<P>
The <TT>theme</TT> file is new from IceWM 1.2.10. It specifies which 
theme should be used
<TSCREEN><VERB>
Theme=myfavorittheme/default.theme
#Theme=myfavorittheme/default.theme
</VERB></TSCREEN>

# contains theme history. 

<P>
The <TT>theme</TT> file is changed every time you 
switch theme in menu and selected theme is therefore used after IceWM restart.

<SECT2>prefoverride

<P>
The <TT>prefoverride</TT> file is new from IceWM 1.2.12. In this file you can
specify any preference which will override any preference specified by theme or 
anything else. This is introduced to solve troubles with order of preferences 
interpretation and give a usr possibility to customize global things he wants to
have allways same.


<SECT>Customizing The Behavior

<P>
IceWM's reactions on your actions can be pretty much configured as you like
it. You can choose which focus model you like, what should happen on
mouse clicks on the titlebars, or which mouse button calls which menu when
clicked on the desktop.

<SECT1>What are the focus models good for?

<P>
To answer this question it is a good idea to first take a look at the
four general focus models that are implemented by IceWM:

<DESCRIP>
  <TAG><TT>ClickToRaise</TT></TAG>
    When a window is clicked, it is raised and activated. This is the
    behavior of Win95 and OS/2.
  <TAG><TT>ClickToFocus</TT></TAG>
    A Window is raised and focused when titlebar or frame border is
    clicked and it is focused but not raised when the window interior
    is clicked.
  <TAG><TT>PointerFocus</TT></TAG>
    When the mouse is moved, focus is set to window the mouse is
    pointing at. It should be possible to change the focus with the
    keyboard when the mouse is not moved.
  <TAG><TT>ExplicitFocus</TT></TAG>
    When a window is clicked, it is activated but not raised. New
    windows do not automatically get the focus unless they are
    transient windows for the active window.
</DESCRIP>

<EM>&quot;A window is raised&quot;</EM> is telling and needs no
further explanation.

<EM>&quot;A window is activated, is focused, gets the
focus,...&quot;</EM> means that input (e. g. keystrokes) now are sent
to that window.

<BF>In short:</BF> The focus model controls what you have to do to
make a window pop up and to have it listen to what you type.

<SECT1>Use UseRootButtons and ButtonRaiseMask

<P>
<TT>UseRootButtons</TT> and
<TT>ButtonRaiseMask</TT> are so called <BF>bitmask
options.</BF>

This concept is e.g. used by <TT>chmod</TT> where
<TT>&quot;4&quot;</TT> stands for read access, <TT>&quot;2&quot;</TT>
for write access and <TT>&quot;1&quot;</TT> for execute (or change
directory) access and you add up the relevant numbers to control the
file access.

As far as <TT>UseRootButtons</TT> and
<TT>ButtonRaiseMask</TT> are concerned,
<TT>&quot;1&quot;</TT> stands for the first mouse button,
<TT>&quot;2&quot;</TT> for the second one and <TT>&quot;4&quot;</TT>
for the third one. The following list shows which number stands for
which combination of mouse buttons:

<TSCREEN><VERB>
    ---------------------------------
     Value   Stands for
    ---------------------------------
       0     No mouse button at all
       1     Button 1
       2     Button 2
       3     Buttons 1 and 2
       4     Buttons 3
       5     Buttons 1 and 3
       6     Buttons 2 and 3
       7     All three mouse buttons
    ---------------------------------
</VERB></TSCREEN>

Any value greater than seven has the same effect as seven.
<TT>UseRootButtons</TT> controls which buttons call up a
menu when clicked on an unoccupied region of the desktop.
<TT>ButtonRaiseMask</TT> determines which buttons will
raise a window when clicked on that window's title bar.

<SECT1>Set the mouse button a menu which is bound to

<P>
There is an option for each of the root menus which controls which
button is bound to that menu.

<TSCREEN><VERB>
    -----------------------------------------
     Option Name            Controls
    -----------------------------------------
     DesktopWinMenuButton   Window menu
     DesktopWinListButton   Window list
     DesktopMenuButton      Application menu
    -----------------------------------------
</VERB></TSCREEN>

<P>
The value of each option determines the button to which the
corresponding menu is bound according to the following scheme:

<TSCREEN><VERB>
    -----------------------------
     Value   Stands for
    -----------------------------
       0     No mouse button
       1     Left mouse button
       2     Right mouse button
       3     Middle mouse button
      4-6    Other buttons
    -----------------------------
</VERB></TSCREEN>

<SECT1>Setting the lock command<LABEL ID="locking">

<P>
By default IceWM uses <TT>xlock</TT> (without any
argument) to lock your screen. There may be several reasons for using
a different lock command:

<ITEMIZE>
  <ITEM>
    There is no <TT>xlock</TT> on your machine.
  <ITEM>
    <TT>xlock</TT> tends to crash on your machine either
    leaving you locked out (best case) or unlocking your session
    (worst case).
  <ITEM>
    <TT>xlock</TT> has some CPU intensive modes compiled in that
    interfere with your SETI@HOME session.
</ITEMIZE>

It is very easy to set a lock command: Simply add

<TSCREEN><VERB>
    LockCommand=&quot;xlock -mode blank&quot;
</VERB></TSCREEN>

to your <TT>$HOME/.icewm/preferences</TT> and
<TT>xlock</TT> will run in <TT>blank</TT> mode (which
shows nothing but a black screen).

The example was chosen on purpose: Using this mode you have the best
chance of your monitor going asleep (enter power saving mode).

<SECT1>Can the taskbar applet monitor ethernet (or isdn) instead of my modem?

<P>
In the <TT>preferences</TT> file just change the option
<TT>NetworkStatusDevice</TT> to read

<TSCREEN><VERB>
    NetworkStatusDevice=&quot;eth0&quot;
</VERB></TSCREEN>

Replace <TT>&quot;eth0&quot;</TT> by <TT>&quot;ippp0&quot;</TT> to monitor
ISDN connections. AFAIK eth0 support is limited to Linux and *BSD since
commercial Unices tend to use another format for their network interfaces.

<SECT1>Can the taskbar applet monitor more devices?

<P> 
In the <TT>preferences</TT> file just change the option
<TT>NetworkStatusDevice</TT> to read

<TSCREEN><VERB>
    NetworkStatusDevice=&quot;eth0&quot;
</VERB></TSCREEN>

Replace <TT>&quot;eth0&quot;</TT> by <TT>&quot;eth0 ppp0&quot;</TT> to monitor
eth0 and ppp0.


<SECT1>I'd like to check remote mailboxes with the taskbar mail applet

<P>
No problem either. Your <TT>MailBoxPath</TT> in the <TT>preferences</TT>
file should read

<TSCREEN><VERB>
    MailBoxPath=&quot;imap://username:password@remote.host&quot;
</VERB></TSCREEN>

Replace <TT>imap</TT> with <TT>pop</TT> or <TT>pop3</TT> if necessary. Be sure to have save
permissions on the preferences file so nobody else can get your mail password.


<SECT>Control The Look and Behavior Of Applications

<P>
This section is about how you can make windows appear on a certain
workspace, have them displayed without a border or titlebar, or put them
above or under other windows. All this can be accomplished using the
<TT>winoptions</TT> preferences file, some of it even interactively.

<SECT1>Assign an option to a given application

<P>
Assigning a particular option (icon, default layer, default
workspace, etc.) to a given application or application window can be
done as follows:

First, you should acquire the <TT>&quot;WM_CLASS&quot;</TT> descriptor
using <TT>xprop.</TT> Simply run

<TSCREEN><VERB>
    xprop |grep WM_CLASS
</VERB></TSCREEN>

in an XTerm. The first item is the window name and the second item it
the window class. You can then add the desired options to your
<TT>winoptions</TT> file. Entries in that file have one
of the following formats:

<TSCREEN><VERB>
    name.class.option: value
    class.option:      value
    name.option:       value
</VERB></TSCREEN>

The <TT>&quot;WM_CLASS&quot;</TT> for a Netscape Navigator window is

<TSCREEN><VERB>
    &quot;Navigator&quot;, &quot;Netscape&quot;
</VERB></TSCREEN>

To assign the icons <TT>&quot;navigator_*.xpm&quot;</TT> to the
Netscape Navigator window, use this option:

<TSCREEN><VERB>
    Navigator.Netscape.icon: navigator
</VERB></TSCREEN>

The other options work according to roughly the same pattern. The list
of winoptions you can find in 
<HTMLURL URL="http://www.icewm.org/manual/" 
NAME="IceWM manual"> chapter about Window Options.


<SECT1>How do I make a window stay on top?

<P>
There are two slightly different ways to do this. Use whatever suits your
need. Option one: the window always stays on top of any other windows. Set
the following option <TT>name.class.layer: onTop</TT>.
Option two: the window sits in a rectangular zone of the desktop where no
other windows can be placed: Use the doNotCover option:
<TT>name.class.doNotCover: 1</TT>. By the way: this is how the taskbar or
the GNOME panel work. It's a good idea to use this on gkrellm, your icq
client, or other monitoring tools you'd always like to have in view.

<SECT1>Have windows iconified/maximized as soon they are mapped

<P>
There may be programs that you either want to start up iconified or
maximized. Until now, there is no possible entry in your
<TT>winoptions</TT> file that iconifies or maximizes a
windows of a given name or class as it is mapped.


Fortunately some programs (like Netscape) have a command line option
to be started iconic and most X program support
<TT>&quot;-geometry&quot;</TT> to specify a default window size.



<SECT>Using IceWM With The Keyboard

<P>
It should be possible to control everything by keyboard. Here we show some
of the not so obvious ways to achieve important window managing tasks only
with keystrokes.

<SECT1>Basic predefined keyboard shortcuts

<P>
<VERB>
Alt-Tab = Switches between the open windows
Alt-F4 = Closes a window
Alt-F9 = Minimizes a window
Alt-F10 = Maximizes a window
Alt-F12 = Rolls the window up
(leaving only the titlebar visible, press Alt-F12 again and the window rolls back down)
Alt-Shift-F10 = Maximizes the window vertically 
Alt-Ctrl-arrow left = Changes workspaces from 1-12
Alt-Ctrl-arrow right = Changes workspaces from 12-1
Alt-Ctrl-Esc = Opens the  window list
Ctrl-Esc = Opens the  menu
</VERB>


<SECT1>Switching Desktop using keyboard

<P>
You are accustomed to a window manager that allows you to switch
between virtual desktops using your keyboard? IceWM allows for this,
too.

Before I describe how to switch between virtual desktops I want to
describe how to control their number. Imagine that your
<TT>$HOME/.icewm/preferences</TT> has a row reading

<TSCREEN><VERB>
    WorkspaceNames=&quot;1&quot;,&quot;2&quot;,&quot;3&quot;,&quot;4&quot;,&quot;5&quot;,&quot;6&quot;,&quot;7&quot;,&quot;8&quot;,&quot;9&quot;,&quot;0&quot;
</VERB></TSCREEN>

This setting results in ten virtual desktops and ten buttons in your
taskbar looking like this:

<TSCREEN><VERB>
    +---+---+---+---+---+---+---+---+---+---+
    | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0 |
    +---+---+---+---+---+---+---+---+---+---+
</VERB></TSCREEN>

If you name less desktops you obtain less if you name more you get
more.

For understanding how switching virtual desktops works in IceWM you
should imagine that the buttons represent your virtual desktops and
that these desktops are arranged in one long row.

You can imagine two ways of switching between desktops:

<ITEMIZE>
  <ITEM>Switching to desktop number seven
  <ITEM>Switching to the desktop on the left/right of the present one
</ITEMIZE>

IceWM has both ways:

<ITEMIZE>
  <ITEM> To switch to desktop number <EM>n</EM> you simply press
    <TT>&quot;Ctrl-Alt-n&quot;</TT>
  <ITEM> To switch one desktop to the left you press
    <TT>&quot;Ctrl-Alt-Cursor_Left&quot;</TT>
  <ITEM> To switch one desktop to the right you press
    <TT>&quot;Ctrl-Alt-Cursor_Right&quot;</TT>
</ITEMIZE>

<TT>&quot;Cursor_Left&quot;</TT> <TT>(&quot;Cursor_Right&quot;)</TT>
represents the key that moves your cursor one character to the left
(right).

If you are using <TT>&quot;Ctrl-Alt-Cursor_Right&quot;</TT> on the
rightmost desktop you switch to the leftmost desktop. From here,
<TT>&quot;Ctrl-Alt-Cursor_Left&quot;</TT> brings you back to the
rightmost desktop.

<EM>What if you have more than ten virtual desktops?</EM> In this
case <TT>&quot;Ctrl-Alt-n&quot;</TT> will only work for the first ten
desktops while switching to the left or right still works for all
desktops.

IceWM has another feature to offer: You may not only use your
keyboard to switch desktops, you can also use it to move windows from
one desktop to another. The next section is on this (you should read
it, too).

<BF>Note:</BF> To switch desktops when moving mouse on desktop edges use preference:
<TSCREEN><VERB>
EdgeSwitch=1
</VERB></TSCREEN>
then you can change workspaces automatically by moving your cursor to the left/right edges of your screen.


<SECT1>Moving windows between desktops using keyboard

<P>
In the previous section I explained how to switch between desktops.
If you didn't already read it you should do it now because moving the
active window to another desktop works almost the same like switching
to a certain desktop. All you have to do is pressing the
<TT>&quot;Shift&quot;</TT> while switching to the desktop:

<ITEMIZE>
  <ITEM> To move a window to desktop number <EM>n</EM> you simply
    press <TT>&quot;Ctrl-Alt-Shift-n&quot;</TT>
  <ITEM> To move a window one desktop to the left you press
    <TT>&quot;Ctrl-Alt-Shift-Cursor_Left&quot;</TT>
  <ITEM> To move a window one desktop to the right you press
    <TT>&quot;Ctrl-Alt-Shift-Cursor_Right&quot;</TT>
</ITEMIZE>

<SECT1>Using the CLI (command line interface)

<P>
You should run IceWM with <TT>&quot;TaskBarDoubleHeigth=1&quot;</TT>
because that will enable the CLI (see <EM><REF ID="CLI"
NAME="What is the blank bar in the task bar good for?"></EM> for some
more information).

The CLI is especially useful if you rather frequently need to access
man pages and don't want to have xman hang around all the time.

If you enter <TT>man perl</TT> and press
<TT>&quot;Ctrl-ENTER&quot;</TT> an XTerm will pop up displaying the
main Perl man page. If you press <TT>&quot;q&quot;</TT> not only the
man page no longer is displayed but the XTerm will terminate, too.

This only is <EM>one</EM> example of how to use the CLI. You can use
it to issue any other command as well. A problem that might occur is
that the XTerm will terminate before you had time to read the output
of a command (it terminates as soon as the command is done).

In most such cases it is sufficient to pipe the output through
<TT>less</TT> (this is one of the rare cases you cannot
use <TT>more</TT> because it terminates after displaying
the last line). However, there are cases (mainly programs that write
colorful output such as <TT>ls</TT>) that may result in
trouble with <TT>less</TT>.

Fortunately Linux (any Unix version?) offers a solution to these
cases, too: The <TT>sleep</TT> command. It sleeps some
time, then terminates. So you could use

<TSCREEN><VERB>
    ls $HOME/bin --color ; sleep 1m
</VERB></TSCREEN>

to list all programs in your <TT>$HOME/bin</TT>
directory. The <TT>sleep</TT> command will wait the given
period of time (in this case a minute) before the XTerm automatically
will close (you can use <TT>&quot;Ctrl-C&quot;</TT> to abort the
<TT>sleep</TT> command before that time went by).



<SECT>Customizing The Look Through Themes

<P>
IceWM can be customized using a great variety of themes.

<SECT1>What image formats can I use with IceWM?

<P>
If IceWM is compiled with the standard xpm libraries, then it can
only employ xpm images (as backgrounds, etc.). If, however, IceWM is
compiled with <TT>imlib</TT> support, it can display all
common image formats including jpeg, gif, png, and tiff.

<SECT1>Setting background color/image

<P>
If you provide the appropriate options in your
<TT>preferences</TT> file and starts <TT>icewmbg</TT>, IceWM will set the 
background color or the background image for you. You can use

<TSCREEN><VERB>
    DesktopBackgroundColor=&quot;color&quot;
</VERB></TSCREEN>

to set a background color and

<TSCREEN><VERB>
    DesktopBackgroundImage=&quot;image&quot;
</VERB></TSCREEN>

to set a background image. To keep IceWM from setting a background
color/image you simply set <EM>both</EM> options to an empty string:

<TSCREEN><VERB>
    DesktopBackgroundColor=&quot;&quot;
    DesktopBackgroundImage=&quot;&quot;
</VERB></TSCREEN>

<BF>Hints:</BF>

<ENUM>
  <ITEM>
    Commenting out
    <TT>DesktopBackgroundColor=&quot;color&quot;</TT>
    and <TT>DesktopBackgroundImage=&quot;image&quot;</TT>
    does not have the intended effect.
  <ITEM>
    IMHO using a background image (especially a huge one) isn't that
    good an idea. It awfully slows down the X windowing system.
</ENUM>

To distinguish between filling whole desktop with image or to place it self
standing in the middle you can use

<TSCREEN><VERB>
    DesktopBackgroundCenter=&quot;&quot;
</VERB></TSCREEN>

DesktopBackgroundCenter is used to tell IceWM how you want your wallpaper placed on the screen.
If set to 1 your picture will be centered on screen. As a result of that, you will only have one picture in the middle of your desktop.
If set to 0 your picture file will fill the whole screen. That is a good thing if you are using a pattern thingy to cover the whole desktop.


<SECT1>Setting the clock format<LABEL ID="timeformat">

<P>
Setting up the look of the task bar clock of IceWM as well as the
format of the associated tooltip is rather easy. IceWM uses the same
format as the Unix standard function <TT>strftime</TT> so
when in doubt you can always refer to

<TSCREEN><VERB>
    man 3 strftime
</VERB></TSCREEN>

To set the clock format you use

<TSCREEN><VERB>
    TimeFormat=&quot;&lt;format string&gt;&quot;
</VERB></TSCREEN>

and for the clock tooltip format you use

<TSCREEN><VERB>
    DateFormat=&quot;&lt;format string&gt;&quot;
</VERB></TSCREEN>


Ordinary characters placed in the format string are printed without
conversion (if possible, see below). Conversion specifiers are
introduced by a percent character <TT>&quot;%&quot;,</TT> and are
replaced by a corresponding string.

<BF>Important Note:</BF> While <TT>&quot;DateFormat&quot;</TT> and
<TT>&quot;TimeFormat&quot;</TT> both support all the format
descriptors the latter only has full support if used with

<TSCREEN><VERB>
    TaskBarClockLeds=0
</VERB></TSCREEN>

(which is set equal 1 by default).

The reason for this is that there are no icons to display the name of
a month, day, or time zone. To be more precise there are only icons
for

<ENUM>
  <ITEM>digits (0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
  <ITEM>colon, dot, slash, and space
  <ITEM>A, P, and M (for AM and PM)
</ENUM>

Format descriptors which may only be in
<TT>&quot;TimeFormat&quot;</TT> if
<TT>&quot;TaskBarClockLeds=0&quot;</TT> (in general or depending on
the locale) are labeled as <BF>restricted</BF> in the following
table. It shows the replacement for all format descriptors available.

The values in parentheses show what the different format specifiers
display for

<TT>YYYY/MM/DD HH:MM:SS TimeZone = 1999/09/04 19:09:22 UTC</TT>

on my machine with hardware clock and Linux running UTC, local being
&quot;C&quot; (i.e.  no internationalization at all):

<DESCRIP>
  <TAG><TT>&quot;%a&quot;</TT> (Sat) restricted</TAG>
    The abbreviated weekday name according to the current locale.
  <TAG><TT>&quot;%A&quot;</TT> (Saturday) restricted</TAG>
    The full weekday name according to the current locale.
  <TAG><TT>&quot;%b&quot;</TT> (Sep) restricted</TAG>
    The abbreviated month name according to the current locale.
  <TAG><TT>&quot;%B&quot;</TT> (September) restricted</TAG>
    The full month name according to the current locale.
  <TAG><TT>&quot;%c&quot;</TT> (Sat Sep 04 19:09:22 1999) restricted</TAG>
    The preferred date and time representation for the current
    locale.
  <TAG><TT>&quot;%d&quot;</TT> (04)</TAG>
    The day of the month as a decimal number (range 01 to 31).
  <TAG><TT>&quot;%H&quot;</TT> (19)</TAG>
    The hour as a decimal number using a 24-hour clock (range 00 to
    23).
  <TAG><TT>&quot;%I&quot;</TT> (07)</TAG>
    The hour as a decimal number using a 12-hour clock (range 01 to
    12).
  <TAG><TT>&quot;%j&quot;</TT> (247)</TAG>
    The day of the year as a decimal number (range 001 to 366).
  <TAG><TT>&quot;%m&quot;</TT> (09)</TAG>
    The month as a decimal number (range 01 to 12).
  <TAG><TT>&quot;%M&quot;</TT> (09)</TAG>
    The minute as a decimal number.
  <TAG><TT>&quot;%p&quot;</TT> (PM) restricted</TAG>
    Either &quot;am&quot; or &quot;pm&quot; according to the given
    time value, or the corresponding strings for the current locale.
  <TAG><TT>&quot;%S&quot;</TT> (22)</TAG>
    The second as a decimal number.
  <TAG><TT>&quot;%U&quot;</TT> (35)</TAG>
    The week number of the current year as a decimal number, starting
    with the first Sunday as the first day of the first week.
  <TAG><TT>&quot;%W&quot;</TT> (35)</TAG>
    The week number of the current year as a decimal number, starting
    with the first Monday as the first day of the first week.
  <TAG><TT>&quot;%w&quot;</TT> (06)</TAG>
    The day of the week as a decimal, Sunday being 0.
  <TAG><TT>&quot;%x&quot;</TT> (09/04/99) restricted</TAG>
    The preferred date representation for the current locale without
    the time.
  <TAG><TT>&quot;%X&quot;</TT> (19:09:22) restricted</TAG>
    The preferred time representation for the current locale without
    the date.
  <TAG><TT>&quot;%y&quot;</TT> (99)</TAG>
    The year as a decimal number without a century (range 00 to 99).
  <TAG><TT>&quot;%Y&quot;</TT> (1999)</TAG>
    The year as a decimal number including the century.
  <TAG><TT>&quot;%Z&quot;</TT> (UTC) restricted</TAG>
    The time zone or its name or its abbreviation.
  <TAG><TT>&quot;%%&quot;</TT> restricted</TAG>
    A literal &quot;%&quot; character.
</DESCRIP>

<SECT1>I have more icons to add

<P>
You can either copy them to systemwide <TT>icons</TT> directory or you can copy
them to <TT>~/.icewm/icons</TT> or you can use option

<TSCREEN><VERB>
IconPath="/home/username/.icewm/myicons:/usr/share/pixmaps"
</VERB></TSCREEN>
from preferences file. Remember that the new path you are adding must be seperated with a colon (:).


<SECT1>How to learn making themes for IceWM?

<P>
There is documentation on
<HTMLURL URL="http://www.icewm.org/themes/" 
NAME="http://www.icewm.org/themes/"> written by MJ Ray and update by Adam Pribyl.


<SECT>Miscellaneous Questions

<P>
This section is a collection of questions on subjects that go beyond
simply <BF>using</BF> IceWM.

<SECT1>What does Logout(Cancel) Command do?

<P>
For most users, nothing. Both commands were meant for GNOME
integration as alternative commands that would be run when users
initiated a logout or logout cancel. Since GNOME did not seem to
incorporate this feature, they generally go unused.

<SECT1>What is the blank field in the task bar good for?<LABEL ID="CLI">

<P>
If you are running IceWM with the
<TT>&quot;TaskBarDoubleHeight&quot;</TT> option set, a blank field in
the task bar occurs. It is a command line interface.

In this field you can enter commands to start programs. If you click
inside the field and enter <TT>xclock</TT> the X clock is
started.

If you click on it and simply press <TT>&quot;Ctrl-Enter&quot;</TT>
an XTerm is being started.

If you enter a non-X command and press
<TT>&quot;Ctrl-Enter&quot;</TT> an that command is being executed in
an XTerm.

<SECT1>How to keep IceWM from grabbing keystrokes

<P>
What if you are running an application and need to use a keystroke
that is grabbed by IceWM?

Marko suggests the following workaround:

<ENUM>
  <ITEM>Activate scroll lock
  <ITEM>Do problematic key stroke
  <ITEM>Deactivate scroll lock
</ENUM>

He advises that this will only work if
<TT>&quot;ScrollLock&quot;</TT> is set up as a modifier.

Here is how to use the X11 <TT>xmodmap</TT> utility to setup <TT>ScrollLock</TT> as
a modifier (from Marco Molteni):
<ENUM>
    <ITEM> check which modifiers are free:

<TSCREEN><VERB>
    $ xmodmap -pm

    xmodmap:  up to 2 keys per modifier, (keycodes in parentheses):

    shift       Shift_L (0x32),  Shift_R (0x3e)
    lock        Caps_Lock (0x42)
    control     Control_L (0x25),  Control_R (0x6d)
    mod1        Alt_L (0x40),  Alt_R (0x71)
    mod2        Num_Lock (0x4d)
    mod3
    mod4        Super_L (0x73),  Super_R (0x74)
    mod5      
</VERB></TSCREEN>

<ITEM> in this example <TT>mod3</TT> is free, so we bind the <TT>ScrollLock</TT> key to it:

<TSCREEN><VERB>
   $ xmodmap -e "add mod3 = Scroll_Lock"
</VERB></TSCREEN>
   
   this invocation of <TT>xmodmap</TT> should be put in the script that starts the
   window manager, for example <TT>$HOME/.xinit</TT> or <TT>$HOME/.xsession</TT>, see 
   <REF ID="defwm" name="Howto make IceWM default WM"> for more detailed info
   about startup of WM or use IceWM's <REF ID="startup" name="startup">.
</ENUM>

<SECT1>How to lock the screen

<P>
Screen locking is something you should do whenever you leave your
machine (even at home and even for only a few seconds - just imagine
a cat pushing the enter button at the wrong moment). It should be a
habit like logging out root as soon as possible.

<SECT2>... by keyboard

<P>
With IceWM screen locking is very easy: If you press

<TSCREEN><VERB>
    Ctrl-Alt-Del
</VERB></TSCREEN>

a menu pops up offering you the following tasks:

<ITEMIZE>
  <ITEM>Lock <TT>&quot;W&quot;</TT>orkstation
  <ITEM><TT>&quot;L&quot;</TT>ogout
  <ITEM><TT>&quot;C&quot;</TT>ancel
  <ITEM><TT>&quot;R&quot;</TT>estart icewm
  <ITEM>Re<TT>&quot;b&quot;</TT>oot
  <ITEM>Shut<TT>&quot;d&quot;</TT>own
</ITEMIZE>

The letters that are emphasized in this FAQ are underlined in real
life. The meaning of this emphasis is that you may e. g. press
<TT>&quot;W&quot;</TT> to lock your workstation.

Another possibility (this is the one I prefer because I once to often
pressed <TT>&quot;L&quot;</TT> in order to lock my machine) is to
press <TT>&quot;ENTER&quot;.</TT> The result is the same because the
button that is active by default is <EM>&quot;Lock
Workstation&quot;.</EM>

A more obvious reason for using <TT>&quot;ENTER&quot;</TT> in place
of <TT>&quot;W&quot;</TT> is that it is easier to type in:
<TT>&quot;Del&quot;</TT> and <TT>&quot;ENTER&quot;</TT> are next to
each other.

You could as well use your mouse to click on <EM>&quot;Lock
Workstation&quot;</EM> but if you are already using your keyboard to
evoke the menu why not use the keyboard to select from it?

<SECT2>... by mouse

<P>
If you prefer to use your mouse to lock the screen you may add the
following entry to your <TT>$HOME/.icewm/toolbar</TT>

<TSCREEN><VERB>
    prog    xlock   xlock   xlock
</VERB></TSCREEN>

You could as well add that line
<TT>$HOME/.icewm/menu</TT> or
<TT>$HOME/.icewm/programs</TT> but that's not a good
idea: Screen locking is often done in a hurry and if you have to scan
through a menu this will increase the chance that you will not lock
your machine at all.

<SECT2>... using a lock command other than xlock

<P>
How to define a different lock command is described in section <REF
ID="locking" name="Setting the lock command">

<SECT1>Does IceWM support session management?

<P>
Of course not. This is where the more complicated desktop environments like
GNOME, KDE or xfce join the game. IceWM still is only a window manager...
but of course you can always start your favorite apps upon X start-up/login
using the <TT>.xinitrc</TT> or <TT>.xsession</TT>files. Or use IceWM as the
window manager instead of the default GNOME/KDE wm.

<SECT1>Can I have icons on the desktop? <LABEL ID="iconsondesk">

<P>
Sure, but not from IceWM. Again, this is desktop environment work, but
usually done by the respective file managers, since they already know about
MIME types, file endings and such. IceWM users usually use idesk, dfm, rox, kfm or gmc,
where idesk, dfm and rox are better suited for work on smaller (older) machines than the
other two.

<SECT1>Why doesn't IceWM accept my background image/color?

<P>Usually this is because it's the wrong image format. It can happen when
IceWM is compiled only with libXpm.
With imlib, IceWM is able to read most of the often used image
formats like png, gif, jpeg, instead of just xpm images with libXpm. Another
reason can be, that the theme defines another image or color.

<SECT1>Can I have bigger icons in menu, taskbar, quickswitch etc.?

<P>No. At this time IceWM handles only default sizes of icons. For
menu and taskbar it is 16x16 pixels, for quickswitch it uses 32x32 pixels.
There is a patch that enables IceWM to handle different sizes of icons in icewm 
patch tracker, but it is not fully prepared yet.

<SECT1>How can I translate IceWM into my language?

<P>
Create a copy of <TT>icewm.pot</TT> and rename it to 
<TT>cs.po</TT> or whatever is right for your language.
<P>
Then you have to translate the file using any of the tools for
gettext file transaltion, e.g. kbabel, or you can edit it by hand.
After translation you can send it to icewm-devel list or post it
as patch in patch tracker.

<P>
If you want to test file yourself you can add this file 
into <TT>po</TT> directory under IceWM sources and then configure IceWM
(<TT>./configure</TT>) and type <TT>make</TT> in <TT>po</TT> directory.
This creates .mo file, which you can either copy to locale locations
(e.g. /usr/local/share/locale/cs/LC_MESSAGES) or you can do <TT>make install</TT>.


<SECT>Example: configuration A-Z

<P>
This is sample of possible configuration you need to do to have IceWM
running with all you need. Following applies for RedHat(9). Placement of files can be
bit different.

<SECT1>X window login

<P>To have possibility to switch to IceWM  in GDM greeter (after start to runlevel 5 = Xwindow),
then you need to do following things:

<ITEMIZE>
  <ITEM>Add to <TT>/etc/X11/gdm/Sessions/</TT> (gdm is default greeter) file <TT>IceWM</TT> with content
<TSCREEN><VERB>
  #!/bin/bash
  exec /etc/X11/xdm/Xsession icewm
</VERB></TSCREEN>
 
  <ITEM>Modify <TT>/etc/X11/xdm/Xsession</TT> to understand what "icewm" is (this is not necessary)
  <ITEM>Add to <TT>/usr/share/apps/switchdesk/</TT> file <TT>Xclients.icewm</TT> with content
<TSCREEN><VERB>
  #!/bin/bash
  exec /usr/local/bin/icewm-session
</VERB></TSCREEN>
  
</ITEMIZE>

<SECT1>IceWM configuration

<P>To configure all of IceWM options go to sections about configuration.
<P>Generally all you need to customize IceWM globaly, is to edit <TT>/usr/local/share/icewm/preferences</TT> etc.

<SECT1>Additional applications

<SECT2>Icons on desktop

<P>Usually people want to have icons on desktop. One of most simple applications that can
satisfy this need is <TT>idesk</TT> (see Tools to find it). I personaly recommend
to use 0.3.x version - this has almost no requirements and is really simple.

<P>Configuration of idesk is almost as easy as configuration of IceWM, but has one disadvantage:
idesk does not have in version 0.3.x global configuration file - therefore each user needs to
have proper configuration file in his/her home.

<P>To configure idesk you need to:
<ITEMIZE>
  <ITEM>Add <TT>~/.ideskrc</TT> file with content like this
<TSCREEN><VERB>
table Config
  FontName: Helvetica
  FontSize: 9
  FontColor: #ffffff
  PaddingX: 35
  PaddingY: 25
  Locked: true
  HighContrast: false
  Transparency: 50
  Shadow: true
  ShadowColor: #000000
  ShadowX: 1
  ShadowY: 1
  Bold: false
end
</VERB></TSCREEN>
 
  <ITEM>Add <TT>~/.idesktop</TT> directory
  <ITEM>Add <TT>whatever.lnk</TT> files into it, with content like this
  
<TSCREEN><VERB>
table Icon
  Caption: Mozilla
  Command: mozilla
  Icon: /usr/share/pixmaps/mozilla-icon.png
  X: 22
  Y: 13
end
</VERB></TSCREEN>
  
  <ITEM>Do not forget you need to start idesk at the beginning of the session. 
  Best to achieve this is using your <TT>~/.icewm/startup</TT> file (for details see Configuration section).
  In case of idesk you can add line:
<TSCREEN><VERB>
idesk > /dev/null & # start idesk - desktop icon manager
</VERB></TSCREEN>


</ITEMIZE>



<SECT2>Control tools

<P>To have some "control center" like application you can use Vadim A. Khohlov's <TT>icecc</TT> - 
IceWM Control center. (see Tools to find it) His utility is also very simple, fast and has editors
for all of the IceWM options.

<P>To integrate it into menu you have to edit <TT>/usr/local/share/icewm/menu</TT> and add there line like this
<TSCREEN><VERB>
prog "Control Center" "icecc_icon" icecc
</VERB></TSCREEN>

<P>Please note that icecc needs some other programs like gvim and python to work properly.

<SECT>Tools for IceWM <LABEL ID="tools4icewm">

<P>
This section is a collection of tools that simplify the usage of
IceWM. Head on over to the utilities section of the IceWM homepage if you
want an up to date overview about all available tools.

<SECT1>IcePref

<P>
<BF>Note:</BF> IcePref is a history these day, but you can still find it.

<SECT2>Description (by the author of IcePref)

<P>
IcePref is a small graphical utility (written with Python and the Gtk
toolkit) designed to simplify the configuration of IceWM.

It currently supports the options of IceWM version 1.0.4 and should
(in theory) work consistently with versions at least as high as
1.0.4. While it is not a particularly elegant program, I have found
IcePref useful and hope that it will be found useful by those who use
IceWM and also have Gtk installed.

IcePref should be especially useful to those who have GNOME, and who
are therefore likely to have PyGNOME and PyGTK already installed on
their boxes.

<SECT2>Download IcePref

<P>
IcePref was available from <HTMLURL
URL="http://members.xoom.com/SaintChoj/icepref.html"
NAME="http://members.xoom.com/SaintChoj/icepref.html">
Nowadays you have to search the net for suitable archiv

<SECT1>IcePref2

<P>
IcePref2 is maintained successor to IcePref.
It is included in <EM>IceWM Control Panel</EM>.

<SECT2>Description

<P>
IcePref2 is advanced preferences file editor.

<SECT2>Download IcePref2

<P>
<HTMLURL URL="http://icesoundmanager.sourceforge.net/" 
NAME="http://icesoundmanager.sourceforge.net/">


<SECT1>IceME

<P>
The IceWM Menu Editor allows users to edit their menu without knowing
anything about config files.
It is included in <EM>IceWM Control Panel</EM>.

<SECT2>Download IceME

<P>
Get IceME at <HTMLURL
URL="http://iceme.sourceforge.net/"
NAME="http://iceme.sourceforge.net/">

<SECT1>IceWM Control Panel

<SECT2>Description (by author of IceWM Control Panel)

<P>
IceWM Control Panel is the first full-featured, Gtk-based control panel 
for IceWM. It is meant to run in IceWM, but can be used in ANY window 
manager as a general-purpose control panel. It was inspired by the Qt-based 
application called IceMC, but includes many more tools, a more familiar 
Windoze Control Panel-like interface, and uses the MUCH faster Gtk user 
interface (Who runs a fast Window Manager like IceWM, to launch SLOW-running, 
memory-intensive Qt/KDE-based applications?? I sure don't). 
Let's face it: IceWM and fast Gtk interfaces work well together. 

IceWM Control Panel includes applications for editing preferences (IcePref2),
menus (IceMe), themes, sounds (IceSoundMngr), cursors, keys, mouse, wallpapers,
winoptions, icon browser etc.

<SECT2>Download IceWM Control Panel

<P>
The IceWM Control Panel homepage is at 
<HTMLURL 
URL="http://icesoundmanager.sourceforge.net/" 
NAME="http://icesoundmanager.sourceforge.net/">

<SECT1>IceWM Control Center

<SECT2>Description

<P>
This is Vadim Khohlov's software. A good collection of the configuration 
software for IceWM, include: menu/toolbar editor, Ice Sound Configurator, 
theme Switcher, backgroundoptions editor, IceWM's winoptions editor, keys 
editor.

<SECT2>Download IceWM Control Center

<P>
The IceWM Control Center homepage is at <HTMLURL
URL="http://freshmeat.net/projects/icecc/"
NAME="http://freshmeat.net/projects/icecc/">

<P>
Vadim also made a 
<HTMLURL 
URL="http://icecc.sourceforge.net/idesktools.html" 
NAME="little tool">
to automate desktop link creation for
idesk version 0.3.5.

<SECT1>IceWMConf

<SECT2>Description (by the author of IceWMConf)

<P>
IceWMConf is a small application which helps with configuring IceWM.
It tries to be self-configuring, starting with the basic options from
the system preferences files and then overriding them with user
preferences.

In this way, it should pick up new options introduced by later
versions of IceWM. (It does mean that old options aren't deleted, so
you have to occasionally &quot;trim&quot; your user file to remove
lines IceWM grumbles about, but that isn't very necessary.)

Its user interface is functional bordering on spartan, but builds its
own option categories and has an option name search facility. If you
want a really user friendly configuration tool, I suggest IcePref.

<SECT2>Download IceWMConf

<P>
The IceWMConf homepage is at <HTMLURL
URL="http://sdboyd.dyndns.org/icewmconf/"
NAME="http://sdboyd.dyndns.org/icewmconf/">


<SECT1>IceWO

<SECT2>Description

<P>
IceWO is an icewm's winoption file editor. It allows you to set winoptions 
for any window by clicking on buttons, without manual editing winoptions file.

<SECT2>Download IceWO

<P>
<HTMLURL URL="http://syjon.fantastyka.net/~narel/icewo/"
NAME="http://syjon.fantastyka.net/~narel/icewo/">

<SECT1>IceMC

<SECT2>Description

<P>
IceMC is a graphical menu editor for IceWM, designed to be simple and stable.
You can configure your menu entries with copy, paste, and drag'n'drop.

<SECT2>Download IceWO

<P>
<HTMLURL URL="http://freshmeat.net/projects/icemc/"
NAME="http://freshmeat.net/projects/icemc/">


<SECT1>MenuMaker

<SECT2>Description

<P>
MenuMaker is utility written entirely in Python that scans through the system for 
installed programs and generates menu for specified X window manager. 
It is by far more superior to existing solutions in terms of knowledge base size, 
maintainability and extensibility, and has a number of features that have no counterparts 
in its class. MenuMaker is intended for users of lightweight *NIX graphical desktop environments.
<SECT2>Download MenuMaker

<P>
<HTMLURL URL="http://menumaker.sourceforge.net/"
NAME="http://menumaker.sourceforge.net/">

<SECT1>IDesk

<SECT2>Description

<P>
iDesk gives users of minimal wm's (fluxbox, pekwm, windowmaker...) icons on 
their desktop. The icon graphics are either from a png or svg (vector) file 
and support some eyecandy effects like transparency. Each icon can be confgured
to run one or more shell commands and the actions which run those commands are 
completely configurable. In a nutshell if you want icons on your desktop and 
you don't have or dont't want KDE or gnome doing it, you can use idesk.

<SECT2>Download IDesk

<P>
<HTMLURL URL="http://idesk.timmfin.net/"
NAME="http://idesk.timmfin.net/">


<SECT1>DFM

<SECT2>Description

<P>
DFM is a file manager for Linux and other UNIX like Operating Systems. 
DFM is the abrvabation for Desktop File Manager. "Desktop" stands for the 
capability to place icons on the root window.

<SECT2>Download DFM

<P>
<HTMLURL URL="http://www.kaisersite.de/dfm/"
NAME="http://www.kaisersite.de/dfm/">


<SECT>Bugs and Problems

<P>
This section is for problems that are intrinsic to the philosophy of
IceWM or that are caused by bugs.

<SECT1>IceWM ignores my color settings

<P>
Some users wonder why the colors specified in their preference files
seem to have no effect upon the actual appearance of things. The
reason is that these settings may be overridden by settings in the
theme file.

The theme file can control all of the options
controlled by the <TT>preferences</TT> file, but usually
theme authors are decent confine their meddling to superficial
aspects of window manager behavior and leave control over most
important behaviors to the user.

If this wasn't the reason: If you are running X in 8-bit mode then it
is possible that the specified color simply isn't available.

You don't know if X is running in 8-bit mode? Run

<TSCREEN><VERB>
    xwininfo | grep Depth
</VERB></TSCREEN>

in an XTerm and click on the root window (the desktop). If this
command displays

<TSCREEN><VERB>
    Depth: n
</VERB></TSCREEN>

you are running X in n-bit mode (n typically is 8, 16, 24 or 32).

<SECT1>Programs are missing in the menus

<P>
A very annoying problem are programs you added to the
<TT>menu</TT> file but
that are missing in the corresponding menus. That isn't really a bug
of IceWM. The point of view of IceWM is that it makes no sense to
display a program that <EM>are not present.</EM>

The crucial point is the meaning of <EM>&quot;to be
present&quot;.</EM> It does not mean <EM>&quot;to be
installed&quot;</EM> but <EM>&quot;to be found using the present
path&quot;</EM> (<EM>echo $PATH</EM> or <EM>which program</EM> to find if program is in
PATH).

To fix the problem you have at least three possibilities:

<ENUM>
  <ITEM>
    You give the full path and not only the program name itself.
  <ITEM>
    You set the path in your <TT>.xinitrc</TT>, <TT>.xsession</TT> or <TT>.Xclients</TT>.
  <ITEM>
    You use a wrapper script for running IceWM.
</ENUM>

The first two solutions are straightforward. Using a wrapper script
is a bit tricky therefore I'll describe how to do it.

Become root and move <TT>icewm</TT> to
<TT>icewm.bin.</TT>

<TSCREEN><VERB>
    mv /usr/local/bin/icewm /usr/local/bin/icewm.bin
</VERB></TSCREEN>

Edit <TT>icewm</TT> so that it reads something like this:

<TSCREEN><VERB>
    #!/bin/sh

    PATH=&lt;what the path shall be&gt;
    export $PATH

    exec icewm.bin $*
</VERB></TSCREEN>

It is very important to add the <TT>&quot;$*&quot;.</TT> Otherwise
all command line arguments (such as <EM>&quot;use another
theme&quot;)</EM> will be ignored.

<BF>Hint:</BF> Using <TT>bash</TT>, <TT>ksh</TT> and
<TT>zsh</TT> you can contract

<TSCREEN><VERB>
    PATH=&lt;what the path shall be&gt;
    export $PATH
</VERB></TSCREEN>

into

<TSCREEN><VERB>
    export PATH=&lt;what the path shall be&gt;
</VERB></TSCREEN>

You could also <BF>add</BF> directories to the path (instead of
simply overwriting it). To do this you use

<TSCREEN><VERB>
    PATH=$PATH:&lt;what shall be added&gt;
</VERB></TSCREEN>

<SECT1>IceWM maximizes windows over the GNOME panel

<P><P>
This used to be a really annoying problem, but seems to be gone with newer
versions of IceWM and GNOME. If it still happens on your machine try to set

<TSCREEN><VERB>
    Panel.doNotCover: 1
</VERB></TSCREEN>

in your <TT>winoptions</TT> file.

<SECT1>The IceWM binaries are very big

<P>
You might wonder why the IceWM binaries is that big. This is because
they contain an awful lot of (debugging) symbols. Without them the
binaries are <BF>much</BF> smaller. The command to remove the symbols
is <TT>strip:</TT> Go to the directory where IceWM has
been installed in (typically <TT>/usr/local/bin/)</TT>
and issue:

<TSCREEN><VERB>
    ls -l icewm icewmhint icewmbg icewmtray genpref
    strip -s icewm icewmhint icewmbg icewmtray genpref
    ls -l icewm icewmhint icewmbg icewmtray genpref
</VERB></TSCREEN>

The <TT>ls</TT> commands are not really needed, but show
you the (maybe dramatic) change of size of the icewm binaries.

Use <TT>man strip</TT> and <TT>info
strip</TT> to find out more details about the
<TT>strip</TT> command.

<SECT1>Screen locking doesn't work

<P>
The reason for this is that the standard lock command
(<TT>xlock</TT>) could not be found by IceWM. See <REF
ID="locking" name="Setting the lock command"> for details on setting
a different lock command.

<SECT1>Background does not show up

<P>
IceWM is divided in few separated parts. One of them is <TT>icewmbg</TT>.
This part takes care of bacground setup. Therefore if you want IceWM to
take care of desktop background you have to start <TT>icewmbg</TT> at
IceWM startup. Most common is to use <TT>startup</TT> file of icewm.
See <REF ID="conffiles" name="Configuration">.
<P>
You can also use <REF ID="icewmsess" name="icewm-session">.

<SECT1>Icon tray does not work

<P>
Problem is nearly same as with background. There is <TT>icewmtray</TT>
you need to start to activate tray functions. This should implement some docking
standard used by other applications.

<SECT1>IceWM does not respect my font settings

<P>
IceWM uses two ways of font handling.
<P>
X server provided fonts (--enable-corefonts option).
These fonts can be specified in <TT>preferences</TT> or theme <TT>default.theme</TT> like this:

<TSCREEN><VERB>
    ActiveButtonFontName = "-artwiz-snap-regular-r-normal-sans-10-*-*-*-*-*-*-*"
</VERB></TSCREEN>

Xft (xfreetype) library (default, disable using option --disable-xfreetype).
Then you have to specify these fonts like this:

<TSCREEN><VERB>
    ActiveButtonFontNameXft = "Snap:size=10,sans-serif:size=12:bold"
</VERB></TSCREEN>

Where you can define more fonts.

<P>
To provide correct fonts to Xft you have to specify them in <TT>/etc/fonts/fonts.conf</TT>.
X server font are either provided by X server itself e.g. <TT>/etc/X11/XF86Config</TT> Section &quot;Files&quot;)
or by XFS (X Font Server) e.g. <TT>/etc/X11/fs/config</TT>.


<SECT>Sources of information

<P>
This section lists sources of information on the IceWM window
manager. X applications to use with IceWM have their own section (see
<REF ID="tools4icewm" name="Tools for IceWM">).

Additions to the lists are welcome!

<BF>Important Note:</BF> This section is presently being worked on.
It's not finished and may be rather incomplete. FIXME

<SECT1>web pages<LABEL ID="icewebpages">

<SECT2>IceWM homepage

<P>
<DESCRIP>
  <TAG>Name:</TAG>
    IceWM homepage
  <TAG>URL:</TAG>
    <HTMLURL URL="http://www.icewm.org/"
    NAME="http://www.icewm.org/">
  <TAG>Maintainer:</TAG>
    Adam Pribyl, Marko Macek
</DESCRIP>

<SECT2>IceIcons

<P>
<DESCRIP>
  <TAG>Name:</TAG>
    IceIcons
  <TAG>URL:</TAG>
    <HTMLURL URL="http://themes.freshmeat.net/projects/iceicons/"
    NAME="http://themes.freshmeat.net/projects/iceicons/">
  <TAG>Maintainer:</TAG>
    Adam Pribyl
</DESCRIP>


<SECT2>IceWM.Themes.Org

<P>
<DESCRIP>
  <TAG>Name:</TAG>
    icewm.themes.org
  <TAG>URL:</TAG>
    <HTMLURL URL="http://icewm.themes.org/"
    NAME="http://icewm.themes.org">
  <TAG>Maintainer:</TAG>
    Freshmeat; was
    MJ Ray alias MarkJ (<HTMLURL URL="mailto:markj@themes.org"
    NAME="markj@themes.org">), Steven Blunt alias enterfornone
    (<HTMLURL URL="mailto:efn@themes.org" NAME="efn@themes.org">),
    and Josef 'Jupp' Schugt alias Jupp (<HTMLURL
    URL="mailto:jupp@themes.org" NAME="jupp@themes.org">).
    
</DESCRIP>

<SECT2>IceWM DevelZone

<P>
<DESCRIP>
  <TAG>Name:</TAG>
    IceWM DevelZone
  <TAG>URL:</TAG>
    <HTMLURL URL="http://icewm.sourceforge.net/"
    NAME="http://icewm.sourceforge.net/">
  <TAG>Maintainer</TAG>
    The IceWM developers team.
  <TAG>Comment:</TAG>
    The technical side of IceWM's web presence. Features technology
    previews, code snapshots and unstable testing versions. Bugs tracking
    and RFEs.
</DESCRIP>

<SECT2>IceWM FAQ and Howto

<P>
<DESCRIP>
  <TAG>Name:</TAG>
    IceWM FAQ
  <TAG>URL:</TAG>
    <HTMLURL URL="http://www.icewm.org/FAQ/"
    NAME="http://www.icewm.org/FAQ/">,
    old: <HTMLURL URL="http://icewm.maol.ch/FAQ/"
    NAME="http://icewm.maol.ch/FAQ/">
  <TAG>Maintainer:</TAG>
    Adam Pribyl, <HTMLURL URL="mailto:covex@ahoj.fsik.cvut.cz" 
    NAME="covex@ahoj.fsik.cvut.cz">,
    old: Markus Ackermann, <HTMLURL URL="mailto:maol@gmx.net"
    NAME="maol@gmx.net">
</DESCRIP>

<SECT1>mailing lists

<P>
There are several mailing lists for IceWM users, developers and for those
just interested in new releases. For more in-depth information about the
lists and on how to subscribe to the lists visit 
<HTMLURL URL="http://sourceforge.net/mail/?group_id=31" 
NAME="http://sourceforge.net/mail/?group_id=31">.

<SECT2>icewm-user

<P>
<DESCRIP>
  <TAG>Purpose:</TAG>
    General discussion and help list for IceWM users
  <TAG>Maintainer:</TAG>
    The IceWM developers team
  <TAG>Archive:</TAG>
    <HTMLURL URL="http://sourceforge.net/mailarchive/forum.php?forum_id=5805"
    NAME="http://sourceforge.net/mailarchive/forum.php?forum_id=5805">
  <TAG>Old archive:</TAG>
    <HTMLURL URL="http://groups.yahoo.com/group/icewm/messages/"
    NAME="http://groups.yahoo.com/group/icewm/messages/">
  <TAG>Subscribe:</TAG>
    <HTMLURL URL="http://lists.sourceforge.net/lists/listinfo/icewm-user/"
    NAME="http://lists.sourceforge.net/lists/listinfo/icewm-user">
  <TAG>Comments:</TAG>
    The place for all things IceWM
</DESCRIP>

<SECT2>icewm-devel

<P>
<DESCRIP>
  <TAG>Purpose:</TAG>
    Discussion of IceWM's development
  <TAG>Maintainer:</TAG>
    The IceWM developers team
  <TAG>Archive:</TAG>
    <HTMLURL URL="http://sourceforge.net/mailarchive/forum.php?forum_id=5806"
    NAME="http://sourceforge.net/mailarchive/forum.php?forum_id=5806">
  <TAG>Comments:</TAG>
    Only for code related questions, patches, bugfixes.
</DESCRIP>
<SECT1>IRC channel

<P>
channel "#icewm" on the Freenodes 
<HTMLURL URL="http://www.freenode.info/"
NAME="http://www.freenode.info/">

<P>
<DESCRIP>
  <TAG>Purpose:</TAG>
    Discussing IceWM, helping IceWM users
  <TAG>Maintainer:</TAG>
    The IceWM IRC team
  <TAG>Archive:</TAG>
    <HTMLURL URL="http://www.maol.ch/irc/?channel=icewm"
    NAME="http://www.maol.ch/irc/?channel=icewm">
</DESCRIP>

<SECT>License

<P>
This document is released under the terms of the GNU Library General Public License.

<APPENDIX>
<SECT>Recent Changes to this document

<P>
This section keeps you informed what parts of this document changed
recently.

<ITEMIZE>
  <ITEM>
    Adam Pribyl, translation howto, Vadims idesk lnk maker add, minor correction. (2004/03/01)
  <ITEM>
    Adam Pribyl, font handling problem question and answer. (2004/02/10)
  <ITEM>
    Adam Pribyl, startup script section improvements, corrected path in example section (thx to Michael Dipperstein), MFAQ add showdestop
  <ITEM>
    Adam Pribyl, added icewm-session to most FAQ; Fulltext advice made more visible;
    Section Example configuration A-Z added - this is preliminary version - comments welcomed. (2003/10/14)
  <ITEM>
    Adam Pribyl, added idesk and dfm links to tools section. icewm-session
    and prefoverride added. Some small improvements. (2003/09/14)
  <ITEM>
    Adam Pribyl, updated Howto prevent IceWM from grabbing keystrokes, with text sent by Marco Molteni. 
    Some more hyperlinking. (2003/09/11)
  <ITEM>
    Adam Pribyl, updates to reflect latest icewm development (icewmtray, icewmbg,
    .icewm/theme). License note add. MenuMaker add. Minor hyperlink and some answers updates. (2003/08/25)
  <ITEM>
    Adam Pribyl makes some answers more accurate, added IceMC, bigger icons answer.
    (2003/05/10)
  <ITEM>
    Adam Pribyl updated FAQs to fit nowadays needs, put them on
    icewm.org site and added few new things. (2003/03/29)
  <ITEM>
    New maintainer. Markus Ackermann took over and reorganized much of the
    FAQ. I've even renamed it to "IceWM FAQ and Howto", since that's what it's already
    been. Moved homepage of the English version to <HTMLURL
    URL="http://icewm.maol.ch/FAQ/" NAME="http://icewm.maol.ch/FAQ/">
    (2001/07/25).
  <ITEM>
    Revision of FAQ because some formats (Postscript for example)
    weren't OK (2000/01/08).
  <ITEM>
    Added sections <EM>"Switching Desktop using keyboard"</EM> and
    <EM>"Moving windows between desktops using keyboard"</EM>
    (2000/01/08).
  <ITEM>
    IceWM homepage has moved, update URL (1999/12/26).
  <ITEM>
    This section has been added (1999/10/10).
  <ITEM>
    The themes.org site <HTMLURL URL="http://icewm.themes.org/"
    NAME="icewm.themes.org"> is up now. This information has been
    added to <REF ID="icewebpages" NAME="IceWM related web pages">
    section (1999/10/10).
  <ITEM>
    Contact mail address has been changed to <HTMLURL
    URL="mailto:jupp@themes.org" NAME="jupp@themes.org">
    (1999/10/10).
</ITEMIZE>


</ARTICLE>
