Apply window-jump fix (D. Fries).

[fvwm.git] / modules / FvwmTheme / FvwmTheme.1.in

.\" t
.\" @(#)@PACKAGE@-@VERSION@ @RELDATELONG@
.de EX          \"Begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.in +.5i
..
.de EE
.fi
.in -.5i
.if n .sp 1
.if t .sp .5
..
.ta .3i .6i .9i 1.2i 1.5i 1.8i
.TH FvwmTheme 1 "@RELDATELONG@ (@VERSION@)" Fvwm "Fvwm Modules"
.UC

.SH NAME
FvwmTheme \- an fvwm module for managing the appearance of fvwm and its modules

.SH SYNOPSIS
ModuleSynchronous Timeout 5 FvwmTheme

\fBFvwmTheme\fP can only be invoked by fvwm.
Command line invocation of the FvwmTheme module will not work.

.SH DESCRIPTION
FvwmTheme creates appearance resources that may be shared by fvwm and other
modules.  It reads an initial configuration and also reacts to configuration
commands and messages sent from fvwm so that the resources can be dynamically
changed.

.SH INVOCATION
Starting with 2.5.1, FvwmTheme is obsolete, please read fvwm man page
about the built-in colorsets solution.  However, all options are still
the same, so this man page defines the exact Colorset syntax.

FvwmTheme must be spawned as a module by fvwm.
.PP
It is highly suggested that FvwmTheme is invoked before any other modules
that use the colorsets provided by FvwmTheme.  Thus FvwmTheme has
to be invoked with the 'ModuleSynchronous' command by inserting the
line 'ModuleSynchronous Timeout 5 FvwmTheme' in the .fvwm2rc file
right after the \fIImagePath\fP has been defined.
Invoking FvwmTheme from the \fIInitFunction\fP, \fIStartFunction\fP
or \fIRestartFunction\fP or later can cause excessive redrawing of
already running modules.  It is highly suggested
that the configuration lines for FvwmTheme appear in the configuration
file before FvwmTheme is started.  You can find a proper sample
fvwm setup at the end of this document.
It is pointless to run more than one FvwmTheme
so there is no provision for using an alias name.

.SH CONFIGURATION OPTIONS
FvwmTheme supports some configuration options.

.IP "*FvwmTheme: Colorset \fIn\fP \fIoptions\fP "
Creates or modifies colorset \fIn\fP. 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.

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.

\fIoptions\fP 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, NoShape and Plain.

\fIfg\fP, \fIFore\fP and \fIForeground\fP take a color name as an argument and
set the foreground color.  The special name \fIContrast\fP 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.

\fIbg\fP, \fIBack\fP and \fIBackground\fP 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 \fIAverage\fP may be used to select a color
that is the average color of the pixmap.
If the pixmap is tinted with the
.I Tint
option, the tint is not taken in account in the computation of the average
color. You should use the
.I bgTint
option to get the "real" average color.
The background color is reset to the default value if the color name is omitted.

\fIhi\fP, \fIHilite\fP and \fIHilight\fP 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.

\fIsh\fP, \fIShade\fP and \fIShadow\fP 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.

.I fgsh
takes a color name as an argument and sets the color used by the
shadowing font effect. See the
.B 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.

\fIPixmap\fP, \fITiledPixmap\fP and \fIAspectPixmap\fP take a file name as
an argument, search the \fIImagePath\fP and use it as the background pixmap.
Any transparent parts are filled with the background color.  Not specifying a
file name removes any existing one from the colorset.  \fITiledPixmap\fP
produces repeated copies of the image with no scaling, \fIPixmap\fP
causes the image to be stretched to fit whatever object the colorset is applied
to and \fIAspectPixmap\fP stretches to fit but retains the image
aspect ratio.

\fITransparent\fP tries to create a transparent background pixmap.
The pixmap may be used as a window background to achieve root transparency.
For this you should use the
.B ParentalRelativity
fvwm style.
The root background change may be detected or not, this depends on the program
used to set the background. If you use fvwm-root, xsetbg (xli),
FvwmBacker with a solid or a colorset colors or a recent version of Esetroot
(>= 9.2) a background change should be detected. If background changes are not
detected (e.g., if you use xv or xsetroot) you can force detection by using
the -d option of fvwm-root:
.EX
xv -root -quit mybg.png; fvwm-root -d
.EE
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.

