# Command Expansion

Whenever an fvwm command line is executed, fvwm performs parameter expansion. A parameter is a '$' followed by a word enclosed in brackets ($[...]) or a single special character. If fvwm encounters an unquoted parameter on the command line it expands it to a string indicated by the parameter name. Unknown parameters are left untouched. Parameter expansion is performed before quoting. To get a literal '$' use "$$".

If a command is prefixed with a '-' parameter expansion isn't performed. This applies to the command immediately following the '-', in which the expansion normally would have taken place. When uesed together with other prefix commands it must be added before the other prefix.

Example:

     - exec xmessage '$[w.name]'

opens an xmessage dialog with "$[w.name]" unexpanded.

The longer variables may contain additional variables inside the name, which are expanded before the outer variable.

In earlier versions of fvwm, some single letter variables were supported. It is deprecated now, since they cause a number of problems. You should use the longer substitutes instead.

Example:

    # Print the current desk number, horizontal page number
    # and the window's class (unexpanded here, no window).
     $[desk.n] $[page.nx] $[w.class]

Note: If the command is called outside a window context, it prints "$[w.class]" instead of the class name. It is usually not enough to have the pointer over a window to have a context window. To force using the window with the focus, the command can be used:

      $[desk.n] $[page.nx] $[w.class]

The parameters known by fvwm are:

$$

  A literal '$'.

$.

  The absolute directory of the currently Read file. Intended for creating relative and relocatable configuration trees. If used outside of any read file, the returned value is '.'.

$0 to $9

  The positional parameters given to a complex function (a function that has been defined with the command). "$0" is replaced with the first parameter, "$1" with the second parameter and so on. If the corresponding parameter is undefined, the "$..." is deleted from the command line.

$*

  All positional parameters given to a complex function. This includes parameters that follow after "$9".

$[n]

  The n:th positional parameter given to a complex function, counting from 0. If the corresponding parameter is undefined, the "$[n]" is deleted from the command line. The parameter is expanded unquoted.

$[n-m]

  The positional parameters given to a complex function, starting with parameter n and ending with parameter m. If all the corresponding parameters are undefined, the "$[...]" is deleted from the command line. If only some of the parameters are defined, all defined parameters are expanded, and the remaining silently ignored. All parameters are expanded unquoted.

$[n-]

  All the positional parameters given to a complex function, starting with parameter n. If all the corresponding parameters are undefined, the "$[...]" is deleted from the command line. All parameters are expanded unquoted.

$[*]

  All the positional parameters given to a complex function. This is equivalent of $[0-].

$[version.num]

  The version number, like "2.6.0".

$[version.info]

  The version info, like " (from cvs)", empty for the official releases.

$[version.line]

  The first line printed by the --version command line option.

$[vp.x] $[vp.y] $[vp.width] $[vp.height]

  Either coordinate or the width or height of the current viewport.

$[wa.x] $[wa.y] $[wa.width] $[wa.height]

  Either coordinate or the width or height of the EWMH working area.

$[dwa.x] $[dwa.y] $[dwa.width] $[dwa.height]

  Either coordinate or the width or height of the dynamic EWMH working area.

$[desk.n]

  The current desk number.

$[desk.name<n>]

  These parameters are replaced with the name of the desktop number <n> that is defined with the command. If no name is defined, then the default name is returned.

$[desk.width] $[desk.height]

  The width or height of the whole desktop, i.e. the width or height multiplied by the number of pages in x or y direction.

$[desk.pagesx] $[desk.pagesy]

  The number of total pages in a desk in x or y direction. This is the same as the values set by .

$[page.nx] $[page.ny]

  The current page numbers, by X and Y axes, starting from 0. page is equivalent to area in the GNOME terminology.

$[w.id]

  The window-id (expressed in hex, e.g. 0x10023c) of the window the command was called for or "$[w.id]" if no window is associated with the command.

