<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "../docbook-xml/docbookx.dtd"
[
<!ENTITY % myents SYSTEM "../fvwm.ent" >
%myents;
]>

<!-- $Id$ -->

<section id='Colorset'>
<title>Colorset</title>

<cmdsynopsis>
	<command>Colorset</command
	><arg choice='plain'
		><replaceable>num</replaceable
	></arg
	><arg choice='opt'
		><replaceable>options</replaceable
	></arg>
</cmdsynopsis>

<para>Creates or modifies colorset
<replaceable>num</replaceable>.
Colorsets are identified by this number. The number can start at
zero and can be a very large number.</para>

<para>Warning: The highest colorset number used determines memory
consumption. Thus, if you define 'Colorset 100000', the memory for
100001 colorsets is used.  Keep your colorset numbers as small as
possible.</para>

<para>By convention, colorsets are numbered like this:</para>

<programlisting>
# 0 = Default colors
# 1 = Inactive windows
# 2 = Active windows
# 3 = Inactive menu entry and menu background
# 4 = Active menu entry
# 5 = greyed out menu entry (only bg used)
# 6 = module foreground and background
# 7 = hilight colors
</programlisting>


<para>If you need to have more colors and do not want to reinvent the
wheel, you may use the convention used in fvwm-themes, it defines
the meaning of the first 40 colorsets for nearly all purposes:</para>

<para>
<ulink url='http://fvwm-themes.sourceforge.net/doc/colorsets'>http://fvwm-themes.sourceforge.net/doc/colorsets</ulink></para>

<para>Each colorset has four colors, an optional pixmap and an optional
shape mask.  The four colors are used by modules as the
foreground, background, highlight and shadow colors.  When a
colorset is created it defaults to a foreground of black and
background of gray.  The background and foreground are marked as
"average" and "contrast" (see later) so that just specifying a
pixmap or gradient gives sensible results.</para>

<para><replaceable>options</replaceable>
is a comma separated list containing some of the keywords:
fg, Fore, Foreground,
bg, Back, Background,
hi, Hilite, Hilight,
sh, Shade, Shadow,
fgsh,
Pixmap, TiledPixmap, AspectPixmap,
Transparent, RootTransparent,
Shape, TiledShape, AspectShape, NoShape,
?Gradient,
Tint, fgTint, bgTint,
Alpha, fgAlpha,
Dither, NoDither,
IconTint,
IconAlpha,
Plain.</para>

<para>
<fvwmopt cmd="Colorset" opt="fg"/>,
<fvwmopt cmd="Colorset" opt="Fore"/> and
<fvwmopt cmd="Colorset" opt="Foreground"/>
take a color name as an argument and set the foreground color.
The special name
<fvwmopt cmd="Colorset" opt="Contrast"/>
may be used to select a color that contrasts well with the
background color.  To reset the foreground color to the default
value you can simply omit the color name.</para>

<para>
<fvwmopt cmd="Colorset" opt="bg"/>,
<fvwmopt cmd="Colorset" opt="Back"/> and
<fvwmopt cmd="Colorset" opt="Background"/>
take a color name as an argument and set the background color.  It
also sets the highlight and shadow colors to values that give a 3d
effect unless these have been explicitly set with the options
below.  The special name
<fvwmopt cmd="Colorset" opt="Average"/>
may be used to select a color that is the average color of the
pixmap.  If the pixmap is tinted with the
<emphasis remap='I'>Tint</emphasis>
option, the tint is not taken in account in the computation of the
average color. You should use the
<emphasis remap='I'>bgTint</emphasis>
option to get the "real" average color.  The background color is
reset to the default value if the color name is omitted.</para>

<para>
<fvwmopt cmd="Colorset" opt="hi"/>,
<fvwmopt cmd="Colorset" opt="Hilite"/> and
<fvwmopt cmd="Colorset" opt="Hilight"/>
take a color name as an argument and set the highlight color.  If
the highlight color is not explicitly set, the default is to
calculate it from the background color.  To switch back to the
default behavior the color name can be omitted.</para>