Using outline move and resize (see the
.B OpaqueMoveSize
command and the
.I ResizeOpaque
style) as well as setting the
.I WindowShadeShrinks
style may help. The transparency achieved with
.I Transparent
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:
.EX
Colorset 12 VGradient 200 grey30 grey60
Colorset 17 Transparent
*FvwmIconMan: Colorset 12
*FvwmIconMan: PlainColorset 17
.EE
gives an IconMan with a vertical grey gradient background and the
buttons use the background (by transparency). To obtain a
(root) transparent IconMan:
.EX
Colorset 12 Transparent
Colorset 17 Transparent
Colorset 18 Transparent
Colorset 19 Transparent
...
*FvwmIconMan: Colorset 12
*FvwmIconMan: PlainColorset 17
*FvwmIconMan: FocusColorset 18
*FvwmIconMan: IconColorset  19
.EE
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:
.EX
FvwmButtons:(Colorset 10, Swallow "FvwmIconMan" 'FvwmIconMan')
.EE
then, IconMan become a child of FvwmButtons and it is transparent
relative to FvwmButtons. So, in this case IconMan uses Colorset
10 as background. If you want root transparency
use the
.I RootTransparent
option. FvwmButtons, FvwmIconMan, FvwmIdent, FvwmScroll and
FvwmTaskBar 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 FvwmWinList and
FvwmProxy are simpler. With FvwmWinList all the colorsets are drawn on
the foreground and with FvwmProxy the two colorsets refer to the
window backgrounds. 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 FvwmForm and 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.
.I Tint
may work or not with the
.I Transparent
option. When the colorset is drawn on the foreground
.I Tint
should work. In the other cases, tinting works in some exceptional cases
(and may be very slow). Tinting may work with fvwm menu (without
animation). In the other case tinting may work if your X server has
backing store enabled (try xdpyinfo to see if this the case).
But, 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
.I RootTransparent
option.

.IR RootTransparent " [ " buffer " ] "
creates a root transparent background. To make this option work, you
must use an Esetroot compatible program, fvwm-root with the
--retain-pixmap option or FvwmBacker with the RetainPixmap option (and
colorset or solid backgrounds).  The
.I buffer
keyword is useful only when the
.I Tint
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
.IR buffer .
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.

\fIShape\fP, \fITiledShape\fP and \fIAspectShape\fP take a file name as
an argument, search the \fIImagePath\fP and use it as the shape bitmap.
\fITiledShape\fP produces repeated copies of the bitmap with no scaling,
\fIShape\fP causes the bitmap to be stretched to fit whatever object the
colorset is applied to and \fIAspectShape\fP stretches to fit but
retains the bitmap aspect ratio.  If the file is a pixmap in xpm format,
the shape mask of the pixmap is used.

Warning: Due to the way X11 implements shapes and the implementation
of the FvwmTheme module you cannot take back making windows shaped.
You may have to restart fvwm or the shaped application.

\fI?Gradient ...\fP creates a pixmap and stretches it to fit the window.
\fI?Gradient\fP may be one of HGradient, VGradient, DGradient, BGradient,
SGradient, CGradient, RGradient or 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, we are not \fIthat\fP mad).
Please refer to the \fICOLOR GRADIENTS\fP section in the \fIfvwm\fP man page
for the syntax of gradients.

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

.I fgTint
takes 2 arguments, a color and a percentage between 0 and 100.
It causes the color defined using
.I fg
to be tinted with the specified color using the percentage.
With no arguments this option removes the tint.

.I bgTint
takes 2 arguments, a color and a percentage between 0 and 100.
It causes the color defined using
.I bg
to be tinted with the specified color using the percentage.
If the
.I sh
and
.I hi
colors are not specified, they are recomputed from the tinted bg color.
With no arguments this option removes the tint.

.I Alpha
takes a percentage between 0 and 100 as an argument.
It causes fvwm to merge the image defined using
.I ?Pixmap
or
.I ?Gradient
with the
.I bg
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.

.I 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
.B FONT NAMES AND FONT LOADING
section of fvwm man page.
The default is 100 and it is restored if no argument is given.

.I Dither
causes fvwm to dither the image defined using
.I ?Pixmap
or
.I ?Gradient.
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.
.I NoDither
causes fvwm to do not dither the images.
.I Dither
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
.IR NoDither ,
however this effect can be useful with images which contain
a lot of close colors. For example a fine gradient will look
more smooth.

.I 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
.I Icon
FvwmButtons button option) ...etc.
With no arguments this option removes the icon tint.

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

.IR Note :
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.

.I NoShape
removes the shape mask from the colorset while
.I Plain
removes the background pixmap or gradient.

.SH COMMANDS
The following fvwm command may be executed at any time to alter the colorsets.
It may be bound to a menu item or typed into a module such as FvwmConsole.

.IP "SendToModule FvwmTheme Colorset \fIoptions\fP"
The syntax is the same as the configuration option.

.SH EXAMPLES

.EX
*FvwmTheme: Colorset 3 fg wheat, bg navy
.EE

If necessary this creates colorsets 0, 1, 2 and 3 and then changes colorset
3 to have a foreground of wheat, a background of navy.

.EX
*FvwmTheme: Colorset 3 bg "navy blue"
.EE

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

.EX
*FvwmTheme: Colorset 3 AspectPixmap large_murky_dungeon.xpm
.EE

Causes depression.

.EX
*FvwmTheme: Colorset 3 bg Average
.EE

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.

