doc/commands/Test.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!-- $Id: Test.xml,v 1.3 2007/06/16 12:38:46 griph 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='Test'>
  12 <title>Test</title>
  13
  14 <cmdsynopsis>
  15         <command>Test</command
  16         ><arg choice='opt'
  17                 >(<replaceable>test-conditions</replaceable
  18         >)</arg
  19         ><arg choice='plain'
  20                 ><replaceable>command</replaceable
  21         ></arg>
  22 </cmdsynopsis>
  23
  24 <para>Performs <replaceable>command</replaceable> if all
  25 <replaceable>test-conditions</replaceable> are satisfied.  The
  26 <replaceable>test-conditions</replaceable>
  27 are keywords with possible arguments from the list below
  28 and are separated by commas or whitespace.  They include:
  29 <emphasis remap='I'>Version operator x.y.z</emphasis>,
  30 <emphasis remap='I'>EnvIsSet varname</emphasis>,
  31 <emphasis remap='I'>EnvMatch varname pattern</emphasis>,
  32 <emphasis remap='I'>EdgeHasPointer direction</emphasis>,
  33 <emphasis remap='I'>EdgeIsActive direction</emphasis>,
  34 <emphasis remap='I'>Start</emphasis>,
  35 <emphasis remap='I'>Init</emphasis>,
  36 <emphasis remap='I'>Restart</emphasis>,
  37 <emphasis remap='I'>Exit</emphasis>,
  38 <emphasis remap='I'>Quit</emphasis>,
  39 <emphasis remap='I'>ToRestart</emphasis>,
  40 <emphasis remap='I'>True</emphasis>,
  41 <emphasis remap='I'>False</emphasis>,
  42 <emphasis remap='I'>F</emphasis>,
  43 <emphasis remap='I'>R</emphasis>,
  44 <emphasis remap='I'>W</emphasis>,
  45 <emphasis remap='I'>X</emphasis> and
  46 <emphasis remap='I'>I</emphasis>.
  47 A test-condition prefixed with "!" is negated.</para>
  48
  49 <para>The
  50 <fvwmopt cmd="Test" opt="Version"/> <emphasis>operator x.y.z</emphasis>
  51 test-condition is fulfilled if the logical condition of the expression is
  52 true. Valid <emphasis remap='I'>operator</emphasis> values are:
  53 <emphasis remap='I'>&gt;=</emphasis>,
  54 <emphasis remap='I'>&gt;</emphasis>,
  55 <emphasis remap='I'>&lt;=</emphasis>,
  56 <emphasis remap='I'>&lt;</emphasis>,
  57 <emphasis remap='I'>==</emphasis>
  58 and
  59 <emphasis remap='I'>!=</emphasis>.</para>
  60
  61 <para>Example:</para>
  62
  63 <programlisting>
  64 Test (Version &gt;= 2.5.11) <fvwmref cmd="Echo"/> 2.5.11 or later.
  65 </programlisting>
  66
  67 <para>The
  68 <fvwmopt cmd="Test" opt="EnvIsSet"/> <emphasis>varname</emphasis>
  69 test-condition is true if the given environment variable is set.
  70 The
  71 <fvwmopt cmd="Test" opt="EnvMatch"/> <emphasis>varname pattern</emphasis>
  72 test-condition is true if
  73 <emphasis remap='I'>pattern</emphasis>
  74 matches the given environment variable value.
  75 The pattern may contain special "*" and "?" chars.</para>
  76
  77 <para>The
  78 <fvwmopt cmd="Test" opt="EdgeHasPointer"/>
  79 <optional><replaceable>direction</replaceable></optional>
  80 test-condition is true if the edge in the given direction currently
  81 contains the pointer.
  82 The
  83 <fvwmopt cmd="Test" opt="EdgeIsActive"/>
  84 <optional><replaceable>direction</replaceable></optional>
  85 test-condition is true if the edge in the given direction currently is
  86 active. An edge is active, and can contain a pointer if either a
  87 command is bound to it or edge scroll is available in that
  88 direction. The direction may be one of
  89 <emphasis remap='I'> Any</emphasis>,<emphasis remap='I'> North</emphasis>,<emphasis remap='I'> Top</emphasis>,<emphasis remap='I'> Up</emphasis>,<emphasis remap='I'> West</emphasis>,<emphasis remap='I'> Left</emphasis>,<emphasis remap='I'> South</emphasis>,<emphasis remap='I'> Bottom</emphasis>,
  90 <emphasis remap='I'> Down</emphasis>,<emphasis remap='I'> Right</emphasis> and <emphasis remap='I'> East</emphasis>.
  91 If no direction is specified <emphasis>Any</emphasis> is assumed.</para>
  92
  93 <para>The
  94 <fvwmopt cmd="Test" opt="Start"/>
  95 test-condition is the same as either
  96 <fvwmopt cmd="Test" opt="Init"/> or <fvwmopt cmd="Test" opt="Restart"/>.
  97 It is only true on startup or restart prior and during
  98 <emphasis remap='B'>StartFunction</emphasis>
  99 execution.
 100 The
 101 <fvwmopt cmd="Test" opt="Exit"/>
 102 test-condition is the same as either
 103 <fvwmopt cmd="Test" opt="Quit"/> or <fvwmopt cmd="Test" opt="ToRestart"/>.
 104 It is only valid on shutdown during
 105 <emphasis remap='B'>ExitFunction</emphasis>
 106 function execution.</para>
 107
 108 <para>The <fvwmopt cmd="Test" opt="True"/> and <fvwmopt cmd="Test" opt="False"/>
 109 test-conditions are unconditionally true and false.</para>
 110
 111 <para>Additionally, if a test-condition name is not recognized, the Error
 112 return code is set and the command is not executed.</para>
 113
 114 <para>The
 115 <fvwmopt cmd="Test" opt="F"/> <replaceable>file</replaceable>,
 116 <fvwmopt cmd="Test" opt="R"/> <replaceable>file</replaceable>,
 117 <fvwmopt cmd="Test" opt="W"/> <replaceable>file</replaceable>,
 118 <fvwmopt cmd="Test" opt="X"/> <replaceable>file</replaceable> and
 119 <fvwmopt cmd="Test" opt="I"/> <replaceable>file</replaceable>
 120 test-conditions test for existence of the given [F]ile (possibly
 121 with [R]ead/[W]rite permissions), e[X]ecutable (in <envar>$PATH</envar>),
 122 or the [I]mage (in ImagePath).</para>
 123
 124 <para>Example:</para>
 125
 126 <programlisting>
 127 <fvwmref cmd="AddToFunc"/> StartFunction I Test (Init) <fvwmref cmd="Exec"/> exec xterm
 128
 129 <fvwmref cmd="AddToFunc"/> VerifyVersion
 130 + I Test (Version 2.5.*) <fvwmref cmd="Echo"/> 2.5.x detected
 131 + I <fvwmref cmd="TestRc"/> (NoMatch) \
 132         Test (!Version 2.6.*) <fvwmref cmd="Echo"/> Future version
 133 + I <fvwmref cmd="TestRc"/> (NoMatch) \
 134         <fvwmref cmd="Echo"/> 2.6.x is detected
 135
 136 Test (F $[FVWM_USERDIR]/local-config) <fvwmref cmd="Read"/> local-config
 137 Test (X xterm-utf16) <fvwmref cmd="Exec"/> exec xterm-utf16
 138 </programlisting>
 139
 140
 141 </section>