doc/commands/Colorset.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   3   "../docbook-xml/docbookx.dtd"
   4 [
   5 <!ENTITY % myents SYSTEM "../fvwm.ent" >
   6 %myents;
   7 ]>
   8
   9 <!-- $Id: Colorset.xml,v 1.3 2007/06/16 12:38:45 griph Exp $ -->
  10
  11 <section id='Colorset'>
  12 <title>Colorset</title>
  13
  14 <cmdsynopsis>
  15         <command>Colorset</command
  16         ><arg choice='plain'
  17                 ><replaceable>num</replaceable
  18         ></arg
  19         ><arg choice='opt'
  20                 ><replaceable>options</replaceable
  21         ></arg>
  22 </cmdsynopsis>
  23
  24 <para>Creates or modifies colorset
  25 <replaceable>num</replaceable>.
  26 Colorsets are identified by this number. The number can start at
  27 zero and can be a very large number.</para>
  28
  29 <para>Warning: The highest colorset number used determines memory
  30 consumption. Thus, if you define 'Colorset 100000', the memory for
  31 100001 colorsets is used.  Keep your colorset numbers as small as
  32 possible.</para>
  33
  34 <para>By convention, colorsets are numbered like this:</para>
  35
  36 <programlisting>
  37 # 0 = Default colors
  38 # 1 = Inactive windows
  39 # 2 = Active windows
  40 # 3 = Inactive menu entry and menu background
  41 # 4 = Active menu entry
  42 # 5 = greyed out menu entry (only bg used)
  43 # 6 = module foreground and background
  44 # 7 = hilight colors
  45 </programlisting>
  46
  47
  48 <para>If you need to have more colors and do not want to reinvent the
  49 wheel, you may use the convention used in fvwm-themes, it defines
  50 the meaning of the first 40 colorsets for nearly all purposes:</para>
  51
  52 <para>
  53 <ulink url='http://fvwm-themes.sourceforge.net/doc/colorsets'>http://fvwm-themes.sourceforge.net/doc/colorsets</ulink></para>
  54
  55 <para>Each colorset has four colors, an optional pixmap and an optional
  56 shape mask.  The four colors are used by modules as the
  57 foreground, background, highlight and shadow colors.  When a
  58 colorset is created it defaults to a foreground of black and
  59 background of gray.  The background and foreground are marked as
  60 "average" and "contrast" (see later) so that just specifying a
  61 pixmap or gradient gives sensible results.</para>
  62
  63 <para><replaceable>options</replaceable>
  64 is a comma separated list containing some of the keywords:
  65 fg, Fore, Foreground,
  66 bg, Back, Background,
  67 hi, Hilite, Hilight,
  68 sh, Shade, Shadow,
  69 fgsh,
  70 Pixmap, TiledPixmap, AspectPixmap,
  71 Transparent, RootTransparent,
  72 Shape, TiledShape, AspectShape, NoShape,
  73 ?Gradient,
  74 Tint, fgTint, bgTint,
  75 Alpha, fgAlpha,
  76 Dither, NoDither,
  77 IconTint,
  78 IconAlpha,
  79 Plain.</para>
  80
  81 <para>
  82 <fvwmopt cmd="Colorset" opt="fg"/>,
  83 <fvwmopt cmd="Colorset" opt="Fore"/> and
  84 <fvwmopt cmd="Colorset" opt="Foreground"/>
  85 take a color name as an argument and set the foreground color.
  86 The special name
  87 <fvwmopt cmd="Colorset" opt="Contrast"/>
  88 may be used to select a color that contrasts well with the
  89 background color.  To reset the foreground color to the default
  90 value you can simply omit the color name.</para>
  91
  92 <para>
  93 <fvwmopt cmd="Colorset" opt="bg"/>,
  94 <fvwmopt cmd="Colorset" opt="Back"/> and
  95 <fvwmopt cmd="Colorset" opt="Background"/>
  96 take a color name as an argument and set the background color.  It
  97 also sets the highlight and shadow colors to values that give a 3d
  98 effect unless these have been explicitly set with the options
  99 below.  The special name
 100 <fvwmopt cmd="Colorset" opt="Average"/>
 101 may be used to select a color that is the average color of the
 102 pixmap.  If the pixmap is tinted with the
 103 <emphasis remap='I'>Tint</emphasis>
 104 option, the tint is not taken in account in the computation of the
 105 average color. You should use the
 106 <emphasis remap='I'>bgTint</emphasis>
 107 option to get the "real" average color.  The background color is
 108 reset to the default value if the color name is omitted.</para>
 109
 110 <para>
 111 <fvwmopt cmd="Colorset" opt="hi"/>,
 112 <fvwmopt cmd="Colorset" opt="Hilite"/> and
 113 <fvwmopt cmd="Colorset" opt="Hilight"/>
 114 take a color name as an argument and set the highlight color.  If
 115 the highlight color is not explicitly set, the default is to
 116 calculate it from the background color.  To switch back to the
 117 default behavior the color name can be omitted.</para>
 118
 119 <para>
 120 <fvwmopt cmd="Colorset" opt="sh"/>,
 121 <fvwmopt cmd="Colorset" opt="Shade"/> and
 122 <fvwmopt cmd="Colorset" opt="Shadow"/>
 123 take a color name as an argument and set the shadow color.  If the
 124 shadow color is not explicitly set, the default is to calculate it
 125 from the background color.  To switch back to the default behavior
 126 the color name can be omitted.</para>
 127
 128 <para>
 129 <fvwmopt cmd="Colorset" opt="fgsh"/>
 130 takes a color name as an argument and sets the color used by the
 131 shadowing font effect. See the
 132 <fvwmref sect="fonts" opt="font_shadow_effects" name="Font Shadow Effects"/>
 133 section of the fvwm man page.  By default this color is computed
 134 from the foreground and background colors.  To switch back to the
 135 default the color name can be omitted.</para>
 136
 137 <para>
 138 <fvwmopt cmd="Colorset" opt="Pixmap"/>,
 139 <fvwmopt cmd="Colorset" opt="TiledPixmap"/> and
 140 <fvwmopt cmd="Colorset" opt="AspectPixmap"/>
 141 take a file name as an argument, search the
 142 <fvwmref cmd="ImagePath"/>
 143 and use it as the background pixmap.  Any transparent parts are
 144 filled with the background color.  Not specifying a file name
 145 removes any existing image from the colorset.
 146 <emphasis remap='I'>TiledPixmap</emphasis>
 147 produces repeated copies of the image with no scaling,
 148 <emphasis remap='I'>Pixmap</emphasis>
 149 causes the image to be stretched to fit whatever object the
 150 colorset is applied to and
 151 <emphasis remap='I'>AspectPixmap</emphasis>
 152 stretches to fit but retains the image aspect ratio.</para>
 153
 154 <para>
 155 <fvwmopt cmd="Colorset" opt="Transparent"/>
 156 creates a transparent background pixmap.  The pixmap is used as a
 157 window background to achieve root transparency.  For this you
 158 should use the
 159 <fvwmref cmd="Style" opt="ParentalRelativity"/>
 160 option to the
 161 <fvwmref cmd="Style"/>
 162 command.
 163 A subsequent root background change may be detected or not, this
 164 depends on the program used to set the background.  If you use
 165 <command>fvwm-root</command>, <command>xsetbg</command> (xli),
 166 <fvwmref mod="FvwmBacker"/> with solid or colorset colors
 167 or a recent version of <command>Esetroot</command> (&gt;= 9.2) a background change is
 168 detected. If background changes are not detected (e.g., if you use
 169 <command>xv</command> or <command>xsetroot</command>) you can force detection by using the <option>-d</option> option of
 170 fvwm-root:</para>
 171
 172 <programlisting>
 173 xv -root -quit mybg.png; fvwm-root -d
 174 </programlisting>
 175
 176 <para>Due to the way X implements transparency no guarantees can be made
 177 that the desired effect can be achieved.  The application may even
 178 crash.  If you experience any problems with this option, do not
 179 use it.</para>
 180
 181 <para>Using outline move and resize (see the
 182 <fvwmref cmd="OpaqueMoveSize"/>
 183 command and the
 184 <fvwmref cmd="Style" opt="ResizeOpaque"/>
 185 <fvwmref cmd="Style"/>
 186 option) as well as setting the
 187 <fvwmref cmd="Style" opt="WindowShadeShrinks"/>
 188 style may help.  The transparency achieved with
 189 <emphasis remap='I'>Transparent</emphasis>
 190 depends on whether the colorset is applied to the foreground or
 191 the background of a window. In the second case the transparency is
 192 relative to the parent window of the window on which the colorset
 193 is defined.  For example:</para>
 194
 195 <programlisting>
 196 Colorset 12 VGradient 200 grey30 grey60
 197 Colorset 17 Transparent
 198 *<fvwmref mod="FvwmIconMan"/>: Colorset 12
 199 *<fvwmref mod="FvwmIconMan"/>: PlainColorset 17
 200 </programlisting>
 201
 202 <para>gives an IconMan with a vertical grey gradient background and the
 203 buttons use the background (by transparency). To obtain a (root)
 204 transparent IconMan:</para>
 205
 206 <programlisting>
 207 Colorset 12 Transparent
 208 Colorset 17 Transparent
 209 Colorset 18 Transparent
 210 Colorset 19 Transparent
 211
 212 *<fvwmref mod="FvwmIconMan"/>: Colorset 12
 213 *<fvwmref mod="FvwmIconMan"/>: PlainColorset 17
 214 *<fvwmref mod="FvwmIconMan"/>: FocusColorset 18
 215 *<fvwmref mod="FvwmIconMan"/>: IconColorset  19
 216 </programlisting>
 217
 218 <para>The Colorset IconMan option defines the IconMan window background,
 219 but the PlainColorset and the FocusColorset are drawn on the
 220 foreground. So, the transparency of the IconMan buttons is
 221 achieved by drawing nothing.  Now if this IconMan is swallowed in
 222 an FvwmButtons as:</para>
 223
 224 <programlisting>
 225 <fvwmref mod="FvwmButtons"/>:(Colorset 10, Swallow "FvwmIconMan" 'FvwmIconMan')
 226 </programlisting>
 227
 228 <para>then,
 229 <fvwmref mod="FvwmIconMan"/>
 230 becomes a child of
 231 <fvwmref mod="FvwmButtons"/>
 232 and it is transparent relative to
 233 <fvwmref mod="FvwmButtons"/>.
 234 So, in this case
 235 <fvwmref mod="FvwmIconMan"/>
 236 uses Colorset 10 as background. If you want root transparency use
 237 the
 238 <emphasis>RootTransparent</emphasis>
 239 option.
 240 <fvwmref mod="FvwmButtons"/>,
 241 <fvwmref mod="FvwmIconMan"/>,
 242 <fvwmref mod="FvwmIdent"/>,
 243 <fvwmref mod="FvwmScroll"/>
 244 and
 245 <fvwmref mod="FvwmTaskBar"/>
 246 are relatively simple. There is one main colorset option which
 247 defines the background of the window and the other colorsets (if
 248 any) are drawn on the foreground. The case of
 249 <fvwmref mod="FvwmWinList"/> and
 250 <fvwmref mod="FvwmProxy"/>
 251 are simpler. With
 252 <fvwmref mod="FvwmWinList"/>
 253 all the colorsets are drawn on the foreground and with
 254 <fvwmref mod="FvwmProxy"/>
 255 the two colorsets refer to the window backgrounds.
 256 <fvwmref mod="FvwmPager"/>
 257 is more complicated as almost everything in the pager are windows
 258 with some parental relations (the mini windows are the child and
 259 the desktops are the parents and all this is complicated by the
 260 hilighted page). So, the colorsets apply to the background of
 261 these windows. You should experiment. For
 262 <fvwmref mod="FvwmForm"/> and
 263 <fvwmref mod="FvwmScript"/>
 264 the situation is similar. There is a main window (a child of the
 265 root window) which corresponds to the main colorset and most of
 266 the widgets are windows which are children of the main window.
 267 <emphasis remap='I'>Tint</emphasis>
 268 may work or not with the
 269 <emphasis remap='I'>Transparent</emphasis>
 270 option. When the colorset is drawn on the foreground
 271 <emphasis remap='I'>Tint</emphasis>
 272 should work. In some cases, tinting may be very slow. Tinting may
 273 work with fvwm menu (without animation). Tinting may work better
 274 if your X server has backing store enabled (try xdpyinfo to see if
 275 this the case). There is a chance that the backing store support
 276 of your X server does not work well with the terrible hack used to
 277 Tint the ParentRelative Pixmap. So, to get tinted root
 278 transparency it is more safe to use the
 279 <emphasis remap='I'>RootTransparent</emphasis>
 280 option.</para>
 281
 282 <para>
 283 <fvwmopt cmd="Colorset" opt="RootTransparent"/> <optional> <emphasis remap='I'>buffer</emphasis> </optional>
 284 creates a root transparent background. To make this option work,
 285 you must use an <command>Esetroot</command> compatible program, fvwm-root with the
 286 --retain-pixmap option or <fvwmref mod="FvwmBacker"/> with the RetainPixmap option
 287 (and colorset or solid backgrounds).  The
 288 <emphasis remap='I'>buffer</emphasis>
 289 keyword is useful only when the
 290 <emphasis remap='I'>Tint</emphasis>
 291 option is used too. This speeds up creation of windows which use
 292 the colorset (useful for fvwm menus) at the cost of memory
 293 usage. It also speeds up opaque move and resize which can be
 294 unacceptably slow without
 295 <emphasis remap='I'>buffer</emphasis>.
 296 However, this option may add a lot of memory to your X server
 297 (depending on the size of the image used to set the
 298 background). In summary, using outline move and resize for modules
 299 which use such a colorset may be a good idea.</para>
 300
 301 <para>
 302 <fvwmopt cmd="Colorset" opt="Shape"/>,
 303 <fvwmopt cmd="Colorset" opt="TiledShape"/> and
 304 <fvwmopt cmd="Colorset" opt="AspectShape"/>
 305 take a file name as an argument, search the
 306 <fvwmref cmd="ImagePath"/>
 307 and use it as the shape bitmap.
 308 <emphasis remap='I'>TiledShape</emphasis>
 309 produces repeated copies of the bitmap with no scaling,
 310 <emphasis remap='I'>Shape</emphasis>
 311 causes the bitmap to be stretched to fit whatever object the
 312 colorset is applied to and
 313 <emphasis remap='I'>AspectShape</emphasis>
 314 stretches to fit but retains the bitmap aspect ratio.  If the file
 315 is a pixmap in xpm format the shape mask (all opaque pixels) of the
 316 pixmap is used.  For png and svg images, the shape mask is equivalent
 317 to all not completely transparent pixels (alpha > 0).</para>
 318
 319 <warning>Due to the way X11 implements shapes you cannot take back
 320 making windows shaped. You may have to restart fvwm or the shaped
 321 application.</warning>
 322
 323 <para>
 324 <emphasis remap='I'>?Gradient ...</emphasis>
 325 creates a pixmap and stretches it to fit the window.
 326 <emphasis remap='I'>?Gradient</emphasis>
 327 may be one of <fvwmopt cmd="Colorset" opt="HGradient"/>, <fvwmopt cmd="Colorset" opt="VGradient"/>,
 328 <fvwmopt cmd="Colorset" opt="DGradient"/>, <fvwmopt cmd="Colorset" opt="BGradient"/>,
 329 <fvwmopt cmd="Colorset" opt="SGradient"/>, <fvwmopt cmd="Colorset" opt="CGradient"/>,
 330 <fvwmopt cmd="Colorset" opt="RGradient"/> or <fvwmopt cmd="Colorset" opt="YGradient"/>.
 331 The gradient types
 332 are as follows:  H is horizontal; V is vertical; D is diagonal
 333 from top left to bottom right; B is a backwards diagonal from
 334 bottom left to top right; S is concentric squares; C is concentric
 335 circles; R is a radar like pattern and Y is a Yin Yang style (but
 336 without the dots).
 337 Please refer to the
 338 <fvwmref sect="colorGradients" opt="color_gradients" name="Color Gradients"/>
 339 section for the syntax of gradients.</para>
 340
 341 <para>
 342 <fvwmopt cmd="Colorset" opt="Tint"/>
 343 takes 2 arguments, a color and a percentage between 0 and 100. It
 344 causes the image defined using
 345 <emphasis remap='I'>?Pixmap</emphasis>
 346 or
 347 <emphasis remap='I'>?Gradient</emphasis>
 348 to be tinted with the specified color using the percentage. If the
 349 image is transparent
 350 <emphasis remap='I'>Tint</emphasis>
 351 tints only the image part. Unfortunately, a colorset background
 352 specified using the
 353 <emphasis remap='I'>Transparent</emphasis>
 354 option can give strange results. See the
 355 <emphasis remap='I'>Transparent</emphasis>
 356 option for details. With no arguments this option removes the
 357 tint.</para>
 358
 359 <para>
 360 <fvwmopt cmd="Colorset" opt="fgTint"/>
 361 takes 2 arguments, a color and a percentage between 0 and 100. It
 362 causes the color defined using
 363 <emphasis remap='I'>fg</emphasis>
 364 to be tinted with the specified color using the percentage. With
 365 no arguments this option removes the tint.</para>
 366
 367 <para>
 368 <fvwmopt cmd="Colorset" opt="bgTint"/>
 369 takes 2 arguments, a color and a percentage between 0 and 100. It
 370 causes the color defined using
 371 <emphasis remap='I'>bg</emphasis>
 372 to be tinted with the specified color using the percentage. If the
 373 <emphasis remap='I'>sh</emphasis>
 374 and
 375 <emphasis remap='I'>hi</emphasis>
 376 colors are not specified, they are recomputed from the tinted bg
 377 color. With no arguments this option removes the tint.</para>
 378
 379 <para>
 380 <fvwmopt cmd="Colorset" opt="Alpha"/>
 381 takes a percentage between 0 and 100 as an argument. It causes
 382 fvwm to merge the image defined using
 383 <emphasis remap='I'>?Pixmap</emphasis>
 384 or
 385 <emphasis remap='I'>?Gradient</emphasis>
 386 with the
 387 <emphasis remap='I'>bg</emphasis>
 388 color using the percentage. If the percentage is 0 the image is
 389 hidden and if it is 100 the image is displayed as usual (no
 390 merge). The default is 100 and it is restored if no argument is
 391 given.</para>
 392
 393 <para>
 394 <fvwmopt cmd="Colorset" opt="fgAlpha"/>
 395 takes a percentage between 0 and 100 as an argument. It causes
 396 fvwm to merge the text and the colorset background using the
 397 percentage. If the percentage is 0 the text is hidden and if it is
 398 100 the text is displayed as usual (no merge). This option has an
 399 effect only with fonts loaded by Xft, see the
 400 <fvwmref sect="fonts" opt="font_names_and_font_loading" name="Font Names and Font Loading"/>
 401 section. The default is 100 and it is restored if no argument is
 402 given.</para>
 403
 404 <para>
 405 <fvwmopt cmd="Colorset" opt="Dither"/>
 406 causes fvwm to dither the image defined using
 407 <emphasis remap='I'>?Pixmap</emphasis>
 408 or
 409 <emphasis remap='I'>?Gradient.</emphasis>
 410 This is useful only with displays with depth less than or equal to
 411 16 (i.e., on displays which can only display less than 65537
 412 colors at once). The dithering effect lets you simulate having
 413 more colors available that you actually have.
 414 <fvwmopt cmd="Colorset" opt="NoDither"/>
 415 causes fvwm to do not dither the images.
 416 <emphasis remap='I'>Dither</emphasis>
 417 is the default if the depth is less than or equal to 8 (a screen
 418 with 256 colors or less). In depth 15 (32768 colors) and 16 (65536
 419 colors), the default is
 420 <emphasis remap='I'>NoDither</emphasis>,
 421 however this effect can be useful with images which contain a lot
 422 of close colors. For example a fine gradient looks more
 423 smooth.</para>
 424
 425 <para>
 426 <fvwmopt cmd="Colorset" opt="IconTint"/>
 427 takes 2 arguments, a color and a percentage between 0 and 100. It
 428 causes fvwm or a module to tint the "icons" which are rendered
 429 into the colorset background with the specified color using a
 430 percentage. Here "icons" means, fvwm Icons, fvwm menu icons,
 431 MiniIcons which represent applications in various modules, images
 432 loaded by modules (e.g., images specified by the
 433 <fvwmref mod="FvwmButtons" opt="Icon"/>
 434 <fvwmref mod="FvwmButtons"/>
 435 button option) ...etc. With no arguments this option removes the
 436 icon tint.</para>
 437
 438 <para>
 439 <fvwmopt cmd="Colorset" opt="IconAlpha"/>
 440 takes a percentage between 0 and 100 as an argument. It causes
 441 fvwm to merge the "icons" which are rendered into the colorset
 442 background using this percentage. The default is 100 and it is
 443 restored if no argument is given.</para>
 444
 445 <para><emphasis remap='I'>Note</emphasis>:
 446 It is equivalent to use "Tint a_color rate" and "Alpha a" if a =
 447 100 and the bg color is a_color. This equivalence does not hold
 448 for IconAlpha and IconTint as the background can be an image or a
 449 gradient (and not a uniform color background).
 450 However, in some cases you can achieve (almost) the same effect by
 451 using IconTint in the place of IconAlpha. This is preferable as,
 452 in general, IconAlpha generates more redrawing than IconTint.</para>
 453
 454 <para>
 455 <fvwmopt cmd="Colorset" opt="NoShape"/>
 456 removes the shape mask from the colorset while
 457 <fvwmopt cmd="Colorset" opt="Plain"/>
 458 removes the background pixmap or gradient.</para>
 459
 460 <para>Examples</para>
 461
 462 <programlisting>
 463 Colorset 3 fg tan, bg navy
 464 </programlisting>
 465
 466
 467 <para>If necessary this creates colorsets 0, 1, 2 and 3 and then changes
 468 colorset 3 to have a foreground of tan, a background of navy.</para>
 469
 470
 471 <programlisting>
 472 Colorset 3 bg "navy blue"
 473 </programlisting>
 474
 475
 476 <para>changes the background color of colorset 3 to navy blue. The
 477 foreground and pixmap are unchanged.</para>
 478
 479
 480 <programlisting>
 481 Colorset 3 AspectPixmap large_murky_dungeon.xpm
 482 </programlisting>
 483
 484
 485 <para>causes depression.</para>
 486
 487
 488 <programlisting>
 489 Colorset 3 bg Average
 490 </programlisting>
 491
 492
 493 <para>Sets the background color and the relief colors to match the
 494 background pixmap. This is the default setting but it must be used
 495 if a background color was specified and is now not required.</para>
 496
 497 <programlisting>
 498 Colorset 3 YGradient 200 3 blue 1000 navy 1 blue 1000 navy
 499 </programlisting>
 500
 501 <para>Adds a Yin Yang gradient background pixmap to colorset 3.  If the
 502 background is set to average it is recomputed along with the
 503 foreground if that is set to contrast.</para>
 504
 505
 506 <programlisting>
 507 #!/bin/sh
 508 <fvwmref mod="FvwmCommand"/> "Colorset 7 fg navy, bg gray"
 509 while true
 510 do
 511   <fvwmref mod="FvwmCommand"/> "Colorset 7 fg gray"
 512   sleep 1
 513   <fvwmref mod="FvwmCommand"/> "Colorset 7 fg navy"
 514   sleep 1
 515 done
 516 </programlisting>
 517
 518 <para>Makes colorset 7 blink.</para>
 519
 520 <para>The color names used in colorsets are saved as fvwm variables which
 521 can be substituted in any fvwm command. For example:</para>
 522
 523 <programlisting>
 524 <fvwmref cmd="AddToFunc"/> InitFunction
 525 + I <fvwmref cmd="Exec"/> exec xterm -fg $[fg.cs0] -bg $[bg.cs0]
 526 </programlisting>
 527
 528 <para>Where $[fg.cs0] is the foreground color of colorset zero. Please
 529 refer to the
 530 <fvwmref sect="expansion" opt="command_expansion" name="Command Expansion"/>
 531 section for more information.</para>
 532
 533 </section>