<para>
<fvwmopt cmd="Colorset" opt="sh"/>,
<fvwmopt cmd="Colorset" opt="Shade"/> and
<fvwmopt cmd="Colorset" opt="Shadow"/>
take a color name as an argument and set the shadow color.  If the
shadow color is not explicitly set, the default is to calculate it
from the background color.  To switch back to the default behavior
the color name can be omitted.</para>

<para>
<fvwmopt cmd="Colorset" opt="fgsh"/>
takes a color name as an argument and sets the color used by the
shadowing font effect. See the
<fvwmref sect="fonts" opt="font_shadow_effects" name="Font Shadow Effects"/>
section of the fvwm man page.  By default this color is computed
from the foreground and background colors.  To switch back to the
default the color name can be omitted.</para>

<para>
<fvwmopt cmd="Colorset" opt="Pixmap"/>,
<fvwmopt cmd="Colorset" opt="TiledPixmap"/> and
<fvwmopt cmd="Colorset" opt="AspectPixmap"/>
take a file name as an argument, search the
<fvwmref cmd="ImagePath"/>
and use it as the background pixmap.  Any transparent parts are
filled with the background color.  Not specifying a file name
removes any existing image from the colorset.
<emphasis remap='I'>TiledPixmap</emphasis>
produces repeated copies of the image with no scaling,
<emphasis remap='I'>Pixmap</emphasis>
causes the image to be stretched to fit whatever object the
colorset is applied to and
<emphasis remap='I'>AspectPixmap</emphasis>
stretches to fit but retains the image aspect ratio.</para>

<para>
<fvwmopt cmd="Colorset" opt="Transparent"/>
creates a transparent background pixmap.  The pixmap is used as a
window background to achieve root transparency.  For this you
should use the
<fvwmref cmd="Style" opt="ParentalRelativity"/>
option to the
<fvwmref cmd="Style"/>
command.
A subsequent root background change may be detected or not, this
depends on the program used to set the background.  If you use
<command>fvwm-root</command>, <command>xsetbg</command> (xli),
<fvwmref mod="FvwmBacker"/> with solid or colorset colors
or a recent version of <command>Esetroot</command> (&gt;= 9.2) a background change is
detected. If background changes are not detected (e.g., if you use
<command>xv</command> or <command>xsetroot</command>) you can force detection by using the <option>-d</option> option of
fvwm-root:</para>

<programlisting>
xv -root -quit mybg.png; fvwm-root -d
</programlisting>

<para>Due to the way X implements transparency no guarantees can be made
that the desired effect can be achieved.  The application may even
crash.  If you experience any problems with this option, do not
use it.</para>

<para>Using outline move and resize (see the
<fvwmref cmd="OpaqueMoveSize"/>
command and the
<fvwmref cmd="Style" opt="ResizeOpaque"/>
<fvwmref cmd="Style"/>
option) as well as setting the
<fvwmref cmd="Style" opt="WindowShadeShrinks"/>
style may help.  The transparency achieved with
<emphasis remap='I'>Transparent</emphasis>
depends on whether the colorset is applied to the foreground or
the background of a window. In the second case the transparency is
relative to the parent window of the window on which the colorset
is defined.  For example:</para>

<programlisting>
Colorset 12 VGradient 200 grey30 grey60
Colorset 17 Transparent
*<fvwmref mod="FvwmIconMan"/>: Colorset 12
*<fvwmref mod="FvwmIconMan"/>: PlainColorset 17
</programlisting>

<para>gives an IconMan with a vertical grey gradient background and the
buttons use the background (by transparency). To obtain a (root)
transparent IconMan:</para>

<programlisting>
Colorset 12 Transparent
Colorset 17 Transparent
Colorset 18 Transparent
Colorset 19 Transparent

*<fvwmref mod="FvwmIconMan"/>: Colorset 12
*<fvwmref mod="FvwmIconMan"/>: PlainColorset 17
*<fvwmref mod="FvwmIconMan"/>: FocusColorset 18
*<fvwmref mod="FvwmIconMan"/>: IconColorset  19
</programlisting>

