workspace/doc/kcontrol/mouse/index.docbook

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
   3 "dtd/kdex.dtd" [
   4 <!ENTITY % addindex "IGNORE">
   5 <!ENTITY % English "INCLUDE" > <!-- change language only here -->
   6 ]>
   7
   8 <article lang="&language;">
   9 <articleinfo>
  10
  11 <authorgroup>
  12 <author>&Mike.McBride; &Mike.McBride.mail;</author>
  13 <author>&Brad.Hards; &Brad.Hards.mail;</author>
  14 <!-- TRANS:ROLES_OF_TRANSLATORS -->
  15 </authorgroup>
  16
  17 <date>2004-10-09</date>
  18 <releaseinfo>3.03.00</releaseinfo>
  19
  20 <abstract>
  21 <para>This is the documentation for the &kde; &kcontrol; module that configures mice and other pointing devices.
  22 </para>
  23 </abstract>
  24
  25 <keywordset>
  26 <keyword>KDE</keyword>
  27 <keyword>KControl</keyword>
  28 <keyword>mouse</keyword>
  29 </keywordset>
  30 </articleinfo>
  31
  32 <sect1 id="mouse">
  33 <title>Mouse</title>
  34
  35 <para>This module allows you to configure your pointing device. Your
  36 pointing device may be a mouse, a track ball, a touch-pad, or another piece
  37 of hardware that performs a similar function.</para>
  38
  39 <para>This module is divided into several tabs:
  40 <link linkend="mouse-general">General</link>,
  41 <link linkend="cursor-theme">Cursor Theme</link>,
  42 <link linkend="mouse-advanced">Advanced</link> and
  43 <link linkend="mouse-navigation">Mouse Navigation</link>.
  44 There may also be one or more additional tabs if you have a Logitech mouse
  45 or trackball, providing access to special features.
  46 </para>
  47
  48 <sect2 id="mouse-general">
  49 <title><guilabel>General</guilabel></title>
  50
  51 <variablelist>
  52 <varlistentry>
  53 <term><guilabel>Button Order</guilabel></term>
  54 <listitem><para>
  55 If you are left-handed, you may
  56 prefer to swap the functions of the <mousebutton>left</mousebutton> and
  57 <mousebutton>right</mousebutton> buttons on your pointing device by choosing the
  58 <quote>Left handed</quote> option. If your pointing device has more than two
  59 buttons, only those that function as the <mousebutton>left</mousebutton> and
  60 <mousebutton>right</mousebutton> buttons are affected. For example, if you have
  61 a three-button mouse, the <mousebutton>middle</mousebutton> button is
  62 unaffected.</para>
  63 </listitem>
  64 </varlistentry>
  65
  66 <varlistentry>
  67 <term><guilabel>Reverse scroll direction</guilabel></term>
  68 <listitem><para>
  69 With this checkbox selected, the scroll wheel (if any) will work in the opposite direction (so that if rolling the top of the scroll wheel towards you previously causes a scroll down, then it will now cause a scroll up). This may be useful to handle a unusual setup of the X server.
  70 </para>
  71 </listitem>
  72 </varlistentry>
  73
  74 <varlistentry>
  75 <term><guilabel>Double-click to open files and folders (select icons on first click)</guilabel></term>
  76 <listitem>
  77 <para> If this option is not checked, icons/files will be opened with a
  78 single click of the <mousebutton>left</mousebutton> mouse-button. This
  79 default behavior is consistent with what you would expect when you click
  80 links in most web browsers. If checked however, icons/files will be
  81 opened with a double click, while a single click will only select the
  82 icon or file. This is the behavior you may know from other desktops or
  83 operating systems.</para>
  84 </listitem>
  85 </varlistentry>
  86
  87 <varlistentry>
  88 <term><guilabel>Single-click to open files and folders</guilabel></term>
  89 <listitem>
  90 <para>This is the default setting for &kde;. Clicking once on an icon
  91 will open it.  To select you can drag around the icon(s) or <keycombo
  92 action="simul">&Ctrl;<mousebutton>Right</mousebutton></keycombo> click,
  93 or simply click and hold to drag it. You can also enable automatic selection of icons using the <guilabel>Automatically select icons</guilabel> checkbox, discussed below.</para>
  94 </listitem>
  95 </varlistentry>
  96
  97 <varlistentry>
  98 <term><guilabel>Change pointer shape over icons</guilabel></term>
  99 <listitem>
 100 <para>When this option is checked, the shape of the mouse pointer
 101 changes whenever it is over an icon.</para>
 102
 103 <tip><para>This option should be checked in most situations. It gives
 104 more visual feedback and says, in essence, if you click here, something
 105 will happen.</para></tip>
 106
 107 </listitem>
 108 </varlistentry>
 109
 110 <varlistentry>
 111 <term><guilabel>Automatically select icons</guilabel></term>
 112 <listitem>
 113 <para>
 114 As noted above, if you have <guilabel>Single-click to open files and folders</guilabel> selected, you can select icons by dragging around them, or by using <keycombo
 115 action="simul">&Ctrl;<mousebutton>Right</mousebutton></keycombo> click. If you routinely need to select icons, you may want to enable this checkbox, which will allow icons to be selected automatically by pausing over the icon. The <guilabel>Delay:</guilabel> slider determines how long is required before the automatic selection takes effect.
 116 </para>
 117 </listitem>
 118 </varlistentry>
 119
 120 <varlistentry>
 121 <term><guilabel>Visual feedback on activation</guilabel></term>
 122 <listitem>
 123 <para>When this option is
 124 checked, &kde; gives you visual feedback whenever you click on something and activate it.</para></listitem>
 125 </varlistentry>
 126
 127 </variablelist>
 128 </sect2>
 129
 130 <sect2 id="cursor-theme">
 131 <title><guilabel>Cursor Theme</guilabel></title>
 132
 133 <para>
 134 This tab allows you to select from a number of cursor themes. A preview of the cursor display is shown above the listbox.
 135 </para>
 136
 137 <note><para>The features provided by this tab may not be available on some systems. Your system may need to be updated to support cursor themes.
 138 </para></note>
 139
 140 <para>
 141 If you have additional cursor themes available, you can install and remove them using the buttons below the listbox. Note that you cannot remove the default themes.
 142 </para>
 143
 144 </sect2>
 145
 146 <sect2 id="mouse-advanced">
 147 <title>Advanced</title>
 148
 149 <variablelist>
 150 <varlistentry>
 151 <term id="peripherals-mouse-acceleration">
 152 <guilabel>Pointer acceleration</guilabel></term>
 153 <listitem>
 154 <para>This option allows you to change the relationship
 155 between the distance that the mouse pointer moves on the
 156 screen and the relative movement of the physical device
 157 itself (which may be a mouse, track-ball, or some other
 158 pointing device.)</para>
 159
 160 <para>A high value for the acceleration multiplier will lead to large
 161 movements of the mouse pointer on the screen, even when
 162 you only make a small movement with the physical device.</para>
 163
 164 <tip><para>A multiplier between <guilabel>1x</guilabel> and
 165 <guilabel>3x</guilabel> will works well for many systems.  With a multiplier
 166 over <guilabel>3x</guilabel> the mouse pointer may become difficult to
 167 control.</para></tip>
 168 </listitem>
 169 </varlistentry>
 170
 171 <varlistentry>
 172 <term><guilabel>Pointer threshold</guilabel></term>
 173 <listitem>
 174 <para>The threshold is the smallest distance that the mouse pointer must
 175 move on the screen before acceleration has any effect. If the movement
 176 is within the threshold, the mouse pointer moves as if the acceleration
 177 were set to <guilabel>1x</guilabel>.</para>
 178
 179 <para>Thus, when you make small movements with the physical device (&eg;
 180 mouse), you still have fine control of the mouse pointer on the screen,
 181 whereas larger movements of the physical device will move the mouse
 182 pointer rapidly to different areas on the screen.</para>
 183
 184 <para>You can set the threshold value by dragging the slider button or
 185 by clicking the up/down arrows on the spin-button to the left of the
 186 slider.</para>
 187
 188 <tip><para>In general, the higher you set the <guilabel>Pointer
 189 acceleration</guilabel> value, the higher you will want to set the
 190 <guilabel>Pointer threshold</guilabel> value.  For example, a
 191 <guilabel>Pointer threshold</guilabel> of 4 pixels may
 192 be appropriate for a <guilabel>Pointer Acceleration</guilabel> of
 193 2x, but 10 pixels might be
 194 better for 3x.</para></tip>
 195 </listitem>
 196 </varlistentry>
 197
 198 <varlistentry>
 199 <term><guilabel>Double click interval</guilabel></term>
 200 <listitem>
 201 <para>This is the maximum amount of time between clicks for &kde; to
 202 register a double click.  If you click twice, and the time between those
 203 two clicks is less than this number, &kde; recognizes that as a double
 204 click.  If the time between these two clicks is greater than this
 205 number, &kde; recognizes those as two <emphasis>separate</emphasis>
 206 single clicks.</para>
 207 </listitem>
 208 </varlistentry>
 209
 210 <varlistentry>
 211 <term><guilabel>Drag start time</guilabel> and <guilabel>Drag start
 212 distance</guilabel></term>
 213
 214 <listitem>
 215 <para>If you
 216 <itemizedlist>
 217 <listitem><para>click with the mouse</para></listitem>
 218 <listitem><para>drag within the time specified in <guilabel>Drag start
 219 time</guilabel>, and </para></listitem>
 220 <listitem><para>move a distance equal to or greater than the number (of
 221 pixels) specified in <guilabel>Drag start distance</guilabel></para>
 222 </listitem>
 223 </itemizedlist>
 224
 225 &kde; will drag the selected item.</para>
 226 </listitem>
 227 </varlistentry>
 228
 229 <varlistentry>
 230 <term><guilabel>Mouse wheel scrolls by</guilabel></term>
 231 <listitem>
 232 <para>If you have a wheel mouse, use the slider to determine how many
 233 lines of text one <quote>step</quote> of the mouse wheel will
 234 scroll.</para>
 235 </listitem>
 236 </varlistentry>
 237
 238 </variablelist>
 239
 240 </sect2>
 241
 242 <sect2 id="mouse-navigation">
 243 <title><guilabel>Mouse Navigation</guilabel></title>
 244
 245 <para>
 246 This tab allows you to configure the keyboard number pad keys as a mouse-type device. This may be useful when you are working on a device without another pointing device, or where you have no other use for the number pad.
 247 </para>
 248
 249 <variablelist>
 250
 251 <varlistentry>
 252 <term><guilabel>Move pointer with keyboard (using the num pad)</guilabel></term>
 253 <listitem>
 254 <para>
 255 To enable keyboard mouse mode, you need to select the checkbox labelled <guilabel>Move pointer with keyboard (using the num pad)</guilabel>. When you do this, the other settings will become enabled, and you can customize the keyboard pointer behavior further, if required.
 256 </para>
 257 <para>
 258 The various keys on the number pad move in the direction you would expect. Note that you can move diagonally as well as up, down, left and right.  The <keycap>5</keycap> key emulates a click to a pointer button, typically &LMB;. You change which button is emulated by using the <keycap>/</keycap> key (which makes it &LMB;), <keycap>*</keycap> key (which makes it &MMB;) and <keycap>-</keycap> (which makes it &RMB;). Using the <keycap>+</keycap> emulates a doubleclick to the selected pointer button. You can use the <keycap>0</keycap> key to emulate holding down the selected pointer button (for easy dragging), and then use the <keycap>.</keycap> to emulate releasing the selected pointer button.
 259 </para>
 260 </listitem>
 261 </varlistentry>
 262
 263 <varlistentry>
 264 <term><guilabel>Acceleration delay</guilabel></term>
 265 <listitem>
 266 <para>
 267 This is the time (in milliseconds) between the initial key press and the first repeated motion event for mouse key acceleration.
 268 </para>
 269 </listitem>
 270 </varlistentry>
 271
 272 <varlistentry>
 273 <term><guilabel>Repeat interval</guilabel></term>
 274 <listitem>
 275 <para>
 276 This is the time in milliseconds between repeated motion events for mouse key acceleration.
 277 </para>
 278 </listitem>
 279 </varlistentry>
 280
 281 <varlistentry>
 282 <term><guilabel>Acceleration time</guilabel></term>
 283 <listitem>
 284 <para>
 285 This is the number of key events before the pointer reaches a maximum speed for mouse key acceleration.
 286 </para>
 287 </listitem>
 288 </varlistentry>
 289
 290 <varlistentry>
 291 <term><guilabel>Maximum speed</guilabel></term>
 292 <listitem>
 293 <para>
 294 This is the maximum speed in pixels per key event the pointer can reach for mouse key acceleration.
 295 </para>
 296 </listitem>
 297 </varlistentry>
 298
 299 <varlistentry>
 300 <term><guilabel>Acceleration profile</guilabel></term>
 301 <listitem>
 302 <para>
 303 This is the slope of the acceleration curve for mouse key acceleration.
 304 </para>
 305 </listitem>
 306 </varlistentry>
 307
 308 </variablelist>
 309
 310 </sect2>
 311
 312 <sect2 id="logitech-mouse">
 313 <title><guilabel>Logitech Support</guilabel></title>
 314
 315 <para>
 316 Some Logitech USB mice support special features, such as switching to a higher resolution, or
 317 providing cordless status. If KDE was built with libusb support, then you will get an additional
 318 tab for each supported mouse that is plugged in.
 319 </para>
 320
 321 <para>
 322 The supported devices are:
 323 </para>
 324 <orderedlist>
 325 <listitem><para>Wheel Mouse Optical</para></listitem>
 326 <listitem><para>MouseMan Traveler</para></listitem>
 327 <listitem><para>MouseMan Dual Optical</para></listitem>
 328 <listitem><para>MX310 Optical Mouse</para></listitem>
 329 <listitem><para>MX510 Optical Mouse</para></listitem>
 330 <listitem><para>MX300 Optical Mouse</para></listitem>
 331 <listitem><para>MX500 Optical Mouse</para></listitem>
 332 <listitem><para>iFeel Mouse</para></listitem>
 333 <listitem><para>Mouse Receiver</para></listitem>
 334 <listitem><para>Dual Receiver</para></listitem>
 335 <listitem><para>Cordless Freedom Optical</para></listitem>
 336 <listitem><para>Cordless Elite Duo</para></listitem>
 337 <listitem><para>MX700 Optical Mouse</para></listitem>
 338 <listitem><para>Cordless Optical Trackman</para></listitem>
 339 <listitem><para>Cordless MX Duo Receiver</para></listitem>
 340 <listitem><para>MX100 Laser Mouse</para></listitem>
 341 <listitem><para>Receiver for Cordless Presenter</para></listitem>
 342 </orderedlist>
 343
 344 <para>
 345 Not all devices support all capabilities (typically cordless devices do not
 346 provide resolution switching, and of course only cordless devices support
 347 cordless status reporting), so some parts of the tab will not be enabled for
 348 some mouse types.
 349 </para>
 350
 351 <para>
 352 If the mouse supports resolution switching, the <guilabel>Sensor Resolution</guilabel>
 353 radio button group will be enabled, and you can switch from <guilabel>400 counts per
 354 inch</guilabel> to <guilabel>800 counts per inch</guilabel> and back. If you use
 355 <guilabel>800 counts per inch</guilabel>, the same physical movement of the mouse
 356 will cause a greater (roughly double) amount of motion of the cursor. This tends
 357 to be popular amongst gamers.
 358 </para>
 359
 360 <para>
 361 If the mouse supports cordless reporting, the <guilabel>Battery Level</guilabel>
 362 and <guilabel>RF Channel</guilabel> widgets will be enabled. You can only change
 363 the <guilabel>RF Channel</guilabel> if your mouse has two channel support.
 364 </para>
 365
 366 <sect3 id="logitech-perms">
 367 <title>Fixing permission problems on Logitech mice</title>
 368
 369 <para>
 370 Because of the way USB devices work, the code that accesses the current
 371 status on Logitech mice needs to be able to write to the mouse. This
 372 should be handled by your distribution, but if not, you may need to do some
 373 configuration yourself.
 374 </para>
 375
 376 <para>
 377 On a Linux system, you should use the hotplug system to change the ownership
 378 and permissions on the mouse entry in <filename>/proc/bus/usb</filename>. One
 379 way to do this is to create a short script
 380 (<filename>/etc/hotplug/usb/consoleUserPerms</filename>) that changes the ownership
 381 and permissions, as shown below:
 382 </para>
 383
 384 <informalexample>
 385 <programlisting>
 386 <![CDATA[
 387 #!/bin/bash
 388 #
 389 # /etc/hotplug/usb/consoleUserPerms
 390 #
 391 # Sets up newly plugged in USB device so that the user who owns
 392 # the console according to pam_console can access it from user space
 393 #
 394 # Note that for this script to work, you'll need all of the following:
 395 # a) a line in the file /etc/hotplug/usb.usermap or another usermap file
 396 #    in /etc/hotplug/usb/ that corresponds to the device you are using.
 397 # b) a setup using pam_console creates the respective lock files
 398 #    containing the name of the respective user. You can check for that
 399 #    by executing "echo `cat /var/{run,lock}/console.lock`" and
 400 #    verifying the appropriate user is mentioned somewhere there.
 401 # c) a Linux kernel supporting hotplug and usbdevfs
 402 # d) the hotplug package (http://linux-hotplug.sourceforge.net/)
 403 #
 404 # In the usermap file, the first field "usb module" should be named
 405 # "consoleUserPerms" to invoke this script.
 406 #
 407
 408 if [ "${ACTION}" = "add" ] && [ -f "${DEVICE}" ]
 409 then
 410 # New code, using lock files instead of copying /dev/console permissions
 411 # This also works with non-kdm logins (e.g. on a virtual terminal)
 412 # Idea and code from Nalin Dahyabhai <nalin@redhat.com>
 413     if [ -f /var/run/console.lock ]
 414     then
 415         CONSOLEOWNER=`cat /var/run/console.lock`
 416     elif [ -f /var/lock/console.lock ]
 417     then
 418         CONSOLEOWNER=`cat /var/lock/console.lock`
 419     else
 420         CONSOLEOWNER=
 421     fi
 422     if [ -n "$CONSOLEOWNER" ]
 423     then
 424         chmod 0000 "${DEVICE}"
 425         chown "$CONSOLEOWNER" "${DEVICE}"
 426         chmod 0600 "${DEVICE}"
 427     fi
 428 fi
 429 ]]>
 430 </programlisting>
 431 </informalexample>
 432
 433 <para>
 434 The usermap file that goes with this is
 435 <filename>/etc/hotplug/usb/logitechmouse.usermap</filename>, as
 436 shown below:
 437 </para>
 438
 439 <informalexample>
 440 <programlisting>
 441 <![CDATA[
 442 # script           match_flags idVendor idProduct bcdDevice_lo bcdDevice_hi bDeviceClass bDeviceSubClass bDeviceProtocol bInterfaceClass bInterfaceSubClass bInterfaceProtocol driver_info
 443 # Wheel Mouse Optical
 444 consoleUserPerms     0x0003      0x046d   0xc00e    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 445 # MouseMan Traveler
 446 consoleUserPerms     0x0003      0x046d   0xc00f    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 447 # MouseMan Dual Optical
 448 consoleUserPerms     0x0003      0x046d   0xc012    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 449 # MX310 Optical Mouse
 450 consoleUserPerms     0x0003      0x046d   0xc01b    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 451 # MX510 Optical Mouse
 452 consoleUserPerms     0x0003      0x046d   0xc01d    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 453 # MX300 Optical Mouse
 454 consoleUserPerms     0x0003      0x046d   0xc024    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 455 # MX500 Optical Mouse
 456 consoleUserPerms     0x0003      0x046d   0xc025    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 457 # iFeel Mouse
 458 consoleUserPerms     0x0003      0x046d   0xc031    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 459 # Mouse Receiver
 460 consoleUserPerms     0x0003      0x046d   0xc501    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 461 # Dual Receiver
 462 consoleUserPerms     0x0003      0x046d   0xc502    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 463 # Cordless Freedom Optical
 464 consoleUserPerms     0x0003      0x046d   0xc504    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 465 # Cordless Elite Duo
 466 consoleUserPerms     0x0003      0x046d   0xc505    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 467 # MX700 Optical Mouse
 468 consoleUserPerms     0x0003      0x046d   0xc506    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 469 # Cordless Optical Trackman
 470 consoleUserPerms     0x0003      0x046d   0xc508    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 471 # Cordless MX Duo Receiver
 472 consoleUserPerms     0x0003      0x046d   0xc50b    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 473 # MX100 Laser Mouse
 474 consoleUserPerms     0x0003      0x046d   0xc50e    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 475 # Receiver for Cordless Presenter
 476 consoleUserPerms     0x0003      0x046d   0xc702    0x0000       0xffff      0x00         0x00            0x00            0x00            0x00               0x00               0x00000000
 477 ]]>
 478 </programlisting>
 479 </informalexample>
 480
 481 <para>
 482 That should be all that is needed on Linux - just copy the files into
 483 <filename>/etc/hotplug/usb/</filename>, and when the mouse is
 484 plugged in, the ownership and permissions should be changed
 485 so that the user at the console can access the mouse.
 486 </para>
 487 </sect3>
 488
 489 </sect2>
 490
 491 </sect1>
 492
 493 </article>