FvwmTheme(1)                     Fvwm Modules                     FvwmTheme(1)



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


SYNOPSIS
       ModuleSynchronous Timeout 5 FvwmTheme

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


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.


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.

       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 ImagePath has been defined.  Invoking FvwmTheme from the
       InitFunction, StartFunction or RestartFunction 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.


CONFIGURATION OPTIONS
       FvwmTheme supports some configuration options.


       *FvwmTheme: Colorset n options
              Creates or modifies colorset n. 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.

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

              fg, Fore and Foreground take a color name as an argument and set
              the foreground color.  The special name 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.

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

              hi, Hilite and 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.

              sh, Shade and 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.

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

              Pixmap, TiledPixmap and AspectPixmap take a file name as an
              argument, search the 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 one from
              the colorset.  TiledPixmap produces repeated copies of the image
              with no scaling, Pixmap causes the image to be stretched to fit
              whatever object the colorset is applied to and AspectPixmap
              stretches to fit but retains the image aspect ratio.

              Transparent 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 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:
              xv -root -quit mybg.png; fvwm-root -d
              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 OpaqueMoveSize command
              and the ResizeOpaque style) as well as setting the
              WindowShadeShrinks style may help. The transparency achieved
              with 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:
              Colorset 12 VGradient 200 grey30 grey60
              Colorset 17 Transparent
              *FvwmIconMan: Colorset 12
              *FvwmIconMan: PlainColorset 17
              gives an IconMan with a vertical grey gradient background and
              the buttons use the background (by transparency). To obtain a
              (root) transparent IconMan:
              Colorset 12 Transparent
              Colorset 17 Transparent
              Colorset 18 Transparent
              Colorset 19 Transparent
              *FvwmIconMan: Colorset 12
              *FvwmIconMan: PlainColorset 17
              *FvwmIconMan: FocusColorset 18
              *FvwmIconMan: IconColorset  19
              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:
              FvwmButtons:(Colorset 10, Swallow "FvwmIconMan" 'FvwmIconMan')
              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 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.  Tint may work or not with the
              Transparent option. When the colorset is drawn on the foreground
              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
              RootTransparent option.

              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 buffer keyword is useful only when the 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 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.

              Shape, TiledShape and AspectShape take a file name as an
              argument, search the ImagePath and use it as the shape bitmap.
              TiledShape produces repeated copies of the bitmap with no
              scaling, Shape causes the bitmap to be stretched to fit whatever
              object the colorset is applied to and AspectShape 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.

              ?Gradient ... creates a pixmap and stretches it to fit the
              window.  ?Gradient 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 that mad).  Please refer to the COLOR GRADIENTS section in
              the fvwm man page for the syntax of gradients.

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

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

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

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

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

              Dither causes fvwm to dither the image defined using ?Pixmap or
              ?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.
              NoDither causes fvwm to do not dither the images.  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 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.

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

              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.

              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.

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


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.


       SendToModule FvwmTheme Colorset options
              The syntax is the same as the configuration option.


EXAMPLES
       *FvwmTheme: Colorset 3 fg wheat, bg navy

       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.

       *FvwmTheme: Colorset 3 bg "navy blue"

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

       *FvwmTheme: Colorset 3 AspectPixmap large_murky_dungeon.xpm

       Causes depression.

       *FvwmTheme: Colorset 3 bg Average

       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.

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

       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.

        #!/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

       Makes colorset 7 blink.

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


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.

        # 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

       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:

        http://fvwm-themes.sourceforge.net/doc/colorsets


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


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


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.



3rd Berkeley Distribution    20 April 2012 (2.6.5)                FvwmTheme(1)