$[w.name] $[w.iconname] $[w.class] $[w.resource] $[w.visiblename] $[w.iconfile] $[w.miniiconfile] $[w.iconfile.svgopts] $[w.miniiconfile.svgopts]

  The window's name, icon name, resource class and resource name, visible name, file name of its icon or mini icon defined with the or style (including the full path if the file was found on disk), and (if fvwm is compiled with SVG support) the icon or mini icon svg rendering options (including the leading colon), or unexpanded "$[w.<attribute>]" string if no window is associated with the command.

  Note, the first 5 variables may include any kind of characters, so these variables are quoted. It means that the value is surrounded by single quote characters and any contained single quote is prefixed with a backslash. This guarantees that commands like:

       $[w.resource]  norm/network.png

  work correctly, regardless of any special symbols the value may contain, like spaces and different kinds of quotes.

  In the case of the window's visible name, this is the value returned from the literal title of the window shown in the titlebar. Typically this will be the same as $[w.name] once expanded, although in the case of using then this is more useful a distinction, and allows for referencing the specific window by its visible name for inclusion in things like commands.

$[w.x] $[w.y] $[w.width] $[w.height]

  Either coordinate or the width or height of the current window if it is not iconified. If no window is associated with the command or the window is iconified, the string is left as is.

$[w.desk]

  The number of the desk on which the window is shown. If the window is sticky the current desk number is used.

$[w.layer]

  The layer of the window.

$[w.screen]

  The screen number the window is on. If Xinerama is not present, this returns the number 0.

$[cw.x] $[cw.y] $[cw.width] $[cw.height]

  These work like $[w....] but return the geometry of the client part of the window. In other words: the border and title of the window is not taken into account.

$[i.x], $[it.x], $[ip.x] $[i.y], $[it.y], $[ip.y] $[i.width], $[it.width], $[ip.width] $[i.height], $[it.height], $[ip.height]

  These work like $[w....] but return the geometry of the icon ($[i....]), the icon title ($[it....]) or the icon picture ($[ip....]).

$[pointer.x] $[pointer.y]

  These return the position of the pointer on the screen. If the pointer is not on the screen, these variables are not expanded.

$[pointer.wx] $[pointer.wy]

  These return the position of the pointer in the selected window. If the pointer is not on the screen, the window is iconified or no window is selected, these variables are not expanded.

$[pointer.cx] $[pointer.cy]

  These return the position of the pointer in the client portion of the selected window. If the pointer is not on the screen, the window is shaded or iconified or no window is selected, these variables are not expanded.

$[pointer.screen]

  The screen number the pointer is currently on. Returns 0 if Xinerama is not enabled.

$[screen]

  The screen number fvwm is running on. Useful for setups with multiple screens.

$[fg.cs<n>] $[bg.cs<n>] $[hilight.cs<n>] $[shadow.cs<n>]

  These parameters are replaced with the name of the foreground (fg), background (bg), hilight (hilight) or shadow (shadow) color that is defined in colorset <n> (replace <n> with zero or a positive integer). For example "$[fg.cs3]" is expanded to the name of the foreground color of colorset 3 (in rgb:rrrr/gggg/bbbb form). Please refer to the section for details about colorsets.

$[schedule.last]

  This is replaced by the id of the last command that was scheduled with the command, even if this command was already executed.

$[schedule.next]

  This is replaced by the id the next command used with will get (unless a different id is specified explicitly).

$[cond.rc]

  The return code of the last conditional command. This variable is only valid inside a function and can not be used in a conditional command. Please refer to the section in the command list.

$[func.context]

  The context character of the running command as used in the , or command. This is useful for example with:

       3 FS N  $$[func.context]

$[gt.str]

  return the translation of str by looking in the current locale catalogs. If no translation is found str is returned as is. See the command.

$[infostore.key]

  Return the value of the item stored in the InfoStore at the given key. If no key is present, the unexpanded string is returned.

$[...]

  If the string within the braces is neither of the above, fvwm tries to find an environment variable with this name and replaces its value if one is found (e.g. "$[PAGER]" could be replaced by "more"). Otherwise the string is left as is.

Some examples can be found in the description of the command.