.EX
*FvwmTheme: Colorset 3 YGradient 200 3 \\
  blue 1000 navy 1 blue 1000 navy
.EE

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.

.EX
 #!/bin/sh
 FvwmCommand "SendToModule FvwmTheme Colorset 7 fg navy, bg gray"
 while true
 do
   FvwmCommand "SendToModule FvwmTheme Colorset 7 fg gray"
   sleep 1
   FvwmCommand "SendToModule FvwmTheme Colorset 7 fg navy"
   sleep 1
 done
.EE

Makes colorset 7 blink.

The color names used in colorsets can be substituted in any fvwm
command.  Please refer to the \fICOMMAND EXPANSION\fP
section in the fvwm man page and the example below for a description.

.SH SAMPLE FVWM CONFIGURATION

Below you can find a fvwm configuration file that demonstrates the
use of the FvwmTheme module.  The order in which FvwmTheme and the
other modules are configured and started is important.

.EX
 # where your images are
 ImagePath <put your image path here>

 #
 # FvwmTheme
 #
 # The FvwmTheme setup must be first in the config file,
 # right after the paths are set.
 #
 # Instead of the *FvwmTheme: Colorset... lines below you
 # could read in a file with these commands.  So to change
 # your color scheme you can simply copy a different file
 # over your palette file and restart fvwm:
 #
 # Read /home/my_user_name/.fvwm/.fvwm_palette
 #

 # 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
 *FvwmTheme: Colorset 0 fg black, bg rgb:b4/aa/94
 *FvwmTheme: Colorset 1 fg black, bg rgb:a1/b2/c8
 *FvwmTheme: Colorset 2 fg black, bg rgb:da/9a/68
 *FvwmTheme: Colorset 3 fg black, bg rgb:b4/aa/94, \\
   VGradient 100 dtcolor5 rgb:b4/aa/94
 *FvwmTheme: Colorset 4 fg black, bg rgb:b4/aa/94
 *FvwmTheme: Colorset 5 fg rgb:d2/bf/a8, \\
   bg rgb:b4/aa/94
 *FvwmTheme: Colorset 6 fg black, bg rgb:b4/aa/94, \\
   VGradient 100 dtcolor5 rgb:b4/aa/94
 *FvwmTheme: Colorset 7 fg black, bg rgb:94/ab/bf

 # run FvwmTheme before anything else is done
 ModuleSynchronous Timeout 5 FvwmTheme

 #
 # general setup
 #
 Style * Colorset 1
 Style * HilightColorset 2
 MenuStyle * MenuColorset 3
 MenuStyle * ActiveColorset 4
 MenuStyle * GreyedColorset 5

 #
 # Applications
 #
 AddToFunc InitFunction
 + I Exec exec xterm -fg $[fg.cs0] -bg $[bg.cs0]

 #
 # module setup
 #

 # ... more FvwmPager config lines ...
 *FvwmPager: Colorset * 6
 *FvwmPager: BalloonColorset * 6
 *FvwmPager: HilightColorset * 7
 *FvwmPager: WindowColorsets 1 2

 # ... more FvwmIconMan config lines ...
 *FvwmIconMan: Colorset 6
 *FvwmIconMan: FocusColorset 2
 *FvwmIconMan: FocusAndSelectColorset 2
 *FvwmIconMan: PlainColorset 6
 *FvwmIconMan: SelectColorset 6
 *FvwmIconMan: TitleColorset 6

 # ... more FvwmButtons config lines ...
 *FvwmButtons: Colorset 6
 # sample button passing color to xterm
 *FvwmButtons: (Title xterm, \\
   Action "Exec exec xterm -fg $[fg.cs6] -bg[bg.cs6]")

 # ... more FvwmWharf config lines ...
 *FvwmWharf: Colorset 6

 # ... more FvwmIdent config lines ...
 *FvwmIdent: Colorset 6

 # ... more FvwmWinList config lines ...
 *FvwmWinList: Colorset      1
 *FvwmWinList: FocusColorset 2
 *FvwmWinList: IconColorset  1

 # ... more FvwmTaskBar config lines ...
 *FvwmTaskBar: Colorset     6
 *FvwmTaskBar: IconColorset 6
 *FvwmTaskBar: TipsColorset 0
.EE

If you need to have more colors and don't 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:

 \fBhttp://fvwm-themes.sourceforge.net/doc/colorsets\fP

.SH BUGS

Initialization of fvwm, FvwmTheme and the other modules is tricky.
Please pay close attention to the text in the \fIINVOCATION\fP
section.  The example above demonstrates the proper way to get a
FvwmTheme setup running.

.SH AUTHOR

Prefers to remain anonymous.
With help from Brad Giaccio and Dominik Vogt.

.SH COPYRIGHT
Copyright (C) 1999 Joey Shutup.  No guarantees or warranties or anything are
provided or implied in any way whatsoever.  Use this program at your own risk.
Permission to use this program for any purpose is given, as long as the
copyright is kept intact.