<para>The Colorset IconMan option defines the IconMan window background,
but the PlainColorset and the FocusColorset are drawn on the
foreground. So, the transparency of the IconMan buttons is
achieved by drawing nothing.  Now if this IconMan is swallowed in
an FvwmButtons as:</para>

<programlisting>
<fvwmref mod="FvwmButtons"/>:(Colorset 10, Swallow "FvwmIconMan" 'FvwmIconMan')
</programlisting>

<para>then,
<fvwmref mod="FvwmIconMan"/>
becomes a child of
<fvwmref mod="FvwmButtons"/>
and it is transparent relative to
<fvwmref mod="FvwmButtons"/>.
So, in this case
<fvwmref mod="FvwmIconMan"/>
uses Colorset 10 as background. If you want root transparency use
the
<emphasis>RootTransparent</emphasis>
option.
<fvwmref mod="FvwmButtons"/>
<fvwmref mod="FvwmIconMan"/>,
and
<fvwmref mod="FvwmIdent"/>,
are relatively simple. There is one main colorset option which
defines the background of the window and the other colorsets (if
any) are drawn on the foreground. The case of
<fvwmref mod="FvwmProxy"/>
is simpler, the two colorsets refer to the window backgrounds.
<fvwmref mod="FvwmPager"/>
is more complicated as almost everything in the pager are windows
with some parental relations (the mini windows are the child and
the desktops are the parents and all this is complicated by the
hilighted page). So, the colorsets apply to the background of
these windows. You should experiment. For
<fvwmref mod="FvwmForm"/> and
<fvwmref mod="FvwmScript"/>
the situation is similar. There is a main window (a child of the
root window) which corresponds to the main colorset and most of
the widgets are windows which are children of the main window.
<emphasis remap='I'>Tint</emphasis>
may work or not with the
<emphasis remap='I'>Transparent</emphasis>
option. When the colorset is drawn on the foreground
<emphasis remap='I'>Tint</emphasis>
should work. In some cases, tinting may be very slow. Tinting may
work with fvwm menu (without animation). Tinting may work better
if your X server has backing store enabled (try xdpyinfo to see if
this the case). There is a chance that the backing store support
of your X server does not work well with the terrible hack used to
Tint the ParentRelative Pixmap. So, to get tinted root
transparency it is more safe to use the
<emphasis remap='I'>RootTransparent</emphasis>
option.</para>

<para>
<fvwmopt cmd="Colorset" opt="RootTransparent"/> <optional> <emphasis remap='I'>buffer</emphasis> </optional>
creates a root transparent background. To make this option work,
you must use an <command>Esetroot</command> compatible program, fvwm-root with the
--retain-pixmap option or <fvwmref mod="FvwmBacker"/> with the RetainPixmap option
(and colorset or solid backgrounds).  The
<emphasis remap='I'>buffer</emphasis>
keyword is useful only when the
<emphasis remap='I'>Tint</emphasis>
option is used too. This speeds up creation of windows which use
the colorset (useful for fvwm menus) at the cost of memory
usage. It also speeds up opaque move and resize which can be
unacceptably slow without
<emphasis remap='I'>buffer</emphasis>.
However, this option may add a lot of memory to your X server
(depending on the size of the image used to set the
background). In summary, using outline move and resize for modules
which use such a colorset may be a good idea.</para>

<para>
<fvwmopt cmd="Colorset" opt="Shape"/>,
<fvwmopt cmd="Colorset" opt="TiledShape"/> and
<fvwmopt cmd="Colorset" opt="AspectShape"/>
take a file name as an argument, search the
<fvwmref cmd="ImagePath"/>
and use it as the shape bitmap.
<emphasis remap='I'>TiledShape</emphasis>
produces repeated copies of the bitmap with no scaling,
<emphasis remap='I'>Shape</emphasis>
causes the bitmap to be stretched to fit whatever object the
colorset is applied to and
<emphasis remap='I'>AspectShape</emphasis>
stretches to fit but retains the bitmap aspect ratio.  If the file
is a pixmap in xpm format the shape mask (all opaque pixels) of the
pixmap is used.  For png and svg images, the shape mask is equivalent
to all not completely transparent pixels (alpha > 0).</para>

