diff options
| -rw-r--r-- | man/joystick.man | 310 |
1 files changed, 180 insertions, 130 deletions
diff --git a/man/joystick.man b/man/joystick.man index 19c2ae3..f045af9 100644 --- a/man/joystick.man +++ b/man/joystick.man @@ -2,8 +2,8 @@ .ds q \N'34' -.TH joystick __drivermansuffix__ __vendorversion__ +.TH JOYSTICK __drivermansuffix__ 2012-10-03 __vendorversion__ .SH NAME -joystick \- Joystick input driver +joystick \- Xorg input driver for using a joystick as a mouse .SH SYNOPSIS -Snipped for xorg.conf.d(5): - +Snippet for xorg.conf.d(5): +.sp .nf @@ -17,7 +17,5 @@ Snipped for xorg.conf.d(5): .fi - - .SH DESCRIPTION .B joystick -is an __xservername__ input driver for controlling the pointer with a +is an Xorg input driver for controlling the pointer with a joystick device. @@ -25,18 +23,20 @@ joystick device. Use this driver, if you want to -- generate +.IP " -" +generate .IR "cursor movement" , perform button or key events to control desktop and applications - -- generate +.IP " -" +generate .I "cursor key events" for playing legacy games, that have no native joystick support - .TP 3 .B Do not use, if you want to -- play games, that have native joystick support - -- use XI2 applications. The evdev(4) driver will suffice for those in most cases. - +.IP " -" +play games that have native joystick support +.IP " -" +use XI2 applications. The +.BR evdev (4) +driver will suffice for those in most cases. .PP -You may mix above scenarios by setting the device +You may mix above scenarios by setting the device .IR floating . @@ -44,6 +44,5 @@ The driver reports relative cursor movement, button and key events, as well as raw axis values through valuators. - .SH SUPPORTED HARDWARE The joystick input module can be used on top of the following kernel devices: - +.sp .nf @@ -53,10 +52,10 @@ The joystick input module can be used on top of the following kernel devices: .fi - -Every joystick supported by the kernel should be supported by the +.sp +Every joystick supported by the kernel should be supported by the .B joystick -input driver. The joystick is assumed to be calibrated and reporting axis values -between +input driver. +The joystick is assumed to be calibrated and reporting axis values between .IR "-32768 " and " 32768" . See the Linux kernel documentation for a complete list of supported devices. - +.PP There is no support for @@ -64,7 +63,7 @@ There is no support for at the moment. - .SH CONFIGURATION DETAILS -Please refer to __xconfigfile__(__filemansuffix__) for general configuration -details. This section only covers configuration details specific to this -driver. +Please refer to +.BR xorg.conf (__filemansuffix__) +for general configuration details. +This section only covers configuration details specific to this driver. .PP @@ -77,8 +76,9 @@ are supported: .BI "Option \*qPath\*q \*q" string \*q -Specifies the device through which the joystick can be accessed. This option is mandatory and there is no default setting. - +Specifies the device through which the joystick can be accessed. +This option is mandatory and there is no default setting. +.IP In Linux, joysticks are usually accessible through .IR /dev/input/jsX " or " /dev/input/eventX . - -In *BSD, joysticks are usually recognized as +.IP +In *BSD, joysticks are usually recognized as .IR /dev/uhidX . @@ -90,6 +90,8 @@ is the time in milliseconds before a key starts repeating. .I rate -is the number of times a key repeats per second. Default: Xorg default +is the number of times a key repeats per second. +Default: Xorg default .TP 7 .BI "Option \*qDebugLevel\*q \*q" integer \*q -Controls the verbosity of the driver for debugging purposes. The higher the DebugLevel, the more output is produced. +Controls the verbosity of the driver for debugging purposes. +The higher the DebugLevel, the more output is produced. Default: 0 @@ -97,3 +99,4 @@ Default: 0 .BI "Option \*qMapButton<number>\*q \*q" string \*q -Sets the mapping of a joystick button to the desired action. Button counting starts with +Sets the mapping of a joystick button to the desired action. +Button counting starts with .IR 1 , @@ -115,4 +118,3 @@ is one of: .B x, y, zx, zy - -and +and .I <factor> @@ -123,10 +125,13 @@ Negative values invert the direction. Default: 1.0 .BI "\*qamplify="<factor> \*q -Amplifies the movement of all axes by the given factor when this button is held down. Different -factors can be combined. +Amplifies the movement of all axes by the given factor when this button +is held down. +Different factors can be combined. .TP 7 .BI "\*qkey="<scancode>[,<scancode>[,<scancode>[,<scancode>]]] -When button is pressed, a series of keydown events with the specified scancodes is -generated. When the button is released, matching keyup events in the opposite -order are generated. You can specify up to 4 scancodes per button. - +When button is pressed, +a series of keydown events with the specified scancodes is generated. +When the button is released, +matching keyup events in the opposite order are generated. +You can specify up to 4 scancodes per button. +.IP See special section about key events below. @@ -138,6 +143,6 @@ See special section about key events below. .B "\*qdisable-all\*q" -Disables either the generation of mouse events, key events or the generation of -all X events by the driver. Press button again to allow the driver to generate -events again. - +Disables either the generation of mouse events, key events, +or the generation of all X events by the driver. +Press button again to allow the driver to generate events again. +.IP You may also set the device @@ -146,3 +151,2 @@ from client space to prevent it from generating core events. .RE -.PP .TP 7 @@ -158,10 +162,14 @@ Where can be one of: - +.IP .B none, relative, accelerated, absolute - .TP 7 .B \*qvaluator\*q -Send extra valuator events for this axis. The valuators will be numbered ascending, starting with 2 (valuator 0 and 1 are reserved for pointer movement). Please consider using the evdev(4) input driver if you are only interested in XI2 features. - -The range of the valuators is always +Send extra valuator events for this axis. +The valuators will be numbered ascending, +starting with 2 (valuator 0 and 1 are reserved for pointer movement). +Please consider using the +.BR evdev (4) +input driver if you are only interested in XI2 features. +.IP +The range of the valuators is always .IR -32767 " to " 32768 . @@ -171,3 +179,5 @@ nor .B axis -needs to be set to generate extra valuator events. The axis will be labelled according to its physical axis number, beginning with +needs to be set to generate extra valuator events. +The axis will be labelled according to its physical axis number, +beginning with .I 1 @@ -183,4 +193,3 @@ is one of: .B x, y, zx, zy, key (see keylow/keyhigh) - -and +and .I <factor> @@ -193,29 +202,42 @@ Negative values will invert the movement. Default: 1.0 .BI "\*qkeyhigh="<scancode>[,<scancode>[,<scancode>[,<scancode>]]] -When the axis is moved out of the deadzone, a series of keydown events according -to the direction of the movement is generated. When the axis is released, matching keyup -events in opposite order will be generated. You can specify up to 4 scancodes for each direction. - +When the axis is moved out of the deadzone, +a series of keydown events according +to the direction of the movement is generated. +When the axis is released, +matching keyup events in opposite order will be generated. +You can specify up to 4 scancodes for each direction. +.IP .B keylow -defines the keys to be generated when the axis is moved in negative direction (left or up), +defines the keys to be generated when the axis is moved in negative direction +(left or up), .B keyhigh -defines the keys to be generated when the axis is moved in positive direction (right or down). - -If +defines the keys to be generated when the axis is moved in positive direction +(right or down). +.IP +If .B mode -is set to +is set to .IR relative : -The driver will emulate autorepeat according to the current value of the axis. A keydown and subsequent keyup event will be generated in short time intervals. To modify that interval and the autorepeat speed, supply the +The driver will emulate autorepeat according to the current value of the axis. +A keydown and subsequent keyup event will be generated in short time intervals. +To modify that interval and the autorepeat speed, supply the .BI "\*qaxis="[<factor>]KEY \*q parameter. - -If +.IP +If .B mode -is set to +is set to .IR accelerated : -Keydown and keyup events will be generated repeatedly. The time between a keydown and a keyup event corresponds to the deflection of the axis. -If the axis is deflected by 30%, the key will be considered to be down 300ms out of 1 second. The exact intervals may vary and can be adjusted with the +Keydown and keyup events will be generated repeatedly. +The time between a keydown and a keyup event corresponds +to the deflection of the axis. +If the axis is deflected by 30%, +the key will be considered to be down 300ms out of 1 second. +The exact intervals may vary and can be adjusted with the .I amplify -parameter. If the axis is deflected by 100%, there will only be one keydown event, so the key is considered down all the time. +parameter. +If the axis is deflected by 100%, there will only be one keydown event, +so the key is considered down all the time. The keys will be autorepeated according to the Xorg keyboard settings. - +.IP See special section about key events below. @@ -229,3 +251,2 @@ Default: 5000 .RE -.PP .TP 7 @@ -234,5 +255,7 @@ Set to .I False -to disable key event generation after startup. You can toggle key event generation with the +to disable key event generation after startup. +You can toggle key event generation with the .I disable-keys -button mapping. Default: enabled +button mapping. +Default: enabled .TP 7 @@ -241,12 +264,10 @@ Set to .I False -to disable mouse event generation after startup. You can toggle mouse event generation with the +to disable mouse event generation after startup. +You can toggle mouse event generation with the .I disable-mouse -button mapping. Default: enabled -.RE -.PP - - +button mapping. +Default: enabled .SH "DEFAULT CONFIGURATION" The default configuration is as follows: - +.sp .nf @@ -269,3 +290,2 @@ The default configuration is as follows: .fi - .SH "ACCELERATED AXIS CONFIGURATION" @@ -274,6 +294,8 @@ mode should be selected, if the axis is a .IR "directional pad" , -which reports only three states: negative, center, positive. It will result in smoothly accelerated movement -when the axis is deflected. An optional factor will affect the acceleration and final speed. - -This example will set up the axis as scrolling vertically inverted, with half the speed: +which reports only three states: negative, center, positive. +It will result in smoothly accelerated movement when the axis is deflected. +An optional factor will affect the acceleration and final speed. +.PP +This example will set up the axis as scrolling vertically inverted, +with half the speed: .nf @@ -281,5 +303,6 @@ This example will set up the axis as scrolling vertically inverted, with half th .fi - -This example maps four buttons to the four pointer directions, so you can use the buttons like a d-pad. The movement will be accelerated -with half the normal speed: +.PP +This example maps four buttons to the four pointer directions, +so you can use the buttons like a d-pad. +The movement will be accelerated with half the normal speed: .nf @@ -290,3 +313,2 @@ with half the normal speed: .fi - .SH "ABSOLUTE AXIS CONFIGURATION" @@ -295,8 +317,14 @@ In axis mode, the -.I position of the cursor will match the -.I position of the configured axis, but relative to the previous position of the cursor. You can specify the range in which the cursor can move. The default range is the screen size. - -In this example the first axis gets a range from left to the right of the screen. The second axis gets a -total range of 200 pixels, 100 to the top and 100 to the bottom: -.nf +.I position of the cursor +will match the +.I position of the configured axis, +but relative to the previous position of the cursor. +You can specify the range in which the cursor can move. +The default range is the screen size. +.PP +In this example the first axis gets a range +from left to the right of the screen. +The second axis gets a total range of 200 pixels, +100 to the top and 100 to the bottom: +.nf .BI " Option \*qMapAxis1\*q \*q" "mode=absolute axis=x" \*q @@ -304,12 +332,16 @@ total range of 200 pixels, 100 to the top and 100 to the bottom: .fi - .SH "GENERATING KEY EVENTS" -Providing a \*qkey=<scancode>[,<scancode>[...]]\*q option will generate X Events with specified scancodes. When the button/axis is released, the keys will be released in opposite order. - +Providing a \*qkey=<scancode>[,<scancode>[...]]\*q option will generate X Events +with specified scancodes. +When the button/axis is released, the keys will be released in opposite order. +.PP If you want a certain KeySym, look up the matching scancode using .BR "xmodmap -pk" . -The scancodes depend on the configured keyboard layout. You can also use unused keycodes and map them to a KeySym of your choice using xmodmap(1). - -You can specify up to 4 scancodes per joystick button/axis, which can be used for modificators to get the KeySym you want. - +The scancodes depend on the configured keyboard layout. +You can also use unused keycodes and map them to a KeySym of your choice using +.BR xmodmap (1). +.PP +You can specify up to 4 scancodes per joystick button/axis, +which can be used for modificators to get the KeySym you want. +.PP Examples: @@ -321,3 +353,3 @@ will generate when the button is pressed. - +.sp .nf @@ -325,7 +357,7 @@ when the button is pressed. .fi -will generate a +will generate a .I "Shift_L+d" -which will result in an uppercase +which will result in an uppercase .IR d . - +.sp .nf @@ -335,3 +367,3 @@ will result in a .IR "space " key. - +.sp .nf @@ -346,9 +378,16 @@ and the second and fourth axis to the arrow keys .IR up " and " down . - -The keys for the first two axes will be generated in an interval according to the value of the axis. The autorepeat speed of the first axis will be half the speed of that of the second axis. -The keys for the third and fourth axis are generated once when the axis moves out of the deadzone and when it moves back into the deadzone. X.Org will autorepeat those keys according to current keyboard settings. - +.PP +The keys for the first two axes will be generated in an interval according to +the value of the axis. +The autorepeat speed of the first axis will be +half the speed of that of the second axis. +The keys for the third and fourth axis are generated once when +the axis moves out of the deadzone and when it moves back into the deadzone. +Xorg will autorepeat those keys according to current keyboard settings. .SH "XI2 Events" -If you only care about raw valuator events instead of using the joystick to control the cursor, consider using the evdev(4) -input driver. If you still use the +If you only care about raw valuator events instead of using the joystick to +control the cursor, consider using the +.BR evdev (4) +input driver. +If you still use the .B joystick @@ -357,3 +396,3 @@ driver for raw events, make sure to unmap all axes/buttons and add the option to the axes: - +.sp .nf @@ -371,6 +410,8 @@ option to the axes: .fi - -Remember, that valuators 0 and 1 are reserved for pointer movement, additional axes will start with valuator 2. - -You might also want to set the device "floating" to stop it from reporting core events: +.sp +Remember, that valuators 0 and 1 are reserved for pointer movement, +additional axes will start with valuator 2. +.PP +You might also want to set the device "floating" +to stop it from reporting core events: .nf @@ -378,3 +419,3 @@ You might also want to set the device "floating" to stop it from reporting core .fi - +.sp .SH "NOTES" @@ -383,11 +424,17 @@ It is not recommended to enable the input driver by default unless explicitly requested by the user. - +.PP Configuration through .I InputClass -sections is recommended in X servers 1.8 and later. See xorg.conf.d(5) for more details. An example xorg.conf.d(5) snipped is provided in +sections is recommended in X servers 1.8 and later. +See +.BR xorg.conf.d (5) +for more details. +An example +.BR xorg.conf.d (5) +snippet is provided in .I ${sourcecode}/config/50-joystick-all.conf - - +.PP Configuration through hal fdi files is recommended in X servers 1.5, -1.6 and 1.7. An example hal policy file is still provided in +1.6, and 1.7. +An example hal policy file is still provided in .I ${sourcecode}/config/50-x11-input-joystick.fdi @@ -395,9 +442,12 @@ to be placed in .IR /etc/hal/fdi/policy . - - .SH "SEE ALSO" -__xservername__(__appmansuffix__), __xconfigfile__(__filemansuffix__), xorg.conf.d(5), Xserver(__appmansuffix__), X(__miscmansuffix__), xmodmap(1) +.BR Xorg (__appmansuffix__), +.BR xorg.conf (__filemansuffix__), +.BR xorg.conf.d (5), +.BR Xserver (__appmansuffix__), +.BR X (__miscmansuffix__), +.BR xmodmap (1) .SH AUTHORS Sascha Hlusiak (2007-2012), -.fi +.br Frederic Lepied (1995-1999) |