1.\" $OpenBSD: wsmouse.4,v 1.24 2024/10/05 13:27:16 chrisz Exp $ 2.\" $NetBSD: wsmouse.4,v 1.3 1999/12/06 14:52:08 augustss Exp $ 3.\" 4.\" Copyright (c) 2018 Ulf Brosziewski <bru@openbsd.org> 5.\" Copyright (c) 1999 6.\" Matthias Drochner. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd $Mdocdate: October 5 2024 $ 30.Dt WSMOUSE 4 31.Os 32.Sh NAME 33.Nm wsmouse 34.Nd generic mouse support in wscons 35.Sh SYNOPSIS 36.Cd "wsmouse* at ..." 37.Sh DESCRIPTION 38The 39.Nm 40driver is an abstraction layer for mice and other pointing devices within the 41.Xr wscons 4 42framework. 43It is attached to the hardware specific drivers and 44provides a character device interface which returns 45.Fa struct wscons_event 46via 47.Xr read 2 . 48For use with X servers, 49.Dq mouse events 50or 51.Dq touch events 52can be generated. 53.Pp 54The 55.Nm 56driver provides a number of ioctl functions to control various parameters (see 57.Pa /usr/include/dev/wscons/wsconsio.h ) . 58The 59.Xr wsconsctl 8 60utility gives access to these variables. 61.Pp 62Touchpad input is processed in one of two modes: 63In 64.Dq absolute mode , 65the 66.Nm 67driver generates touch events. 68Absolute mode is activated by 69.Xr synaptics 4 . 70In 71.Dq compatibility mode , 72which is the default, 73.Nm 74converts the input internally and generates mouse events. 75.Xr wsconsctl 8 76can query and set several configuration parameters for this mode. 77The composite field names have the form 78.Cm mouse Ns Oo Ar N Oc . Ns Cm tp . Ns Ar field 79where 80.Ar N 81is the index of the 82.Nm 83device. 84If 85.Ar N 86is omitted, commands apply to 87.Pa /dev/wsmouse0 . 88.Bl -tag -width Ds 89.It Cm mouse.reverse_scrolling 90Reverse direction of scrolling. 91.It Cm mouse.scaling 92The value is a scale coefficient that is applied to the relative 93coordinates. 94It determines the base speed of the pointer. 95.It Cm mouse.tp.tapping 96Contacts on the touchpad that are immediately released again can 97be mapped to mouse button clicks. 98This list of three parameters configures these mappings, in the order: 99.Bd -literal -offset indent 100.Sm off 101.Ar one-finger , two-finger , three-finger 102.Sm on 103.Ed 104.Pp 105Setting a parameter to a positive value enables that tap gesture 106and maps it to the given mouse button. 107To disable all three tap gestures at once, provide the single value of 0. 108Conversely, a single non-zero value will enable one-finger, two-finger, and 109three-finger tap gestures with their default mappings of left 110button, right button, and middle button, respectively. 111If, within a short time interval, a second touch follows a tap gesture 112mapped to a left-button click, the button-up event is not issued 113until that touch ends 114.Pq Dq tap-and-drag . 115.It Cm mouse.tp.mtbuttons 116This feature is supported for some clickpads. 117If enabled, two-finger clicks - with the fingers side by side - generate 118left-button events, and three-finger clicks generate middle-button events. 119.It Cm mouse.tp.swapsides 120If this parameter has a non-zero value, the order of software 121button areas is inverted. 122If edge scrolling is enabled, the scroll area is set up at the left 123edge of the touchpad. 124.It Cm mouse.tp.disable 125A non-zero value disables pointer movement, tapping, and scrolling. 126Software buttons (and external physical buttons) will work as usual. 127.It Cm mouse.tp.edges 128This field contains a list of four values that define the relative 129sizes of the edge areas, in the order: 130.Bd -literal -offset indent 131.Sm off 132.Ar top , right , bottom , left 133.Sm on 134.Ed 135.Pp 136The unit is percent of the total height of the touchpad surface, or 137of its total width, respectively. 138In order to mitigate the effects of accidental touches, the driver 139ignores most types of input from an edge area (see below). 140If an edge area contains software buttons, they fill up the space 141provided. 142.El 143.Pp 144The automatic configuration enables two-finger scrolling and sets up 145edge areas at the vertical edges. 146On clickpads - where the device surface serves as a single, large 147button - it provides three software button areas at the bottom edge, 148for left-button, middle-button, and right-button clicks. 149On some laptops with a trackpoint, the software buttons are at the 150top edge. 151Vertical edge scrolling will be enabled on older touchpads that do not 152report contact counts. 153.Pp 154A touch that starts and remains in an edge area does not trigger pointer 155movement. 156At the vertical edges and the top edge, tapping and two-finger scrolling 157require that at least one touch is in the main area of the touchpad (the 158exact behaviour of a single-touch device depends on its firmware in this 159case). 160When multi-touch input is available, a touch is ignored if it rests in 161the bottom area while there are other inputs - movement, scrolling, or 162tapping -, and the driver continues to ignore it as long as and whenever 163other touches are present. 164.Sh FILES 165.Bl -tag -width /usr/include/dev/wscons/wsconsio.h -compact 166.It Pa /dev/wsmouse* 167.It Pa /usr/include/dev/wscons/wsconsio.h 168.El 169.Sh SEE ALSO 170.Xr ams 4 , 171.Xr hilms 4 , 172.Xr intro 4 , 173.Xr lms 4 , 174.Xr mms 4 , 175.Xr pms 4 , 176.Xr ubcmtp 4 , 177.Xr ums 4 , 178.Xr utpms 4 , 179.Xr wscons 4 , 180.Xr wsmux 4 , 181.Xr wsconsctl 8 , 182.Xr wsmoused 8 183