doc/commands/AddToFunc.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!-- $Id: AddToFunc.xml,v 1.3 2007/06/16 12:38:45 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='AddToFunc'>
  12 <title>AddToFunc</title>
  13
  14 <cmdsynopsis>
  15         <command>AddToFunc</command
  16         ><arg choice='opt'
  17                 ><replaceable>name</replaceable
  18                 ><arg choice='opt'
  19                         ><group choice='plain'
  20                                 ><arg choice='plain'>I</arg
  21                                 ><arg choice='plain'>M</arg
  22                                 ><arg choice='plain'>C</arg
  23                                 ><arg choice='plain'>H</arg
  24                                 ><arg choice='plain'>D</arg
  25                         ></group
  26                         ><arg choice='plain'
  27                                 ><replaceable>action</replaceable
  28                         ></arg
  29                 ></arg
  30         ></arg>
  31 </cmdsynopsis>
  32
  33 <para>Begins or adds to a function definition.  Here is an example:</para>
  34
  35 <programlisting>
  36 AddToFunc Move-or-Raise I <fvwmref cmd="Raise"/>
  37  + M <fvwmref cmd="Move"/>
  38  + D <fvwmref cmd="Lower"/>
  39 </programlisting>
  40
  41 <para>The function name is "Move-or-Raise", and it could be invoked from a
  42 menu or a mouse binding or key binding:</para>
  43
  44 <programlisting>
  45 <fvwmref cmd="Mouse"/> 1 TS A Move-or-Raise
  46 </programlisting>
  47
  48 <para>The
  49 <replaceable>name</replaceable>
  50 must not contain embedded whitespace.  No guarantees are made
  51 whether function names with embedded whitespace work or not.  This
  52 behavior may also change in the future without further notice.
  53 The letter before the
  54 <replaceable>action</replaceable>
  55 tells what kind of action triggers the command which follows it.
  56 '<fvwmopt cmd="AddToFunc" opt="I"/>'
  57 stands for "Immediate", and is executed as soon as the function is
  58 invoked.
  59 '<fvwmopt cmd="AddToFunc" opt="M"/>'
  60 stands for "Motion", i.e. if the user starts moving the mouse.
  61 '<fvwmopt cmd="AddToFunc" opt="C"/>'
  62 stands for "Click", i.e., if the user presses and releases the
  63 mouse button.
  64 '<fvwmopt cmd="AddToFunc" opt="H"/>'
  65 stands for "Hold", i.e. if the user presses a mouse button and
  66 holds it down for more than
  67 <fvwmref cmd="ClickTime"/>
  68 milliseconds.
  69 '<fvwmopt cmd="AddToFunc" opt="D"/>'
  70 stands for "Double-click". The action
  71 '<emphasis remap='I'>I</emphasis>'
  72 causes an action to be performed on the button-press, if the
  73 function is invoked with prior knowledge of which window to act
  74 on.</para>
  75
  76 <para>There is a number of predefined symbols that are replaced by
  77 certain values if they appear on the command line.  Please refer
  78 to the
  79 <fvwmref sect="expansion" opt="command_expansion" name="Command Expansion"/>
  80 section for details.</para>
  81
  82 <warning>Please read the comments on executing complex functions
  83 in the section
  84 <fvwmref sect="scripting" opt="scripting_and_complex_functions" name="Scripting and Complex Functions"/>.
  85 </warning>
  86
  87 <para>Examples:</para>
  88
  89 <para>If you call</para>
  90
  91 <programlisting>
  92 <fvwmref cmd="Key"/> F10 R A <fvwmref cmd="Function"/> MailFunction xmh "-font fixed"
  93 </programlisting>
  94
  95 <para>and "MailFunction" is</para>
  96
  97 <programlisting>
  98 AddToFunc MailFunction
  99  + I <fvwmref cmd="Next"/> ($0) <fvwmref cmd="Iconify"/> off
 100  + I <fvwmref cmd="Next"/> (AcceptsFocus, $0) <fvwmref cmd="Focus"/>
 101  + I <fvwmref cmd="None"/> ($0) <fvwmref cmd="Exec"/> exec $0 $1
 102 </programlisting>
 103
 104 <para>Then the last line of the function becomes</para>
 105
 106 <programlisting>
 107  + I <fvwmref cmd="None"/> (xmh) <fvwmref cmd="Exec"/> exec xmh -font fixed
 108 </programlisting>
 109
 110 <para>The expansion is performed as the function is executed, so you can
 111 use the same function with all sorts of different arguments.  You
 112 could use</para>
 113
 114 <programlisting>
 115 <fvwmref cmd="Key"/> F11 R A <fvwmref cmd="Function"/> MailFunction zmail "-bg pink"
 116 </programlisting>
 117
 118 <para>in the same
 119 <filename>config</filename>,
 120 if you wanted.  An example of using "$[w.id]" is:</para>
 121
 122 <programlisting>
 123 AddToFunc PrintFunction
 124  + I <fvwmref cmd="Raise"/>
 125  + I <fvwmref cmd="Exec"/> xdpr -id $[w.id]
 126 </programlisting>
 127
 128 <para>Note that "$$" is expanded to '$'.</para>
 129
 130 <para>Another example: bind right mouse button within the window button
 131 number 6 (this is a minimize button for the win95 theme) to
 132 iconify all windows of the same resource:</para>
 133
 134 <programlisting>
 135 AddToFunc FuncIconifySameResource "I" <fvwmref cmd="All"/> ($0) <fvwmref cmd="Iconify"/> on
 136 <fvwmref cmd="Mouse"/> 3 6 A FuncIconifySameResource $[w.resource]
 137 </programlisting>
 138
 139
 140 </section>