doc/commands/CursorStyle.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!-- $Id: CursorStyle.xml,v 1.6 2007/08/17 22:36:49 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='CursorStyle'>
  12 <title>CursorStyle</title>
  13
  14 <cmdsynopsis>
  15         <command>CursorStyle</command
  16         ><arg choice='plain'
  17                 ><replaceable>context</replaceable
  18         ></arg
  19         ><arg choice='opt'
  20                 ><group choice='plain'
  21                         ><arg choice='plain'
  22                                 ><replaceable>num</replaceable
  23                         ></arg
  24                         ><arg choice='plain'
  25                                 ><replaceable>name</replaceable
  26                         ></arg
  27                         ><arg choice='plain'>None</arg
  28                         ><arg choice='plain'>Tiny</arg
  29                         ><arg choice='plain'
  30                                 ><replaceable>file</replaceable
  31                                 ><arg choice='opt'
  32                                         ><arg choice='plain'
  33                                                 ><replaceable>x</replaceable
  34                                         ></arg
  35                                         ><arg choice='plain'
  36                                                 ><replaceable>y</replaceable
  37                                         ></arg
  38                                 ></arg
  39                         ></arg
  40                 ></group
  41                 ><arg choice='opt'
  42                         ><arg choice='plain'
  43                                 ><replaceable>fg</replaceable
  44                         ></arg>
  45                         <arg choice='plain'
  46                                 ><replaceable>bg</replaceable
  47                         ></arg
  48                 ></arg
  49         ></arg>
  50 </cmdsynopsis>
  51
  52 <para>Defines a new cursor for the specified context.  Note that this
  53 command can not control the shapes an applications uses, for
  54 example, to indicate that it is busy.  The various contexts are:</para>
  55
  56 <variablelist>
  57 <varlistentry>
  58         <term><fvwmopt cmd="CursorStyle" opt="POSITION"/> (top_left_corner)</term>
  59         <listitem><para>used when initially placing windows</para></listitem>
  60 </varlistentry>
  61 <varlistentry>
  62         <term><fvwmopt cmd="CursorStyle" opt="TITLE"/> (top_left_arrow)</term>
  63         <listitem><para>used in a window title-bar</para></listitem>
  64 </varlistentry>
  65 <varlistentry>
  66         <term><fvwmopt cmd="CursorStyle" opt="DEFAULT"/> (top_left_arrow)</term>
  67         <listitem><para>used in windows that do not set their cursor</para></listitem>
  68 </varlistentry>
  69 <varlistentry>
  70         <term><fvwmopt cmd="CursorStyle" opt="SYS"/> (hand2)</term>
  71         <listitem><para>used in one of the title-bar buttons</para></listitem>
  72 </varlistentry>
  73 <varlistentry>
  74         <term><fvwmopt cmd="CursorStyle" opt="MOVE"/> (fleur)</term>
  75         <listitem><para>used when moving or resizing windows</para></listitem>
  76 </varlistentry>
  77 <varlistentry>
  78         <term><fvwmopt cmd="CursorStyle" opt="RESIZE"/> (sizing)</term>
  79         <listitem><para>used when moving or resizing windows</para></listitem>
  80 </varlistentry>
  81 <varlistentry>
  82         <term><fvwmopt cmd="CursorStyle" opt="WAIT"/> (watch)</term>
  83         <listitem><para>used during certain fvwm commands (see <fvwmref cmd="BusyCursor"/> for details)</para></listitem>
  84 </varlistentry>
  85 <varlistentry>
  86         <term><fvwmopt cmd="CursorStyle" opt="MENU"/> (top_left_arrow)</term>
  87         <listitem><para>used in menus</para></listitem>
  88 </varlistentry>
  89 <varlistentry>
  90         <term><fvwmopt cmd="CursorStyle" opt="SELECT"/> (crosshair)</term>
  91         <listitem><para>used when the user is required to select a window</para></listitem>
  92 </varlistentry>
  93 <varlistentry>
  94         <term><fvwmopt cmd="CursorStyle" opt="DESTROY"/> (pirate)</term>
  95         <listitem><para>used for <fvwmref cmd="Destroy"/>, <fvwmref cmd="Close"/>, and <fvwmref cmd="Delete"/> commands</para></listitem>
  96 </varlistentry>
  97 <varlistentry>
  98         <term><fvwmopt cmd="CursorStyle" opt="TOP"/> (top_side)</term>
  99         <listitem><para>used in the top side-bar of a window</para></listitem>
 100 </varlistentry>
 101 <varlistentry>
 102         <term><fvwmopt cmd="CursorStyle" opt="RIGHT"/> (right_side)</term>
 103         <listitem><para>used in the right side-bar of a window</para></listitem>
 104 </varlistentry>
 105 <varlistentry>
 106         <term><fvwmopt cmd="CursorStyle" opt="BOTTOM"/> (bottom_side)</term>
 107         <listitem><para>used in the bottom side-bar of a window</para></listitem>
 108 </varlistentry>
 109 <varlistentry>
 110         <term><fvwmopt cmd="CursorStyle" opt="LEFT"/> (left_side)</term>
 111         <listitem><para>used in the left side-bar of a window</para></listitem>
 112 </varlistentry>
 113 <varlistentry>
 114         <term><fvwmopt cmd="CursorStyle" opt="TOP_LEFT"/> (top_left_corner)</term>
 115         <listitem><para>used in the top left corner of a window</para></listitem>
 116 </varlistentry>
 117 <varlistentry>
 118         <term><fvwmopt cmd="CursorStyle" opt="TOP_RIGHT"/> (top_right_corner)</term>
 119         <listitem><para>used in the top right corner of a window</para></listitem>
 120 </varlistentry>
 121 <varlistentry>
 122         <term><fvwmopt cmd="CursorStyle" opt="BOTTOM_LEFT"/> (bottom_left_corner)</term>
 123         <listitem><para>used in the bottom left corner of a window</para></listitem>
 124 </varlistentry>
 125 <varlistentry>
 126         <term><fvwmopt cmd="CursorStyle" opt="BOTTOM_RIGHT"/> (bottom_right_corner)</term>
 127         <listitem><para>used in the bottom right corner of a window</para></listitem>
 128 </varlistentry>
 129 <varlistentry>
 130         <term><fvwmopt cmd="CursorStyle" opt="TOP_EDGE"/> (top_side)</term>
 131         <listitem><para>used at the top edge of the screen</para></listitem>
 132 </varlistentry>
 133 <varlistentry>
 134         <term><fvwmopt cmd="CursorStyle" opt="RIGHT_EDGE"/> (right_side)</term>
 135         <listitem><para>used at the right edge of the screen</para></listitem>
 136 </varlistentry>
 137 <varlistentry>
 138         <term><fvwmopt cmd="CursorStyle" opt="BOTTOM_EDGE"/> (bottom_side)</term>
 139         <listitem><para>used at the bottom edge of the screen</para></listitem>
 140 </varlistentry>
 141 <varlistentry>
 142         <term><fvwmopt cmd="CursorStyle" opt="LEFT_EDGE"/> (left_side)</term>
 143         <listitem><para>used at the left edge of the screen</para></listitem>
 144 </varlistentry>
 145 <varlistentry>
 146         <term><fvwmopt cmd="CursorStyle" opt="ROOT"/> (left_ptr)</term>
 147         <listitem><para>used as the root cursor</para></listitem>
 148 </varlistentry>
 149 <varlistentry>
 150         <term><fvwmopt cmd="CursorStyle" opt="STROKE"/> (plus)</term>
 151         <listitem><para>used during a <fvwmref cmd="StrokeFunc"/> command.</para></listitem>
 152 </varlistentry>
 153 </variablelist>
 154
 155
 156 <para>
 157 The defaults are shown in parentheses above.  If you ever want to
 158 restore the default cursor for a specific context you can omit the
 159 second argument.
 160 </para>
 161
 162 <para>
 163 The second argument is either the numeric value of the cursor as
 164 defined in the include file <filename>X11/cursorfont.h</filename>
 165 or its name (without the XC_ prefix). Alternatively, the xpm file
 166 name may be specified.  The name can also be
 167 <fvwmopt cmd="CursorStyle" opt="None"/>
 168 (no cursor) or
 169 <fvwmopt cmd="CursorStyle" opt="Tiny"/>
 170 (a single pixel as the cursor).</para>
 171
 172 <programlisting>
 173 # make the kill cursor be XC_gumby (both forms work):
 174 CursorStyle DESTROY 56
 175 CursorStyle DESTROY gumby
 176 </programlisting>
 177
 178 <para>
 179 Alternatively, the cursor can be loaded from an (XPM, PNG or SVG) image
 180 <replaceable>file</replaceable>.  If fvwm is compiled with Xcursor support,
 181 full ARGB is used, and (possibly animated) cursor files made with the
 182 <command>xcursorgen</command> program can be loaded.  Otherwise the cursor
 183 is converted to monochrome.
 184 </para>
 185
 186 <para>
 187 The optional <replaceable>x</replaceable> and <replaceable>y</replaceable>
 188 arguments (following a <replaceable>file</replaceable> argument) specifies
 189 the hot-spot coordinate with 0 0 as the top left corner of the image.
 190 Coordinates within the image boundary are valid and overrides any hot-spot
 191 defined in the (XPM/Xcursor) image file.  An invalid or undefined hot-spot
 192 is placed in the center of the image.</para>
 193
 194 <programlisting>
 195 CursorStyle ROOT cursor_image.png 0 0
 196 </programlisting>
 197
 198 <para>The optional
 199 <replaceable>fg</replaceable> and <replaceable>bg</replaceable>
 200 arguments specify the foreground and background colors for the
 201 cursor, defaulting to black and white (reverse video compared
 202 to the actual bitmap).  These colors are only used with monochrome
 203 cursors.  Otherwise they are silently ignored.</para>
 204
 205 <programlisting>
 206 CursorStyle ROOT nice_arrow.xpm yellow black
 207 </programlisting>
 208
 209 </section>