xenial (1) FvwmTheme.1.gz

Provided by: fvwm_2.6.5.ds-4.1_amd64 bug

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