doc/fvwm/expansion.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!-- $Id: expansion.xml,v 1.3 2008/10/04 22:35:21 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='command_expansion'>
  12 <title>Command Expansion</title>
  13
  14 <para>Whenever an fvwm command line is executed, fvwm performs parameter
  15 expansion.  A parameter is a '$' followed by a word enclosed in
  16 brackets ($[...]) or a single special character.  If fvwm
  17 encounters an unquoted parameter on the command line it expands it
  18 to a string indicated by the parameter name.  Unknown parameters
  19 are left untouched.  Parameter expansion is performed before
  20 quoting.  To get a literal '$' use "$$".</para>
  21
  22 <para>If a command is prefixed with a '-' parameter expansion isn't
  23 performed.  This applies to the command immediately following the '-',
  24 in which the expansion normally would have taken place. When uesed
  25 together with other prefix commands it must be added before the other
  26 prefix.</para>
  27
  28 <para>Example:</para>
  29
  30 <programlisting>
  31 <fvwmref cmd="Pick"/> -<fvwmref cmd="Exec"/> exec xmessage '$[w.name]'
  32 </programlisting>
  33
  34 <para>opens an xmessage dialog with "$[w.name]" unexpanded.</para>
  35
  36
  37
  38 <para>The longer variables may contain additional variables inside the
  39 name, which are expanded before the outer variable.</para>
  40
  41 <para>In earlier versions of fvwm, some single letter variables were
  42 supported.  It is deprecated now, since they cause a number of
  43 problems.  You should use the longer substitutes instead.</para>
  44
  45 <para>Example:</para>
  46
  47 <programlisting>
  48 # Print the current desk number, horizontal page number
  49 # and the window's class (unexpanded here, no window).
  50 <fvwmref cmd="Echo"/> $[desk.n] $[page.nx] $[w.class]
  51 </programlisting>
  52
  53
  54 <para>Note: If the command is called outside a window context, it
  55 prints "$[w.class]" instead of the class name.  It is usually not
  56 enough to have the pointer over a window to have a context window.
  57 To force using the window with the focus, the
  58 <fvwmref cmd="Current"/>
  59 command can be used:</para>
  60
  61 <programlisting>
  62 <fvwmref cmd="Current"/> <fvwmref cmd="Echo"/> $[desk.n] $[page.nx] $[w.class]
  63 </programlisting>
  64
  65 <para>The parameters known by fvwm are:</para>
  66
  67 <variablelist remap='TP'>
  68   <varlistentry>
  69     <term>$$</term>
  70     <listitem><para>A literal '$'.</para></listitem>
  71   </varlistentry>
  72   <varlistentry>
  73     <term>$.</term>
  74     <listitem>
  75       <para>
  76         The absolute directory of the currently Read file.  Intended for
  77         creating relative and relocatable configuration trees.  If used
  78         outside of any read file, the returned value is '.'.
  79       </para>
  80     </listitem>
  81   </varlistentry>
  82   <varlistentry>
  83     <term>$0 to $9</term>
  84     <listitem>
  85       <para>
  86         The positional parameters given to a complex function (a function
  87         that has been defined with the
  88         <fvwmref cmd="AddToFunc"/>
  89         command).  "$0" is replaced with the first parameter, "$1" with
  90         the second parameter and so on.  If the corresponding parameter is
  91         undefined, the "$..." is deleted from the command line.
  92       </para>
  93     </listitem>
  94   </varlistentry>
  95   <varlistentry>
  96     <term>$*</term>
  97     <listitem>
  98       <para>
  99         All positional parameters given to a complex function.  This
 100         includes parameters that follow after "$9".
 101       </para>
 102     </listitem>
 103   </varlistentry>
 104   <varlistentry>
 105     <term>$[<replaceable>n</replaceable>]</term>
 106     <listitem>
 107       <para>
 108         The <replaceable>n</replaceable>:th
 109         positional parameter given to a complex function, counting from 0.
 110         If the corresponding parameter is undefined, the
 111         "$[<replaceable>n</replaceable>]" is deleted
 112         from the command line. The parameter is expanded unquoted.
 113       </para>
 114     </listitem>
 115   </varlistentry>
 116   <varlistentry>
 117      <term>$[<replaceable>n</replaceable>-<replaceable>m</replaceable>]</term>
 118      <listitem>
 119        <para>
 120          The positional parameters given to a complex function, starting
 121          with parameter <replaceable>n</replaceable> and ending with parameter
 122          <replaceable>m</replaceable>.
 123          If all the corresponding parameters are undefined, the "$[...]" is
 124          deleted from the command line. If only some of the parameters are
 125          defined, all defined parameters are expanded, and the remaining
 126          silently ignored. All parameters are expanded unquoted.
 127        </para>
 128      </listitem>
 129   </varlistentry>
 130   <varlistentry>
 131     <term>$[<replaceable>n</replaceable>-]</term>
 132     <listitem>
 133       <para>
 134         All the positional parameters given to a complex function,
 135         starting with parameter <replaceable>n</replaceable>.
 136         If all the corresponding parameters are undefined, the "$[...]" is
 137         deleted from the command line. All parameters are expanded
 138         unquoted.
 139       </para>
 140     </listitem>
 141   </varlistentry>
 142   <varlistentry>
 143     <term>$[*]</term>
 144     <listitem>
 145       <para>
 146         All the positional parameters given to a complex function. This is
 147         equivalent of $[0-].
 148       </para>
 149     </listitem>
 150   </varlistentry>
 151   <varlistentry>
 152     <term>$[version.num]</term>
 153     <listitem>
 154       <para>The version number, like "2.6.0".</para>
 155     </listitem>
 156   </varlistentry>
 157   <varlistentry>
 158     <term>$[version.info]</term>
 159     <listitem>
 160       <para>
 161         The version info, like " (from cvs)", empty for the official releases.
 162       </para>
 163     </listitem>
 164   </varlistentry>
 165   <varlistentry>
 166     <term>$[version.line]</term>
 167     <listitem>
 168       <para>
 169         The first line printed by the --version command line option.
 170       </para>
 171     </listitem>
 172   </varlistentry>
 173   <varlistentry>
 174     <term>$[vp.x] $[vp.y] $[vp.width] $[vp.height]</term>
 175     <listitem>
 176       <para>
 177         Either coordinate or the width or height of the current viewport.
 178       </para>
 179     </listitem>
 180   </varlistentry>
 181   <varlistentry>
 182     <term>$[desk.n]</term>
 183     <listitem><para>The current desk number.</para></listitem>
 184   </varlistentry>
 185   <varlistentry>
 186     <term>$[desk.name&lt;n&gt;]</term>
 187     <listitem>
 188       <para>
 189         These parameters are replaced with the name of the desktop
 190         number &lt;n&gt; that is defined with the
 191         <fvwmref cmd="DesktopName"/>
 192         command. If no name is defined, then the default name is returned.
 193       </para>
 194     </listitem>
 195   </varlistentry>
 196   <varlistentry>
 197     <term>$[desk.width] $[desk.height]</term>
 198     <listitem>
 199       <para>
 200         The width or height of the whole desktop, i.e. the width or height
 201         multiplied by the number of pages in x or y direction.
 202       </para>
 203     </listitem>
 204   </varlistentry>
 205   <varlistentry>
 206     <term>$[desk.pagesx] $[desk.pagesy]</term>
 207     <listitem>
 208       <para>
 209         The number of total pages in a desk in x or y direction.
 210         This is the same as the values set by
 211         <fvwmref cmd="DesktopSize"/>.
 212       </para>
 213     </listitem>
 214   </varlistentry>
 215   <varlistentry>
 216     <term>$[page.nx] $[page.ny]</term>
 217     <listitem>
 218       <para>
 219         The current page numbers, by X and Y axes, starting from 0.
 220         <emphasis remap='I'>page</emphasis> is equivalent to
 221         <emphasis remap='I'>area</emphasis> in the
 222         <acronym>GNOME</acronym> terminology.
 223       </para>
 224     </listitem>
 225   </varlistentry>
 226   <varlistentry>
 227     <term>$[w.id]</term>
 228     <listitem>
 229       <para>
 230         The window-id (expressed in hex, e.g. 0x10023c) of the window the
 231         command was called for or "$[w.id]" if no window is associated
 232         with the command.
 233       </para>
 234     </listitem>
 235   </varlistentry>
 236   <varlistentry>
 237     <term>
 238       $[w.name] $[w.iconname] $[w.class] $[w.resource]
 239       $[w.visiblename] $[w.iconfile] $[w.miniiconfile]
 240       $[w.iconfile.svgopts] $[w.miniiconfile.svgopts]
 241     </term>
 242     <listitem>
 243       <para>
 244         The window's name, icon name, resource class and resource name,
 245         visible name, file name of its icon or mini icon defined with the
 246         <fvwmref cmd="Style" opt="Icon"/> or
 247         <fvwmref cmd="Style" opt="MiniIcon"/>
 248         style (including the full path if the file was found on disk),
 249         and (if fvwm is compiled with <acronym>SVG</acronym> support)
 250         the icon or mini icon svg rendering options (including the
 251         leading colon), or unexpanded "$[w.&lt;attribute&gt;]" string
 252         if no window is associated with the command.
 253       </para>
 254       <para>
 255         Note, the first 5 variables may include any kind of characters, so
 256         these variables are quoted.  It means that the value is surrounded
 257         by single quote characters and any contained single quote is
 258         prefixed with a backslash.  This guarantees that commands like:
 259
 260         <programlisting><fvwmref cmd="Style"/> $[w.resource] <fvwmref cmd="Style" opt="Icon"/> norm/network.png</programlisting>
 261
 262         work correctly, regardless of any special symbols the value may
 263     contain, like spaces and different kinds of quotes.
 264       </para>
 265       <para>
 266     In the case of the window's visible name, this is the value returned
 267     from the literal title of the window shown in the titlebar.  Typically
 268     this will be the same as $[w.name] once expanded, although
 269     in the case of using <fvwmref cmd="Style" opt="IndexedWindowName"/> then
 270     this is more useful a distinction, and allows for referencing the
 271     specific window by its visible name for inclusion in things like
 272     <fvwmref cmd="Style"/> commands.
 273       </para>
 274     </listitem>
 275   </varlistentry>
 276   <varlistentry>
 277     <term>$[w.x] $[w.y] $[w.width] $[w.height]</term>
 278     <listitem>
 279       <para>
 280         Either coordinate or the width or height of the current window if
 281         it is not iconified.  If no window is associated with the command
 282         or the window is iconified, the string is left as is.
 283       </para>
 284     </listitem>
 285   </varlistentry>
 286   <varlistentry>
 287     <term>$[w.desk]</term>
 288     <listitem>
 289       <para>
 290         The number of the desk on which the window is shown.  If the
 291         window is sticky the current desk number is used.
 292       </para>
 293     </listitem>
 294   </varlistentry>
 295   <varlistentry>
 296     <term>$[w.layer]</term>
 297     <listitem><para>The layer of the window.</para></listitem>
 298   </varlistentry>
 299   <varlistentry>
 300     <term>$[cw.x] $[cw.y] $[cw.width] $[cw.height]</term>
 301     <listitem>
 302       <para>
 303         These work like $[w....] but return the geometry of the client
 304         part of the window.  In other words: the border and title of the
 305         window is not taken into account.
 306       </para>
 307     </listitem>
 308   </varlistentry>
 309   <varlistentry>
 310     <term>
 311       $[i.x], $[it.x], $[ip.x]
 312       $[i.y], $[it.y], $[ip.y]
 313       $[i.width], $[it.width], $[ip.width]
 314       $[i.height], $[it.height], $[ip.height]
 315     </term>
 316     <listitem>
 317       <para>
 318         These work like $[w....] but return the geometry of the icon
 319         ($[i....]), the icon title ($[it....]) or the icon picture
 320         ($[ip....]).
 321       </para>
 322     </listitem>
 323   </varlistentry>
 324   <varlistentry>
 325     <term>$[pointer.x] $[pointer.y]</term>
 326     <listitem>
 327       <para>
 328         These return the position of the pointer on the screen.  If the
 329         pointer is not on the screen, these variables are not expanded.
 330       </para>
 331     </listitem>
 332   </varlistentry>
 333   <varlistentry>
 334     <term>$[pointer.wx] $[pointer.wy]</term>
 335     <listitem>
 336       <para>
 337         These return the position of the pointer in the selected window.  If
 338         the pointer is not on the screen, the window is iconified
 339         or no window is selected, these variables are not expanded.
 340       </para>
 341     </listitem>
 342   </varlistentry>
 343   <varlistentry>
 344     <term>$[pointer.cx] $[pointer.cy]</term>
 345     <listitem>
 346       <para>
 347         These return the position of the pointer in the client portion of
 348         the selected window.  If the pointer is not on the screen, the
 349         window is shaded or iconified or no window is selected, these
 350         variables are not expanded.
 351       </para>
 352     </listitem>
 353   </varlistentry>
 354   <varlistentry>
 355     <term>$[screen]</term>
 356     <listitem>
 357       <para>
 358         The screen number fvwm is running on.  Useful for setups with
 359         multiple screens.
 360       </para>
 361     </listitem>
 362   </varlistentry>
 363   <varlistentry>
 364     <term>
 365       $[fg.cs&lt;n&gt;]
 366       $[bg.cs&lt;n&gt;]
 367       $[hilight.cs&lt;n&gt;]
 368       $[shadow.cs&lt;n&gt;]
 369     </term>
 370     <listitem>
 371       <para>
 372         These parameters are replaced with the name of the foreground
 373         (fg), background (bg), hilight (hilight) or shadow (shadow) color
 374         that is defined in colorset &lt;n&gt; (replace &lt;n&gt; with zero
 375         or a positive integer).  For example "$[fg.cs3]" is expanded to the
 376         name of the foreground color of colorset 3 (in rgb:rrrr/gggg/bbbb
 377         form).  Please refer to the
 378         <fvwmref sect="colorsets" opt="colorsets" name="Colorsets"/>
 379         section for details about colorsets.
 380       </para>
 381     </listitem>
 382   </varlistentry>
 383   <varlistentry>
 384     <term>$[schedule.last]</term>
 385     <listitem>
 386       <para>
 387         This is replaced by the id of the last command that was
 388         scheduled with the <fvwmref cmd="Schedule"/> command, even if
 389         this command was already executed.
 390       </para>
 391     </listitem>
 392   </varlistentry>
 393   <varlistentry>
 394     <term>$[schedule.next]</term>
 395     <listitem>
 396       <para>
 397         This is replaced by the id the next command used with
 398         <fvwmref cmd="Schedule"/> will get (unless a different id is
 399         specified explicitly).
 400       </para>
 401     </listitem>
 402   </varlistentry>
 403   <varlistentry>
 404     <term>$[cond.rc]</term>
 405     <listitem>
 406       <para>
 407         The return code of the last conditional command.  This
 408         variable is only valid inside a function and can not be used
 409         in a conditional command.  Please refer to the section
 410         <fvwmref sect="conditionalCommands" opt="conditional_commands"
 411         name="Conditional Commands"/> in the command list.
 412       </para>
 413     </listitem>
 414   </varlistentry>
 415   <varlistentry>
 416     <term>$[func.context]</term>
 417     <listitem>
 418       <para>
 419         The context character of the running command as used in the
 420         <fvwmref cmd="Mouse"/>,
 421         <fvwmref cmd="Key"/> or
 422         <fvwmref cmd="PointerKey"/>
 423         command.  This is useful for example with:
 424         <programlisting><fvwmref cmd="Mouse"/> 3 FS N <fvwmref cmd="WindowShade"/> $$[func.context]</programlisting>
 425       </para>
 426     </listitem>
 427   </varlistentry>
 428   <varlistentry>
 429     <term>$[gt.<replaceable>str</replaceable>]</term>
 430     <listitem>
 431       <para>
 432         return the translation of
 433         <replaceable>str</replaceable> by looking in the current
 434         locale catalogs. If no translation is found
 435         <replaceable>str</replaceable> is returned as is.  See the
 436         <fvwmref cmd="LocalePath"/> command.
 437       </para>
 438     </listitem>
 439   </varlistentry>
 440   <varlistentry>
 441     <term>$[...]</term>
 442     <listitem>
 443       <para>
 444         If the string within the braces is neither of the above, fvwm
 445         tries to find an environment variable with this name and replaces
 446         its value if one is found (e.g. "$[PAGER]" could be replaced by
 447         "more").  Otherwise the string is left as is.
 448       </para>
 449     </listitem>
 450   </varlistentry>
 451 </variablelist>
 452
 453
 454 <para>Some examples can be found in the description of the
 455 <fvwmref cmd="AddToFunc"/>
 456 command.</para>
 457
 458 </section>