doc/fvwm/conditionals.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!-- $Id: conditionals.xml,v 1.4 2007/08/06 22:24:03 domivogt Exp $ -->
   3 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   4   "../docbook-xml/docbookx.dtd"
   5 [
   6 <!ENTITY % myents SYSTEM "../fvwm.ent" >
   7 %myents;
   8 ]>
   9
  10
  11 <section id='conditional_commands'>
  12 <title>Conditional Commands</title>
  13
  14
  15 <para>Conditional commands are commands that are only executed if certain
  16 conditions are met.  Most conditional commands work on windows,
  17 like
  18 <fvwmref cmd="Next"/>, <fvwmref cmd="ThisWindow"/> or <fvwmref cmd="All"/>.
  19 There is one conditional command,
  20 <fvwmref cmd="Test"/>,
  21 that works on global conditions unrelated to windows.  The syntax
  22 of the conditions is described below.  For readability, the list
  23 of conditions is located at the end of this section.</para>
  24
  25
  26 <section id="return_codes">
  27 <title>Return Codes</title>
  28
  29 <para>All commands in this section (unless specifically stated for the
  30 command) also have a return code that can be 1 (if the condition
  31 was met) or 0 (if the condition was not met).  Some commands may
  32 return -1 which means that an error occurred and the return code
  33 is useless.  The
  34 <emphasis remap='B'>Break</emphasis>
  35 command returns -2.  Additionally, the return codes of commands
  36 run in a complex functions are passed to the invoking complex
  37 function.  The return code is used by the
  38 <fvwmref cmd="TestRc"/>
  39 command.  Please refer to the commands' description for examples.
  40 The return code can also be accessed through the variable
  41 <emphasis remap='I'>$[cond.rc]</emphasis>.
  42 Non conditional commands do not modify the return code of the last
  43 conditional command.  Important note:  return codes are only
  44 defined inside functions created with the
  45 <fvwmref cmd="AddToFunc"/>
  46 command and are not inherited by sub functions.  To run a command
  47 without altering the return code, the
  48 <fvwmref cmd="KeepRc"/>
  49 command can be used.</para>
  50
  51 </section>
  52
  53 <section id="ring_of_windows">
  54 <title>The Ring of Windows</title>
  55
  56 <para>Fvwm stores windows in a ring internally.  Think of the focused
  57 window as a cursor on the current position in the ring.  The
  58 <fvwmref cmd="Next"/>
  59 command and many other commands search forwards through the ring
  60 for a matching window, and
  61 <fvwmref cmd="Prev"/>
  62 searches backwards.  The windows in the ring are either ordered by
  63 creation time (if the
  64 <emphasis remap='I'>!FPSortWindowlistByFocus</emphasis>,
  65 <emphasis remap='I'>NeverFocus</emphasis> or <emphasis remap='I'>MouseFocus</emphasis>
  66 styles are used) or by the last time they had the focus.</para>
  67
  68 </section>
  69
  70 <section id="list_of_conditional_commands">
  71 <title>List of Conditional Commands</title>
  72
  73 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="All.xml" />
  74 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Any.xml" />
  75 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Break.xml" />
  76 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Current.xml" />
  77 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Direction.xml" />
  78 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="KeepRc.xml" />
  79 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Next.xml" />
  80 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="None.xml" />
  81 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="NoWindow.xml" />
  82 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Pick.xml" />
  83 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PointerWindow.xml" />
  84 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Prev.xml" />
  85 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ScanForWindow.xml" />
  86 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Test.xml" />
  87 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TestRc.xml" />
  88 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ThisWindow.xml" />
  89 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="WindowId.xml" />
  90 </section>
  91
  92 <section id="conditions">
  93 <title>Conditions</title>
  94
  95 <para>The
  96 <emphasis remap='I'>conditions</emphasis>
  97 that may be given as an argument to any conditional command are a
  98 list of keywords separated by commas, enclosed in
  99 parentheses.  Unless stated otherwise, conditional commands accept
 100 all the conditions listed below.  Note that earlier versions of
 101 fvwm required the conditions to be separated by whitespace instead
 102 of commas and enclosed in brackets instead of parentheses
 103 (this is still supported for backward compatibility).</para>
 104
 105 <para>In addition, the
 106 <emphasis remap='I'>conditions</emphasis>
 107 may include one or more window names to match to.  If more than
 108 one window name is given, all of them must match.  The window
 109 name, icon name, class, and resource are considered when
 110 attempting to find a match. Each name may include the wildcards
 111 '*' and '?', and may consist of two or more alternatives,
 112 separated by the character '|', which acts as an OR operator.  (If
 113 OR operators are used, they must not be separated by spaces from
 114 the names.)  Each window name can begin with '!', which prevents
 115 <emphasis remap='I'>command</emphasis>
 116 if any of the window name, icon name, class or resource match.
 117 However, '!' must not be applied to individual names in a group
 118 separated by OR operators; it may only be applied to the beginning
 119 of the group, and then it operates on the whole group.</para>
 120
 121 <para>Examples:</para>
 122
 123 <programlisting>
 124 <fvwmref cmd="Next"/> ("Netscape|konqueror|Mozilla*") <fvwmref cmd="WarpToWindow"/> 99 90
 125 </programlisting>
 126
 127 <para>This goes to the next web browser window, no matter which of the
 128 three named web browsers is being used.</para>
 129
 130 <programlisting>
 131 <fvwmref cmd="Next"/> ("Mozilla*", "Bookmark*") <fvwmref cmd="WarpToWindow"/> 99 90
 132 </programlisting>
 133
 134 <para>This goes to Mozilla's bookmark manager window, ignoring other
 135 Mozilla windows and other browsers' bookmark windows.</para>
 136
 137 <programlisting>
 138 <fvwmref cmd="All"/> ("XTerm|rxvt", !console) <fvwmref cmd="Iconify"/>
 139 </programlisting>
 140
 141 <para>This iconifies all the xterm and rxvt windows on the current page,
 142 except that the one named "console" (with the -name option to xterm)
 143 is excluded.</para>
 144
 145 <programlisting>
 146 <fvwmref cmd="Next"/> (!"<fvwmref mod="FvwmPager"/>|<fvwmref mod="FvwmForm"/>*|<fvwmref mod="FvwmButtons"/>") <fvwmref cmd="Raise"/>
 147 <fvwmref cmd="Next"/> (!<fvwmref mod="FvwmPager"/>, !<fvwmref mod="FvwmForm"/>*, !<fvwmref mod="FvwmButtons"/>) <fvwmref cmd="Raise"/>
 148 </programlisting>
 149
 150 <para>These two commands are equivalent; either one raises the next window
 151 which is not one of the named fvwm modules.</para>
 152
 153 <para>Any condition can be negated by using a an exclamation mark ('!')
 154 directly in front of its name.</para>
 155
 156 <para><emphasis remap='I'>AcceptsFocus</emphasis>,
 157 <emphasis remap='I'>AnyScreen</emphasis>,
 158 <emphasis remap='I'>CirculateHit</emphasis>,
 159 <emphasis remap='I'>CirculateHitIcon</emphasis>,
 160 <emphasis remap='I'>CirculateHitShaded</emphasis>,
 161 <emphasis remap='I'>Closable</emphasis>,
 162 <emphasis remap='I'>CurrentDesk</emphasis>,
 163 <emphasis remap='I'>CurrentGlobalPage</emphasis>,
 164 <emphasis remap='I'>CurrentGlobalPageAnyDesk</emphasis>,
 165 <emphasis remap='I'>CurrentPage</emphasis>,
 166 <emphasis remap='I'>CurrentPageAnyDesk</emphasis>,
 167 <emphasis remap='I'>CurrentScreen</emphasis>,
 168 <emphasis remap='I'>FixedPosition</emphasis>,
 169 <emphasis remap='I'>FixedSize</emphasis>,
 170 <emphasis remap='I'>Focused</emphasis>,
 171 <emphasis remap='I'>HasHandles</emphasis>,
 172 <emphasis remap='I'>HasPointer</emphasis>,
 173 <emphasis remap='I'>Iconic</emphasis>,
 174 <emphasis remap='I'>Iconifiable</emphasis>,
 175 <emphasis remap='I'>Layer [n]</emphasis>,
 176 <emphasis remap='I'>Maximizable</emphasis>,
 177 <emphasis remap='I'>Maximized</emphasis>,
 178 <emphasis remap='I'>Overlapped</emphasis>,
 179 <emphasis remap='I'>PlacedByButton n</emphasis>,
 180 <emphasis remap='I'>PlacedByButton3</emphasis>,
 181 <emphasis remap='I'>PlacedByFvwm</emphasis>,
 182 <emphasis remap='I'>Raised</emphasis>,
 183 <emphasis remap='I'>Shaded</emphasis>,
 184 <emphasis remap='I'>State n</emphasis>,
 185 <emphasis remap='I'>Sticky</emphasis>,
 186 <emphasis remap='I'>StickyAcrossDesks</emphasis>,
 187 <emphasis remap='I'>StickyAcrossPages</emphasis>,
 188 <emphasis remap='I'>StickyIcon</emphasis>,
 189 <emphasis remap='I'>StickyAcrossDesksIcon</emphasis>,
 190 <emphasis remap='I'>StickyAcrossPagesIcon</emphasis>,
 191 <emphasis remap='I'>Transient</emphasis>,
 192 <emphasis remap='I'>Visible</emphasis>.</para>
 193
 194 <para>The
 195 <emphasis remap='I'>AcceptsFocus</emphasis>
 196 condition excludes all windows that do not want the input focus
 197 (the application has set the "Input hints" for the window to
 198 False) and do not use the
 199 <emphasis remap='I'>Lenience</emphasis>
 200 option of the
 201 <emphasis remap='B'>Style</emphasis>
 202 command.  Also, all windows using the
 203 <emphasis remap='I'>NeverFocus</emphasis>
 204 style are ignored.
 205 Note:
 206 <emphasis>!Lenience</emphasis>
 207 is equivalent to the deprecated option
 208 <emphasis>NoLenience</emphasis>.</para>
 209
 210 <para>With the
 211 <emphasis remap='I'>AnyScreen</emphasis>
 212 condition used together with any of the
 213 <emphasis remap='I'>Current...</emphasis>
 214 conditions, windows that do not intersect the Xinerama screen
 215 containing the mouse pointer are considered for a match too.  For
 216 example:</para>
 217
 218 <programlisting>
 219 # Focus next window on current page,
 220 # regardless of Xinerama screen
 221 <fvwmref cmd="Next"/> (CurrentPage, AnyScreen) <fvwmref cmd="Focus"/>
 222 </programlisting>
 223
 224
 225 <para>The
 226 <emphasis remap='I'>CirculateHit</emphasis> and <emphasis remap='I'>CirculateHitIcon</emphasis>
 227 options override the
 228 <emphasis remap='I'>CirculateSkip</emphasis> and <emphasis remap='I'>CirculateSkipIcon</emphasis>
 229 <emphasis remap='B'>Style</emphasis>
 230 attributes for normal or iconic windows.  The
 231 <emphasis remap='I'>CirculateHitShaded</emphasis>
 232 option overrides the
 233 <emphasis remap='I'>CirculateSkipShaded</emphasis>
 234 <emphasis remap='B'>Style.</emphasis>
 235 All three options are turned on
 236 by default for the
 237 <fvwmref cmd="Current"/>
 238 command.  They can be turned off by specifying
 239 <emphasis remap='I'>!CirculateHit</emphasis>
 240 etc. explicitly.
 241 Note:  Do not confuse these conditions with the style options of
 242 the same name.  Specifically,</para>
 243
 244 <programlisting>
 245 <fvwmref cmd="Style"/> foo CirculateSkip
 246 <fvwmref cmd="Next"/> (foo, CirculateHit) ...
 247 </programlisting>
 248
 249 <para>is not the same as</para>
 250
 251 <programlisting>
 252 <fvwmref cmd="Style"/> foo CirculateHit ...
 253 <fvwmref cmd="Next"/> (foo)
 254 </programlisting>
 255
 256 <para>The prior selects windows with the name foo only in the Next
 257 command.  In the second example, these windows are always matched
 258 in all conditional commands.</para>
 259
 260 <para>The
 261 <emphasis remap='I'>Closable</emphasis>
 262 condition matches only windows that are allowed to be closed.</para>
 263
 264 <para>The
 265 <emphasis remap='I'>CurrentDesk</emphasis>
 266 condition matches only windows that are on the current desk.</para>
 267
 268 <para>The
 269 <emphasis remap='I'>CurrentGlobalPage</emphasis>
 270 condition matches only windows that are on the current page of the
 271 current desk, regardless of whether Xinerama support is enabled or
 272 not.  This condition implicitly activates the
 273 <emphasis remap='I'>CurrentDesk</emphasis>
 274 condition.</para>
 275
 276 <para>The
 277 <emphasis remap='I'>CurrentGlobalPageAnyDesk</emphasis>
 278 condition matches only windows that are on the current page of any
 279 desk, regardless of whether Xinerama support is enabled or not.</para>
 280
 281 <para>The
 282 <emphasis remap='I'>CurrentPage</emphasis>
 283 condition matches only windows that are on the current page of the
 284 current desk.  If Xinerama support is enabled, it only matches
 285 windows that are at least partially on the Xinerama screen
 286 containing the mouse pointer.  This condition implicitly
 287 activates the
 288 <emphasis remap='I'>CurrentDesk</emphasis>
 289 condition.</para>
 290
 291 <para>The
 292 <emphasis remap='I'>CurrentPageAnyDesk</emphasis> and <emphasis remap='I'>CurrentScreen</emphasis>
 293 conditions matches only windows that are on the current page of any
 294 desk.  If Xinerama support is enabled, they only match windows
 295 that are at least partially on the Xinerama screen containing the
 296 mouse pointer.</para>
 297
 298 <para>The
 299 <emphasis remap='I'>FixedPosition</emphasis>
 300 condition excludes all windows that do not have a fixed position,
 301 either set through WM hints or the
 302 <emphasis remap='B'>Style</emphasis>
 303 option
 304 <emphasis remap='I'>FixedPosition</emphasis>.
 305 Example:</para>
 306
 307 <programlisting>
 308 <fvwmref cmd="DestroyFunc"/> ToggleFixedGeometry
 309 <fvwmref cmd="AddToFunc"/>   ToggleFixedGeometry
 310 + I <fvwmref cmd="Pick"/> (FixedPosition) \
 311         <fvwmref cmd="WindowStyle"/> VariablePosition, VariableSize
 312 + I <fvwmref cmd="TestRc"/> (NoMatch) <fvwmref cmd="WindowStyle"/> FixedPosition, FixedSize
 313 </programlisting>
 314
 315
 316 <para>The
 317 <emphasis remap='I'>FixedSize</emphasis>
 318 condition excludes all windows that do not have a fixed size,
 319 either set through WM hints or the
 320 <emphasis remap='B'>Style</emphasis>
 321 option
 322 <emphasis remap='I'>FixedSize</emphasis>.</para>
 323
 324 <para>The
 325 <emphasis remap='I'>Focused</emphasis>
 326 matches on the window that currently has the keyboard focus.
 327 This is not useful for the
 328 <emphasis remap='B'>Current</emphasis>
 329 command but can be used with the other conditional commands.</para>
 330
 331 <para>The
 332 <emphasis remap='I'>HasHandles</emphasis>
 333 condition excludes all windows that do not have resize handles.</para>
 334
 335 <para>The
 336 <emphasis remap='I'>HasPointer</emphasis>
 337 condition excludes all windows that do not contain the pointer.</para>
 338
 339 <para>The
 340 <emphasis remap='I'>Iconic</emphasis>
 341 condition matches only iconic windows.</para>
 342
 343 <para>The
 344 <emphasis remap='I'>Iconifiable</emphasis>
 345 condition matches only windows that are allowed to be iconified.</para>
 346
 347 <para>The
 348 <emphasis remap='I'>Layer [n]</emphasis>
 349 condition matches only windows on the specified layer.  The
 350 optional argument of the
 351 <emphasis remap='I'>Layer</emphasis>
 352 condition defaults to the layer of the focused window.  The
 353 negation
 354 <emphasis remap='I'>!Layer</emphasis>
 355 switches off the
 356 <emphasis remap='I'>Layer</emphasis>
 357 condition.</para>
 358
 359 <para>The
 360 <emphasis remap='I'>Maximizable</emphasis>
 361 condition matches only windows that are allowed to be maximized.</para>
 362
 363 <para>The
 364 <emphasis remap='I'>Maximized</emphasis>
 365 condition matches only maximized windows.</para>
 366
 367 <para>The
 368 <emphasis remap='I'>Overlapped</emphasis>
 369 condition matches only windows that are overlapped by other windows
 370 on the same layer (or unmanaged windows if the option
 371 <emphasis remap='I'>RaiseOverUnmanaged</emphasis>
 372 of the
 373 <fvwmref cmd="BugOpts"/>
 374 command is used).  Note that this condition can be slow if you
 375 have many windows or if RaiseOverUnmanaged is used and the
 376 connection to the X server is slow.</para>
 377
 378 <para>The
 379 <emphasis remap='I'>PlacedByButton n</emphasis>
 380 condition is fulfilled if the last interactive motion of the
 381 window (with the
 382 <fvwmref cmd="Move"/>
 383 command or as
 384 <emphasis remap='I'>ManualPlacement</emphasis>)
 385 was ended by pressing mouse button
 386 <emphasis remap='I'>n</emphasis>.
 387 Example:</para>
 388
 389 <programlisting>
 390 <fvwmref cmd="Mouse"/>   1 T     A       <fvwmref cmd="Function"/> MoveWindow
 391
 392 <fvwmref cmd="DestroyFunc"/> MoveWindow
 393 <fvwmref cmd="AddToFunc"/> MoveWindow
 394 + C <fvwmref cmd="Move"/>
 395 + C <fvwmref cmd="ThisWindow"/> (PlacedByButton 5) <fvwmref cmd="WindowShade"/> off
 396 + C <fvwmref cmd="TestRc"/> (Match) <fvwmref cmd="Maximize"/> on 0 100
 397 + C <fvwmref cmd="ThisWindow"/> (PlacedByButton 4) <fvwmref cmd="WindowShade"/> on
 398 </programlisting>
 399
 400
 401 <para>The
 402 <emphasis remap='I'>PlacedByButton3</emphasis>
 403 condition has the same meaning as
 404 <emphasis remap='I'>PlacedByButton</emphasis>
 405 3. It remains only for backward compatibility.</para>
 406
 407 <para>The
 408 <emphasis remap='I'>PlacedByFvwm</emphasis>
 409 condition excludes all windows that have been placed manually or
 410 by using the user or program position hint.</para>
 411
 412 <para>The
 413 <emphasis remap='I'>Raised</emphasis>
 414 conditions matches only windows that are fully visible on the
 415 current viewport and not overlapped by any other window.</para>
 416
 417 <para>The
 418 <emphasis remap='I'>Shaded</emphasis>
 419 conditions matches only shaded windows (see
 420 <fvwmref cmd="WindowShade"/>
 421 command).</para>
 422
 423 <para>The
 424 <emphasis remap='I'>State n</emphasis> or <emphasis remap='I'>!State n</emphasis>
 425 conditions match only windows with the specified integer state set
 426 (or unset).  See the
 427 <fvwmref cmd="State"/>
 428 command for details.  The argument may range from 0 to 31.</para>
 429
 430 <para>The
 431 <emphasis remap='I'>Sticky</emphasis>, <emphasis remap='I'>StickyAcrossDesks</emphasis> and <emphasis remap='I'>StickyAcrossPages</emphasis>
 432 match only windows that are currently sticky, sticky across all
 433 desks or sticky across all pages.  Please refer to the
 434 <fvwmref cmd="Style"/>
 435 options with the same name and the commands
 436 <fvwmref cmd="Stick"/>, <fvwmref cmd="StickAcrossDesks"/> and <fvwmref cmd="StickAcrossPages"/>
 437 for details.</para>
 438
 439 <para>The
 440 <emphasis remap='I'>StickyIcon</emphasis>, <emphasis remap='I'>StickyAcrossDesksIcon</emphasis> and <emphasis remap='I'>StickyAcrossPagesIcon</emphasis>
 441 match only windows that become sticky, sticky across all desks or sticky
 442 across all pages when they are in iconified state.</para>
 443
 444 <para>The
 445 <emphasis remap='I'>Transient</emphasis>
 446 condition matches only windows that have the "transient"
 447 property set by the application.  This it usually the case for
 448 application popup menus and dialogs.  The
 449 <fvwmref mod="FvwmIdent"/>
 450 module can be used to find out whether a specific window is
 451 transient.</para>
 452
 453 <para>The
 454 <emphasis remap='I'>Visible</emphasis>
 455 condition matches only windows that are at least partially
 456 visible on the current viewport and not completely overlapped by
 457 other windows.</para>
 458
 459 </section>
 460
 461
 462
 463 </section>