<warning>Due to the way X11 implements shapes you cannot take back
making windows shaped. You may have to restart fvwm or the shaped
application.</warning>

<para>
<emphasis remap='I'>?Gradient ...</emphasis>
creates a pixmap and stretches it to fit the window.
<emphasis remap='I'>?Gradient</emphasis>
may be one of <fvwmopt cmd="Colorset" opt="HGradient"/>, <fvwmopt cmd="Colorset" opt="VGradient"/>,
<fvwmopt cmd="Colorset" opt="DGradient"/>, <fvwmopt cmd="Colorset" opt="BGradient"/>,
<fvwmopt cmd="Colorset" opt="SGradient"/>, <fvwmopt cmd="Colorset" opt="CGradient"/>,
<fvwmopt cmd="Colorset" opt="RGradient"/> or <fvwmopt cmd="Colorset" opt="YGradient"/>.
The gradient types
are as follows:  H is horizontal; V is vertical; D is diagonal
from top left to bottom right; B is a backwards diagonal from
bottom left to top right; S is concentric squares; C is concentric
circles; R is a radar like pattern and Y is a Yin Yang style (but
without the dots).
Please refer to the
<fvwmref sect="colorGradients" opt="color_gradients" name="Color Gradients"/>
section for the syntax of gradients.</para>

<para>
<fvwmopt cmd="Colorset" opt="Tint"/>
takes 2 arguments, a color and a percentage between 0 and 100. It
causes the image defined using
<emphasis remap='I'>?Pixmap</emphasis>
or
<emphasis remap='I'>?Gradient</emphasis>
to be tinted with the specified color using the percentage. If the
image is transparent
<emphasis remap='I'>Tint</emphasis>
tints only the image part. Unfortunately, a colorset background
specified using the
<emphasis remap='I'>Transparent</emphasis>
option can give strange results. See the
<emphasis remap='I'>Transparent</emphasis>
option for details. With no arguments this option removes the
tint.</para>

<para>
<fvwmopt cmd="Colorset" opt="fgTint"/>
takes 2 arguments, a color and a percentage between 0 and 100. It
causes the color defined using
<emphasis remap='I'>fg</emphasis>
to be tinted with the specified color using the percentage. With
no arguments this option removes the tint.</para>

<para>
<fvwmopt cmd="Colorset" opt="bgTint"/>
takes 2 arguments, a color and a percentage between 0 and 100. It
causes the color defined using
<emphasis remap='I'>bg</emphasis>
to be tinted with the specified color using the percentage. If the
<emphasis remap='I'>sh</emphasis>
and
<emphasis remap='I'>hi</emphasis>
colors are not specified, they are recomputed from the tinted bg
color. With no arguments this option removes the tint.</para>

<para>
<fvwmopt cmd="Colorset" opt="Alpha"/>
takes a percentage between 0 and 100 as an argument. It causes
fvwm to merge the image defined using
<emphasis remap='I'>?Pixmap</emphasis>
or
<emphasis remap='I'>?Gradient</emphasis>
with the
<emphasis remap='I'>bg</emphasis>
color using the percentage. If the percentage is 0 the image is
hidden and if it is 100 the image is displayed as usual (no
merge). The default is 100 and it is restored if no argument is
given.</para>

<para>
<fvwmopt cmd="Colorset" opt="fgAlpha"/>
takes a percentage between 0 and 100 as an argument. It causes
fvwm to merge the text and the colorset background using the
percentage. If the percentage is 0 the text is hidden and if it is
100 the text is displayed as usual (no merge). This option has an
effect only with fonts loaded by Xft, see the
<fvwmref sect="fonts" opt="font_names_and_font_loading" name="Font Names and Font Loading"/>
section. The default is 100 and it is restored if no argument is
given.</para>

