doc/commands/Mouse.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   3   "../docbook-xml/docbookx.dtd"
   4 [
   5 <!ENTITY % myents SYSTEM "../fvwm.ent" >
   6 %myents;
   7 ]>
   8
   9 <!-- $Id: Mouse.xml,v 1.3 2007/06/16 12:38:46 griph Exp $ -->
  10
  11 <section id='Mouse'>
  12 <title>Mouse</title>
  13
  14 <cmdsynopsis>
  15         <command>Mouse</command
  16         ><arg choice='opt'
  17                 >(<replaceable>window</replaceable
  18         >)</arg
  19         ><arg choice='plain'
  20                 ><replaceable>Button</replaceable
  21         ></arg
  22         ><arg choice='plain'
  23                 ><replaceable>Context</replaceable
  24         ></arg
  25         ><arg choice='plain'
  26                 ><replaceable>Modifiers</replaceable
  27         ></arg
  28         ><arg choice='plain'
  29                 ><replaceable>Function</replaceable
  30         ></arg>
  31 </cmdsynopsis>
  32
  33 <para>Defines a mouse binding, or removes the binding if
  34 <replaceable>Function</replaceable>
  35 is '-'.
  36 <replaceable>Button</replaceable>
  37 is the mouse button number.  If
  38 <replaceable>Button</replaceable>
  39 is zero then any button performs the specified function.  Note
  40 that only mouse buttons 1 to 5 are fully supported by X11.  Any
  41 number above this works only partially.  Complex functions can not
  42 be used with these buttons and neither any operation that requires
  43 dragging the pointer with the button held.  This is due to
  44 limitations of X11.  By default, the highest allowed button number
  45 is 9.</para>
  46
  47 <para><replaceable>Context</replaceable>
  48 describes where the binding applies.  Valid contexts are
  49 '<fvwmopt cmd="Mouse" opt="R"/>' for the root window,
  50 '<fvwmopt cmd="Mouse" opt="W"/>' for an application window,
  51 '<fvwmopt cmd="Mouse" opt="D"/>' for a desktop application (as kdesktop or Nautilus desktop),
  52 '<fvwmopt cmd="Mouse" opt="T"/>' for a window title-bar,
  53 '<fvwmopt cmd="Mouse" opt="S"/>' for a window side, top, or bottom bar,
  54 '<fvwmopt cmd="Mouse" opt="["/>',
  55 '<fvwmopt cmd="Mouse" opt="]"/>',
  56 '<fvwmopt cmd="Mouse" opt="-"/>' and
  57 '<fvwmopt cmd="Mouse" opt="_"/>' for the left, right, top or bottom side only,
  58 '<fvwmopt cmd="Mouse" opt="F"/>' for a window frame (the corners),
  59 '&lt;', '^', '&gt;' and
  60 '<fvwmopt cmd="Mouse" opt="v"/>' for the top
  61 left, top right, bottom right or bottom left corner,
  62 '<fvwmopt cmd="Mouse" opt="I"/>' for an icon window, or
  63 '<fvwmopt cmd="Mouse" opt="0"/>' through
  64 '<fvwmopt cmd="Mouse" opt="9"/>' for title-bar buttons, or any combination of these letters.
  65 '<fvwmopt cmd="Mouse" opt="A"/>' is for any context.  For
  66 instance, a context of "FST" applies when the mouse is anywhere in
  67 a window's border except the title-bar buttons.  Only 'S' and 'W'
  68 are valid for an undecorated window.</para>
  69
  70 <para>The special context '<fvwmopt cmd="Mouse" opt="M"/>' for menus can be used to (re)define the menu
  71 controls. It can be used alone or together with 'T', 'S', 'I', '[', ']', '-' and '_'.  See the
  72 <fvwmref sect="menus" opt="menu_bindings" name="Menu Bindings"/>
  73 section for details.</para>
  74
  75 <para>The special context '<fvwmopt cmd="Mouse" opt="P"/>' controls what buttons that can be used to
  76 place a window. When using this context no modifiers are allowed
  77 (<replaceable>Modifiers</replaceable>
  78 must be N), no
  79 <replaceable>window</replaceable>
  80 is allowed, and the
  81 <replaceable>Function</replaceable>
  82 must be one of
  83 <emphasis remap='I'>PlaceWindow</emphasis>,
  84 <emphasis remap='I'>PlaceWindowDrag</emphasis>,
  85 <emphasis remap='I'>PlaceWindowInteractive</emphasis>,
  86 <emphasis remap='I'>CancelPlacement</emphasis>,
  87 <emphasis remap='I'>CancelPlacementDrag</emphasis>,
  88 <emphasis remap='I'>CancelPlacementInteractive</emphasis> or
  89 <emphasis remap='I'>-</emphasis>.</para>
  90
  91 <para>
  92 <fvwmopt cmd="Mouse" opt="PlaceWindow"/>
  93 makes
  94 <replaceable>Button</replaceable>
  95 usable for window placement, both for interactive and drag move.
  96 <fvwmopt cmd="Mouse" opt="CancelPlacement"/>
  97 does the inverse. That is makes
  98 <replaceable>Button</replaceable>
  99 to cancel move for both interactive and drag move. It may however
 100 not override how new windows are resized after being placed. This
 101 is controlled by the
 102 <fvwmref cmd="Emulate"/>
 103 command. Also a window being dragged can always be placed
 104 by releasing the button hold while dragging, regardless of if it is
 105 set to
 106 <emphasis remap='I'>PlaceWindow</emphasis>
 107 or not.</para>
 108
 109 <para>
 110 <fvwmopt cmd="Mouse" opt="PlaceWindowDrag"/> and
 111 <fvwmopt cmd="Mouse" opt="PlaceWindowInteractive"/>/<fvwmopt cmd="Mouse" opt="CancelPlacementDrag"/>
 112 and <fvwmopt cmd="Mouse" opt="CancelPlacementInteractive"/>
 113 work as
 114 <emphasis remap='I'>PlaceWindow</emphasis>/<emphasis remap='I'>CancelPlacement</emphasis>
 115 with the exception that they only affect either windows dragged /
 116 placed interactively.</para>
 117
 118 <para>
 119 <fvwmopt cmd="Mouse" opt="-"/>
 120 is equivalent to
 121 <emphasis remap='I'>CancelPlacement</emphasis>.</para>
 122
 123 <para>The following example makes all buttons but button 3 usable for
 124 interactive placement and makes drag moves started by other buttons
 125 than one cancel if button 1 is pressed before finishing the move:</para>
 126
 127 <programlisting>
 128 Mouse 0 P N PlaceWindow
 129 Mouse 3 P N CancelPlacement
 130 Mouse 1 P N CancelPlacementDrag
 131 </programlisting>
 132
 133
 134 <para>By default, the binding applies to all windows. You can specify
 135 that a binding only applies to specific windows by specifying the
 136 window name in brackets. The window name is a wildcard pattern
 137 specifying the class, resource or name of the window you want the
 138 binding to apply to.</para>
 139
 140 <para>The following example shows how the same key-binding can be used to
 141 perform different functions depending on the window that is focused:</para>
 142
 143 <programlisting>
 144 <fvwmref cmd="Key"/> (rxvt)  V A C <fvwmref cmd="Echo"/> ctrl-V-in-RXVT
 145 <fvwmref cmd="Key"/> (*term) V A C <fvwmref cmd="Echo"/> ctrl-V-in-Term
 146 <fvwmref cmd="Key"/> (*vim)  V A C --
 147 <fvwmref cmd="Key"/>         V A C <fvwmref cmd="Echo"/> ctrl-V-elsewhere
 148 </programlisting>
 149
 150
 151 <para>A '<fvwmopt cmd="Mouse" opt="--"/>' action indicates that the event should be propagated to the
 152 specified window to handle. This is only a valid action for
 153 window-specific bindings.</para>
 154
 155 <para>This example shows how to display the WindowList when Button 3 is
 156 pressed on an rxvt window:</para>
 157
 158 <programlisting>
 159 Mouse (rxvt) 3 A A <fvwmref cmd="WindowList"/>
 160 </programlisting>
 161
 162
 163 <para>Note that Fvwm actually intercepts all events for a window-specific
 164 binding and (if the focused window doesn't match any of the
 165 bindings) sends a synthetic copy of the event to the window. This
 166 should be transparent to most applications, however (for security
 167 reasons) some programs ignore these synthetic events by default -
 168 xterm is one of them. To enable handling of these events, add the
 169 following line to your <filename>~/.Xdefaults</filename> file:</para>
 170
 171
 172 <programlisting>
 173 XTerm*allowSendEvents:  true
 174 </programlisting>
 175
 176
 177 <para><replaceable>Modifiers</replaceable>
 178 is any combination of
 179 '<fvwmopt cmd="Mouse" opt="N"/>' for no modifiers,
 180 '<fvwmopt cmd="Mouse" opt="C"/>' for control,
 181 '<fvwmopt cmd="Mouse" opt="S"/>' for shift,
 182 '<fvwmopt cmd="Mouse" opt="M"/>' for Meta,
 183 '<fvwmopt cmd="Mouse" opt="L"/>' for Caps-Lock or
 184 '<fvwmopt cmd="Mouse" opt="A"/>' for any
 185 modifier. For example, a modifier of "SM" applies when both the
 186 <keysym>Meta</keysym>
 187 and
 188 <keysym>Shift</keysym>
 189 keys are down.  X11 modifiers mod1 through mod5 are represented as
 190 the digits '1' through '5'.  The modifier 'L' is ignored by
 191 default.  To turn it on, use the
 192 <fvwmref cmd="IgnoreModifiers"/>
 193 command.</para>
 194
 195 <para><replaceable>Function</replaceable>
 196 is one of fvwm's commands.</para>
 197
 198 <para>The title-bar buttons are numbered with odd numbered buttons on
 199 the left side of the title-bar and even numbers on the
 200 right. Smaller-numbered buttons are displayed toward the outside
 201 of the window while larger-numbered buttons appear toward the
 202 middle of the window (0 is short for 10).  In summary, the buttons
 203 are numbered:</para>
 204
 205 <programlisting>
 206 1 3 5 7 9    0 8 6 4 2
 207 </programlisting>
 208
 209 <para>The highest odd numbered button which has an action bound to it
 210 determines the number of buttons drawn on the left side of the
 211 title bar.  The highest even number determines the number of right
 212 side buttons which are drawn.  Actions can be bound to either
 213 mouse buttons or keyboard keys.</para>
 214
 215 </section>