doc/commands/ButtonStyle.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: ButtonStyle.xml,v 1.3 2007/06/16 12:38:45 griph Exp $ -->
  10
  11 <section id='ButtonStyle'>
  12 <title>ButtonStyle</title>
  13
  14 <cmdsynopsis>
  15         <command>ButtonStyle</command>
  16         ><arg choice='plain'>button</arg
  17         ><arg choice='opt'
  18                 ><replaceable>state</replaceable
  19         ></arg
  20         ><arg choice='opt'
  21                 ><replaceable>style</replaceable
  22         ></arg
  23         ><arg choice='opt'
  24                 >-- <arg choice='plain' rep='repeat'
  25                         ><optional>!</optional
  26                         ><replaceable>flag</replaceable
  27                 ></arg
  28         ></arg>
  29 </cmdsynopsis>
  30
  31 <para>Sets the button style for a title-bar button.
  32 <replaceable>button</replaceable>
  33 is the title-bar button number between 0 and 9, or one of
  34 "<fvwmopt cmd="ButtonStyle" opt="All"/>",
  35 "<fvwmopt cmd="ButtonStyle" opt="Left"/>",
  36 "<fvwmopt cmd="ButtonStyle" opt="Right"/>", or
  37 "<fvwmopt cmd="ButtonStyle" opt="Reset"/>".  Button numbering is described in the
  38 <fvwmref cmd="Mouse"/>
  39 command section.  If the
  40 <replaceable>style</replaceable> and <replaceable>flags</replaceable>
  41 are enclosed in parentheses, then multiple
  42 <replaceable>state</replaceable>
  43 definitions can be specified per line.</para>
  44
  45 <para><replaceable>state</replaceable>
  46 refers to which button state should be set.  Button states are
  47 defined as follows:
  48 "<fvwmopt cmd="ButtonStyle" opt="ActiveUp"/>" and
  49 "<fvwmopt cmd="ButtonStyle" opt="ActiveDown"/>" refer to the
  50 un-pressed and pressed states for buttons on active windows; while
  51 the "<fvwmopt cmd="ButtonStyle" opt="InactiveUp"/>" and
  52 "<fvwmopt cmd="ButtonStyle" opt="InactiveDown"/>" states denote buttons on
  53 inactive windows.  The shortcut
  54 "<fvwmopt cmd="ButtonStyle" opt="Active"/>" denotes both "ActiveUp" and
  55 "ActiveDown" states.  Shortcut
  56 "<fvwmopt cmd="ButtonStyle" opt="Inactive"/>" denotes both "InactiveUp"
  57 and "InactiveDown" states.
  58 The similar state names like just described, but with the "Toggled"
  59 prefix are used instead for title buttons which have one of the
  60 <emphasis remap='I'>MwmDecorMax</emphasis>, <emphasis remap='I'>MwmDecorShade</emphasis>, <emphasis remap='I'>MwmDecorStick</emphasis> or <emphasis remap='I'>MwmDecorLayer</emphasis>
  61 hints, if the window is maximized, shaded, sticky or placed on specific
  62 layer, respectively.</para>
  63
  64 <programlisting>
  65 <fvwmref cmd="AddToDecor"/> Default
  66  + ButtonStyle 6                   \
  67    Vector 4 50x25@1 85x75@0 15x75@0 50x25@1
  68  + ButtonStyle 6 ToggledActiveUp   \
  69    Vector 4 50x75@0 85x25@1 15x25@0 50x75@0
  70  + ButtonStyle 6 ToggledActiveDown \
  71    Vector 4 50x75@0 85x25@1 15x25@0 50x75@0
  72  + ButtonStyle 6 ToggledInactive   \
  73    Vector 4 50x75@0 85x25@1 15x25@0 50x75@0
  74  + ButtonStyle 6 - MwmDecorShade
  75 <fvwmref cmd="Mouse"/> 0 6 N <fvwmref cmd="WindowShade"/>
  76 </programlisting>
  77
  78 <para>Additionally, the following shortcuts may be used:
  79 "<fvwmopt cmd="ButtonStyle" opt="AllNormal"/>",
  80 "<fvwmopt cmd="ButtonStyle" opt="AllToggled"/>",
  81 "<fvwmopt cmd="ButtonStyle" opt="AllActive"/>",
  82 "<fvwmopt cmd="ButtonStyle" opt="AllInactive"/>",
  83 "<fvwmopt cmd="ButtonStyle" opt="AllUp"/>",
  84 "<fvwmopt cmd="ButtonStyle" opt="AllDown"/>".
  85 They are actually different masks for 4 individual states from
  86 8 total.  These are supported too:
  87 "<fvwmopt cmd="ButtonStyle" opt="AllActiveUp"/>",
  88 "<fvwmopt cmd="ButtonStyle" opt="AllActiveDown"/>",
  89 "<fvwmopt cmd="ButtonStyle" opt="AllInactiveUp"/>",
  90 "<fvwmopt cmd="ButtonStyle" opt="AllInactiveDown"/>".</para>
  91
  92 <para>If
  93 <replaceable>state</replaceable>
  94 is specified,
  95 that particular button state is set.  If
  96 <replaceable>state</replaceable>
  97 is omitted, every state is set.  Specifying a style destroys the
  98 current style (use
  99 <fvwmref cmd="AddButtonStyle"/>
 100 to avoid this).</para>
 101
 102 <para>If
 103 <replaceable>style</replaceable>
 104 is omitted, then state-dependent flags can be set for the primary
 105 button style without destroying the current style.  Examples (each
 106 line should be considered independent):</para>
 107
 108 <programlisting>
 109 ButtonStyle Left -- flat
 110 ButtonStyle All ActiveUp (-- flat) Inactive (-- flat)
 111 </programlisting>
 112
 113 <para>The first line sets every state of the left buttons to flat, while
 114 the second sets only the "ActiveUp" and "Inactive" states of every
 115 button to flat (only flags are changed; the buttons' individual
 116 styles are not changed).</para>
 117
 118 <para>If you want to reset all buttons to their defaults:</para>
 119
 120 <programlisting>
 121 ButtonStyle <fvwmopt cmd="ButtonStyle" opt="Reset"/>
 122 </programlisting>
 123
 124 <para>To reset the "ActiveUp" button state of button 1 to the default:</para>
 125
 126 <programlisting>
 127 ButtonStyle 1 ActiveUp Default
 128 </programlisting>
 129
 130 <para>To reset all button states of button 1 to the default of
 131 button number 2:</para>
 132
 133 <programlisting>
 134 ButtonStyle 1 Default 2
 135 </programlisting>
 136
 137 <para>For any button, multiple
 138 <replaceable>state</replaceable>
 139 definitions can be given on one line by enclosing the
 140 <replaceable>style</replaceable> and <replaceable>flags</replaceable>
 141 in parentheses.  If only one definition per line is given the
 142 parentheses can be omitted.</para>
 143
 144 <para><replaceable>flags</replaceable>
 145 affect the specified
 146 <replaceable>state</replaceable>.
 147 If a
 148 '!'
 149 is prefixed to any
 150 <replaceable>flag</replaceable>,
 151 its behavior is negated.  The available state-dependent flags for
 152 all styles are described here (the
 153 <emphasis remap='B'>ButtonStyle</emphasis>
 154 entry deals with state-independent flags).</para>
 155
 156 <para>
 157 <fvwmopt cmd="ButtonStyle" opt="Raised"/>
 158 causes a raised relief pattern to be drawn.</para>
 159
 160 <para>
 161 <fvwmopt cmd="ButtonStyle" opt="Sunk"/>
 162 causes a sunken relief pattern to be drawn.</para>
 163
 164 <para>
 165 <fvwmopt cmd="ButtonStyle" opt="Flat"/>
 166 inhibits the relief pattern from being drawn.</para>
 167
 168 <para>
 169 <fvwmopt cmd="ButtonStyle" opt="UseTitleStyle"/>
 170 causes the given button state to render the current title style
 171 before rendering the buttons' own styles.  The
 172 <fvwmref cmd="TitleStyle" opt="Raised"/>,
 173 <fvwmref cmd="TitleStyle" opt="Flat"/> and
 174 <fvwmref cmd="TitleStyle" opt="Sunk"/>
 175 <fvwmref cmd="TitleStyle"/>
 176 flags are ignored since they are redundant in this context.</para>
 177
 178 <para>
 179 <fvwmopt cmd="ButtonStyle" opt="UseBorderStyle"/>
 180 causes the button to inherit the decorated
 181 <emphasis remap='B'>BorderStyle</emphasis>
 182 options.</para>
 183
 184 <para>
 185 <emphasis remap='I'>Raised</emphasis>, <emphasis remap='I'>Sunk</emphasis> and <emphasis remap='I'>Flat</emphasis>
 186 are mutually exclusive, and can be specified for the initial
 187 <emphasis remap='B'>ButtonStyle</emphasis>
 188 only.
 189 <emphasis remap='I'>UseTitleStyle</emphasis> and <emphasis remap='I'>UseBorderStyle</emphasis>
 190 are also mutually exclusive (both can be off however).  The
 191 default is
 192 <emphasis remap='I'>Raised</emphasis>
 193 with both
 194 <emphasis remap='I'>UseBorderStyle  and  UseTitleStyle</emphasis>
 195 left unset.</para>
 196
 197 <important>
 198 for the "ActiveDown" and "InactiveDown" states:  When a button is
 199 pressed, the relief is inverted.  Because of this, to obtain the
 200 raised look in "ActiveDown" or "InactiveDown" states you must
 201 specify the opposite of the desired relief (i.e.
 202 <emphasis remap='I'>Sunk</emphasis>
 203 for "ActiveDown" or "InactiveDown").  This behavior is consistent,
 204 but may seem confusing at first.  The same applies to the
 205 "Toggled" states.</important>
 206
 207 <para>Button styles are classified as non-destructive, partially
 208 destructive, or fully destructive.  Non-destructive styles do not
 209 affect the image. Partially destructive styles can obscure some or
 210 all parts of the underlying image (i.e.
 211 <emphasis remap='I'>Pixmap</emphasis>).
 212 Fully destructive styles obscure the entire underlying image (i.e.
 213 <emphasis remap='I'>Solid</emphasis>
 214 or one of the
 215 <emphasis remap='I'>gradient</emphasis>
 216 styles).  Thus, if stacking styles with
 217 <fvwmref cmd="AddButtonStyle"/> (or <fvwmref cmd="AddTitleStyle"/>
 218 for title-bars), use care in sequencing styles to minimize redraw.</para>
 219
 220 <para>The available styles are:</para>
 221
 222 <para><emphasis remap='I'>Simple</emphasis>, <emphasis remap='I'>Default</emphasis>, <emphasis remap='I'>Solid</emphasis>, <emphasis remap='I'>Colorset</emphasis>, <emphasis remap='I'>Vector</emphasis>,
 223 <emphasis remap='I'>?Gradient</emphasis>, <emphasis remap='I'>Pixmap</emphasis>, <emphasis remap='I'>AdjustedPixmap</emphasis>,
 224 <emphasis remap='I'>ShrunkPixmap</emphasis>, <emphasis remap='I'>StretchedPixmap</emphasis>, <emphasis remap='I'>TiledPixmap</emphasis>, <emphasis remap='I'>MiniIcon</emphasis></para>
 225
 226 <para>The description of these styles and their arguments follow:</para>
 227
 228 <para>The
 229 <fvwmopt cmd="ButtonStyle" opt="Simple"/>
 230 style does nothing.  There are no arguments, and this style is an
 231 example of a non-destructive button style.</para>
 232
 233 <para>The
 234 <fvwmopt cmd="ButtonStyle" opt="Default"/>
 235 style conditionally accepts one argument: a number which specifies
 236 the default button number to load.  If the style command given is
 237 <emphasis remap='B'>ButtonStyle</emphasis> or <fvwmref cmd="AddButtonStyle"/>,
 238 the argument is optional (if given, it overrides the current button).
 239 If a command other than
 240 <emphasis remap='B'>ButtonStyle</emphasis> or <fvwmref cmd="AddButtonStyle"/>
 241 is used, the number must be specified.</para>
 242
 243 <para>The
 244 <fvwmopt cmd="ButtonStyle" opt="Solid"/>
 245 style fills the button with a solid color.  The relief border
 246 color is not affected.  The color is specified as a single
 247 argument.  This style is fully destructive.</para>
 248
 249 <para>The
 250 <fvwmopt cmd="ButtonStyle" opt="Colorset"/>
 251 <replaceable>cs</replaceable>
 252 <optional><replaceable>alpha</replaceable></optional>
 253 style fills the button with the Colorset
 254 <replaceable>cs</replaceable>.
 255 The optional
 256 <replaceable>alpha</replaceable>
 257 argument is a percentage between 0 and 100. It causes fvwm to
 258 merge the colorset background onto the button using this
 259 percentage. If the percentage is 0 the colorset background is
 260 hidden and if it is 100 the colorset background is fully
 261 applied. The default is 100. So, the destructiveness depends on the
 262 <replaceable>alpha</replaceable>
 263 argument.</para>
 264
 265 <para>The
 266 <fvwmopt cmd="ButtonStyle" opt="Vector"/>
 267 <replaceable>num</replaceable>
 268 <emphasis remap='I'>X</emphasis><emphasis remap='B'>[</emphasis><emphasis remap='I'>offset</emphasis><emphasis remap='B'>p]x</emphasis><emphasis remap='I'>Y</emphasis><emphasis remap='B'>[</emphasis><emphasis remap='I'>offset</emphasis><emphasis remap='B'>p]@</emphasis><emphasis remap='I'>C</emphasis><emphasis remap='B'> ...</emphasis>
 269 style draws a line pattern.  Since this is a standard button style,
 270 the keyword
 271 <emphasis remap='I'>Vector</emphasis>
 272 is optional,
 273 <replaceable>num</replaceable>
 274 is a number of point specifications of the form
 275 <emphasis remap='I'>X</emphasis><emphasis remap='B'>[</emphasis><emphasis remap='I'>offset</emphasis><emphasis remap='B'>p]x</emphasis><emphasis remap='I'>Y</emphasis><emphasis remap='B'>[</emphasis><emphasis remap='I'>offset</emphasis><emphasis remap='B'>p]@</emphasis><emphasis remap='I'>C</emphasis><emphasis remap='B'> ...</emphasis>
 276 <emphasis remap='I'>X</emphasis> and <emphasis remap='I'>Y</emphasis>
 277 are point coordinates inside the button, given in percents
 278 (from 0 to 100).  An optional absolute
 279 <emphasis remap='I'>offset</emphasis>
 280 in pixels, can be given as "+&lt;offset&gt;p" for a positive or
 281 "-&lt;offset&gt;p" for a negative offset.</para>
 282
 283 <para>
 284 <fvwmopt cmd="ButtonStyle" opt="C"/>
 285 specifies a line color (0 - the shadow color, 1 - the highlight
 286 color, 2 - the background color, 3 - the foreground color, 4 -
 287 only move the point, do not draw).  The first point color is not
 288 used.  You can use up to 10000 points in a line pattern.  This
 289 style is partially destructive.</para>
 290
 291 <para>The specification is a little cumbersome:</para>
 292
 293 <programlisting>
 294 ButtonStyle 2 Vector 4 50x30@1 70x70@0 30x70@0 50x30@1
 295 </programlisting>
 296
 297 <para>then the button 2 decoration uses a 4-point pattern consisting of
 298 a line from (x=50,y=30) to (70,70) in the shadow color (@0), and
 299 then to (30,70) in the shadow color, and finally to (50,30) in the
 300 highlight color (@1).  Is that too confusing?  See the fvwm web
 301 pages for some examples with screenshots.</para>
 302
 303 <para>A more complex example of
 304 <emphasis remap='I'>Vector</emphasis>:</para>
 305
 306 <programlisting>
 307 ButtonStyle 8 Vector 10 45x65@2 45x75@3 \
 308   20x75@3 20x50@3 35x50@3 35x65@1 35x25@1 \
 309   75x25@1 75x65@0 35x65@0
 310 ButtonStyle 0 Vector 10 45x65@2 45x75@0 \
 311   20x75@0 20x50@1 45x50@1 45x65@0 75x65@3 \
 312   75x25@3 35x25@3 35x47@3
 313 </programlisting>
 314
 315 <para>The
 316 <fvwmopt cmd="ButtonStyle" opt="?Gradient"/>
 317 styles denote color gradients.  Fill in the question mark with any
 318 one of the defined gradient types.  Please refer to the
 319 <fvwmref sect="colorGradients" opt="color_gradients" name="Color Gradients"/>
 320 section for a description of the gradient syntax.  The gradient
 321 styles are fully destructive.</para>
 322
 323 <para>The
 324 <fvwmopt cmd="ButtonStyle" opt="Pixmap"/>
 325 style displays a pixmap.  A pixmap should be specified as an
 326 argument.  For example, the following would give button number 2
 327 the same pixmap for all 4 states (2 active and 2 inactive), and
 328 button number 4 all different pixmaps.</para>
 329
 330 <programlisting>
 331 ButtonStyle 2 Pixmap my_pixmap.xpm
 332 ButtonStyle 4 \
 333         ActiveUp (Pixmap activeup.xpm) \
 334         ActiveDown (Pixmap activedown.xpm) \
 335         Inactive (Pixmap inactiveup.xpm)
 336 ButtonStyle 4 \
 337         InactiveDown Pixmap inactivedown.xpm
 338 </programlisting>
 339
 340 <para>The pixmap specification can be given as an absolute or relative
 341 pathname (see
 342 <fvwmref cmd="ImagePath"/>).
 343 If the pixmap cannot be found, the button style reverts to
 344 <emphasis remap='I'>Simple</emphasis>.
 345 Flags specific to the
 346 <emphasis remap='I'>Pixmap</emphasis>
 347 style are
 348 <emphasis remap='I'>Left</emphasis>, <emphasis remap='I'>Right</emphasis>,
 349 <emphasis remap='I'>Top</emphasis>, and <emphasis remap='I'>Bottom</emphasis>.
 350 These can be used to justify the pixmap (default is centered for
 351 both directions).  Pixmap transparency is used for the color
 352 "None."  This style is partially destructive.</para>
 353
 354 <para>The
 355 <fvwmopt cmd="ButtonStyle" opt="AdjustedPixmap"/>
 356 style is similar to the
 357 <emphasis remap='I'>Pixmap</emphasis>
 358 style. But the image is resized to exactly fit the button.</para>
 359
 360 <para>The
 361 <fvwmopt cmd="ButtonStyle" opt="ShrunkPixmap"/>
 362 style is similar to the
 363 <emphasis remap='I'>Pixmap</emphasis>
 364 style. But if the image is bigger than the button the image is
 365 resized to fit into the button.</para>
 366
 367 <para>The
 368 <fvwmopt cmd="ButtonStyle" opt="StretchedPixmap"/>
 369 style is similar to the
 370 <emphasis remap='I'>Pixmap</emphasis>
 371 style. But if the image is smaller than the button the image is
 372 resized to cover the button.</para>
 373
 374 <para>The
 375 <fvwmopt cmd="ButtonStyle" opt="TiledPixmap"/>
 376 style accepts a pixmap to be tiled as the button background. One
 377 pixmap is specified as an argument.  Pixmap transparency is not
 378 used.  This style is fully destructive.</para>
 379
 380 <para>The
 381 <fvwmopt cmd="ButtonStyle" opt="MiniIcon"/>
 382 style draws the window's miniature icon in the button, which is
 383 specified with the
 384 <emphasis remap='I'>MiniIcon</emphasis>
 385 option of the
 386 <emphasis remap='B'>Style</emphasis>
 387 command.  This button style accepts no arguments.  Example:</para>
 388
 389 <programlisting>
 390 <fvwmref cmd="Style"/> *     MiniIcon mini-bx2.xpm
 391 <fvwmref cmd="Style"/> xterm MiniIcon mini-term.xpm
 392 <fvwmref cmd="Style"/> Emacs MiniIcon mini-doc.xpm
 393
 394 ButtonStyle 1 MiniIcon
 395 </programlisting>
 396
 397
 398 <cmdsynopsis>
 399         <command>ButtonStyle</command
 400         ><arg choice='plain'
 401                 ><replaceable>button</replaceable
 402         ></arg
 403         ><arg choice='plain'>-</arg
 404         ><arg choice='plain' rep='repeat'
 405                 ><optional>!</optional
 406                 ><replaceable>flag</replaceable
 407         ></arg>
 408 </cmdsynopsis>
 409
 410 <para>Sets state-independent flags for the specified
 411 <replaceable>button</replaceable>.
 412 State-independent flags affect button behavior.  Each
 413 <replaceable>flag</replaceable>
 414 is separated by a space.  If a '!'
 415 is prefixed to the flag then the behavior is negated.  The special
 416 flag
 417 <fvwmopt cmd="ButtonStyle" opt="Clear"/>
 418 clears any existing flags.</para>
 419
 420 <para>The following flags are usually used to tell fvwm which buttons
 421 should be affected by mwm function hints (see
 422 <fvwmref cmd="Style" opt="MwmFunctions"/>
 423 option of the
 424 <fvwmref cmd="Style"/>
 425 command.  This is not done automatically since you might have
 426 buttons bound to complex functions, for instance.</para>
 427
 428 <para>
 429 <fvwmopt cmd="ButtonStyle" opt="MwmDecorMenu"/>
 430 should be assigned to title-bar buttons which display a menu.  The
 431 default assignment is the leftmost button.  When a window with the
 432 <fvwmref cmd="Style" opt="MwmFunctions"/>
 433 <fvwmref cmd="Style"/>
 434 option requests not to show this button, it is hidden.</para>
 435
 436 <para>
 437 <fvwmopt cmd="ButtonStyle" opt="MwmDecorMin"/>
 438 should be assigned to title-bar buttons which minimize or iconify
 439 the window.  The default assignment is the second button over from
 440 the rightmost button.  When a window with the
 441 <fvwmref cmd="Style" opt="MwmFunctions"/>
 442 <fvwmref cmd="Style"/>
 443 option requests not to show this button, it is hidden.</para>
 444
 445 <para>
 446 <fvwmopt cmd="ButtonStyle" opt="MwmDecorMax"/>
 447 should be assigned to title-bar buttons which maximize the
 448 window. The default assignment is the rightmost button.  When a
 449 window with the
 450 <fvwmref cmd="Style" opt="MwmFunctions"/>
 451 <fvwmref cmd="Style"/>
 452 option requests not to show this button, it is hidden.  When the
 453 window is maximized, the vector pattern on the button looks
 454 pressed in.</para>
 455
 456 <para>
 457 <fvwmopt cmd="ButtonStyle" opt="MwmDecorShade"/>
 458 should be assigned to title-bar buttons which shade the window
 459 (see
 460 <fvwmref cmd="WindowShade"/>
 461 command).  When the window is shaded, the vector pattern on the
 462 button looks pressed in.</para>
 463
 464 <para>
 465 <fvwmopt cmd="ButtonStyle" opt="MwmDecorStick"/>
 466 should be assigned to title-bar buttons which make the window
 467 sticky. When the window is sticky, the vector pattern on the
 468 button looks pressed in.</para>
 469
 470 <para>The flag
 471 <fvwmopt cmd="ButtonStyle" opt="MwmDecorLayer"/>
 472 <replaceable>layer</replaceable>
 473 should be assigned to title-bar buttons which place the window in
 474 the layer numbered
 475 <replaceable>layer</replaceable>.
 476 When the window is on that specific layer, the vector pattern on
 477 the button looks pressed in.</para>
 478 </section>