<para>
<fvwmopt cmd="Colorset" opt="Dither"/>
causes fvwm to dither the image defined using
<emphasis remap='I'>?Pixmap</emphasis>
or
<emphasis remap='I'>?Gradient.</emphasis>
This is useful only with displays with depth less than or equal to
16 (i.e., on displays which can only display less than 65537
colors at once). The dithering effect lets you simulate having
more colors available that you actually have.
<fvwmopt cmd="Colorset" opt="NoDither"/>
causes fvwm to do not dither the images.
<emphasis remap='I'>Dither</emphasis>
is the default if the depth is less than or equal to 8 (a screen
with 256 colors or less). In depth 15 (32768 colors) and 16 (65536
colors), the default is
<emphasis remap='I'>NoDither</emphasis>,
however this effect can be useful with images which contain a lot
of close colors. For example a fine gradient looks more
smooth.</para>

<para>
<fvwmopt cmd="Colorset" opt="IconTint"/>
takes 2 arguments, a color and a percentage between 0 and 100. It
causes fvwm or a module to tint the "icons" which are rendered
into the colorset background with the specified color using a
percentage. Here "icons" means, fvwm Icons, fvwm menu icons,
MiniIcons which represent applications in various modules, images
loaded by modules (e.g., images specified by the
<fvwmref mod="FvwmButtons" opt="Icon"/>
<fvwmref mod="FvwmButtons"/>
button option) ...etc. With no arguments this option removes the
icon tint.</para>

<para>
<fvwmopt cmd="Colorset" opt="IconAlpha"/>
takes a percentage between 0 and 100 as an argument. It causes
fvwm to merge the "icons" which are rendered into the colorset
background using this percentage. The default is 100 and it is
restored if no argument is given.</para>

<para><emphasis remap='I'>Note</emphasis>:
It is equivalent to use "Tint a_color rate" and "Alpha a" if a =
100 and the bg color is a_color. This equivalence does not hold
for IconAlpha and IconTint as the background can be an image or a
gradient (and not a uniform color background).
However, in some cases you can achieve (almost) the same effect by
using IconTint in the place of IconAlpha. This is preferable as,
in general, IconAlpha generates more redrawing than IconTint.</para>

<para>
<fvwmopt cmd="Colorset" opt="NoShape"/>
removes the shape mask from the colorset while
<fvwmopt cmd="Colorset" opt="Plain"/>
removes the background pixmap or gradient.</para>

<para>Examples</para>

<programlisting>
Colorset 3 fg tan, bg navy
</programlisting>


<para>If necessary this creates colorsets 0, 1, 2 and 3 and then changes
colorset 3 to have a foreground of tan, a background of navy.</para>


<programlisting>
Colorset 3 bg "navy blue"
</programlisting>


<para>changes the background color of colorset 3 to navy blue. The
foreground and pixmap are unchanged.</para>


<programlisting>
Colorset 3 AspectPixmap large_murky_dungeon.xpm
</programlisting>


<para>causes depression.</para>


<programlisting>
Colorset 3 bg Average
</programlisting>


<para>Sets the background color and the relief colors to match the
background pixmap. This is the default setting but it must be used
if a background color was specified and is now not required.</para>

<programlisting>
Colorset 3 YGradient 200 3 blue 1000 navy 1 blue 1000 navy
</programlisting>

<para>Adds a Yin Yang gradient background pixmap to colorset 3.  If the
background is set to average it is recomputed along with the
foreground if that is set to contrast.</para>


<programlisting>
#!/bin/sh
<fvwmref mod="FvwmCommand"/> "Colorset 7 fg navy, bg gray"
while true
do
  <fvwmref mod="FvwmCommand"/> "Colorset 7 fg gray"
  sleep 1
  <fvwmref mod="FvwmCommand"/> "Colorset 7 fg navy"
  sleep 1
done
</programlisting>

<para>Makes colorset 7 blink.</para>

<para>The color names used in colorsets are saved as fvwm variables which
can be substituted in any fvwm command. For example:</para>

<programlisting>
<fvwmref cmd="AddToFunc"/> InitFunction
+ I <fvwmref cmd="Exec"/> exec xterm -fg $[fg.cs0] -bg $[bg.cs0]
</programlisting>

<para>Where $[fg.cs0] is the foreground color of colorset zero. Please
refer to the
<fvwmref sect="expansion" opt="command_expansion" name="Command Expansion"/>
section for more information.</para>

</section>