mirror of
https://gitlab.freedesktop.org/libinput/libinput.git
synced 2026-01-04 12:00:13 +01:00
doc: tablet documentation updates
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> Reviewed-by: Hans de Goede <hdegoede@redhat.com>
This commit is contained in:
Peter Hutterer
parent
abb98d5738
commit
4677c48ab6
3 changed files with 252 additions and 4 deletions
199
doc/svg/tablet.svg
Normal file
199
doc/svg/tablet.svg
Normal file
|
|
@ -0,0 +1,199 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!-- Created with Inkscape (http://www.inkscape.org/) -->
|
||||
|
||||
<svg
|
||||
xmlns:dc="http://purl.org/dc/elements/1.1/"
|
||||
xmlns:cc="http://creativecommons.org/ns#"
|
||||
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
|
||||
xmlns:svg="http://www.w3.org/2000/svg"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
|
||||
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
|
||||
width="147.67236mm"
|
||||
height="86.663628mm"
|
||||
viewBox="0 0 523.24853 307.07585"
|
||||
id="svg2"
|
||||
version="1.1"
|
||||
inkscape:version="0.91 r13725"
|
||||
sodipodi:docname="tablet.svg">
|
||||
<defs
|
||||
id="defs4">
|
||||
<linearGradient
|
||||
inkscape:collect="always"
|
||||
id="linearGradient4294">
|
||||
<stop
|
||||
style="stop-color:#1a1a1a;stop-opacity:1;"
|
||||
offset="0"
|
||||
id="stop4296" />
|
||||
<stop
|
||||
style="stop-color:#808080;stop-opacity:1"
|
||||
offset="1"
|
||||
id="stop4298" />
|
||||
</linearGradient>
|
||||
<linearGradient
|
||||
inkscape:collect="always"
|
||||
xlink:href="#linearGradient4294"
|
||||
id="linearGradient4300"
|
||||
x1="465.81339"
|
||||
y1="666.13727"
|
||||
x2="454.82117"
|
||||
y2="658.65521"
|
||||
gradientUnits="userSpaceOnUse" />
|
||||
</defs>
|
||||
<sodipodi:namedview
|
||||
id="base"
|
||||
pagecolor="#ffffff"
|
||||
bordercolor="#666666"
|
||||
borderopacity="1.0"
|
||||
inkscape:pageopacity="0.0"
|
||||
inkscape:pageshadow="2"
|
||||
inkscape:zoom="0.98994949"
|
||||
inkscape:cx="605.97861"
|
||||
inkscape:cy="-35.324315"
|
||||
inkscape:document-units="px"
|
||||
inkscape:current-layer="layer3"
|
||||
showgrid="false"
|
||||
showguides="true"
|
||||
inkscape:guide-bbox="true"
|
||||
inkscape:window-width="1920"
|
||||
inkscape:window-height="1136"
|
||||
inkscape:window-x="0"
|
||||
inkscape:window-y="27"
|
||||
inkscape:window-maximized="1"
|
||||
fit-margin-top="0"
|
||||
fit-margin-left="0"
|
||||
fit-margin-right="0"
|
||||
fit-margin-bottom="0">
|
||||
<sodipodi:guide
|
||||
position="127.77903,266.16996"
|
||||
orientation="0,1"
|
||||
id="guide4164" />
|
||||
<sodipodi:guide
|
||||
position="125.25365,38.380555"
|
||||
orientation="0,1"
|
||||
id="guide4166" />
|
||||
</sodipodi:namedview>
|
||||
<metadata
|
||||
id="metadata7">
|
||||
<rdf:RDF>
|
||||
<cc:Work
|
||||
rdf:about="">
|
||||
<dc:format>image/svg+xml</dc:format>
|
||||
<dc:type
|
||||
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
|
||||
<dc:title></dc:title>
|
||||
</cc:Work>
|
||||
</rdf:RDF>
|
||||
</metadata>
|
||||
<g
|
||||
inkscape:label="tablet"
|
||||
inkscape:groupmode="layer"
|
||||
id="layer1"
|
||||
style="display:inline"
|
||||
transform="translate(-75.261625,-133.63374)">
|
||||
<g
|
||||
id="g4309"
|
||||
inkscape:export-xdpi="90"
|
||||
inkscape:export-ydpi="90">
|
||||
<rect
|
||||
y="134.15933"
|
||||
x="75.787216"
|
||||
height="306.02466"
|
||||
width="522.19733"
|
||||
id="rect4136"
|
||||
style="opacity:0.92000002;fill:#4d4d4d;fill-opacity:1;stroke:#4d4d4d;stroke-width:1.05118144;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:4.20472551, 1.05118138;stroke-dashoffset:0;stroke-opacity:1" />
|
||||
<rect
|
||||
style="opacity:0.92000002;fill:#4d4d4d;fill-opacity:1;stroke:#4d4d4d;stroke-width:0.74813837;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:2.99255325, 0.74813831;stroke-dashoffset:0;stroke-opacity:1"
|
||||
id="rect4140"
|
||||
width="357.34042"
|
||||
height="226.52563"
|
||||
x="199.33878"
|
||||
y="175.42407" />
|
||||
<rect
|
||||
y="175.72914"
|
||||
x="103.10225"
|
||||
height="22.142857"
|
||||
width="65"
|
||||
id="rect4142"
|
||||
style="opacity:0.92000002;fill:#4d4d4d;fill-opacity:1;stroke:#4d4d4d;stroke-width:0.98900002;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:3.956, 0.989;stroke-dashoffset:0;stroke-opacity:1" />
|
||||
<rect
|
||||
style="opacity:0.92000002;fill:#4d4d4d;fill-opacity:1;stroke:#4d4d4d;stroke-width:0.98900002;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:3.956, 0.989;stroke-dashoffset:0;stroke-opacity:1"
|
||||
id="rect4148"
|
||||
width="65"
|
||||
height="22.142857"
|
||||
x="103.10225"
|
||||
y="203.72914" />
|
||||
<rect
|
||||
y="231.72913"
|
||||
x="103.10225"
|
||||
height="22.142857"
|
||||
width="65"
|
||||
id="rect4150"
|
||||
style="opacity:0.92000002;fill:#4d4d4d;fill-opacity:1;stroke:#4d4d4d;stroke-width:0.98900002;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:3.956, 0.989;stroke-dashoffset:0;stroke-opacity:1" />
|
||||
<rect
|
||||
y="323.72913"
|
||||
x="103.10225"
|
||||
height="22.142857"
|
||||
width="65"
|
||||
id="rect4154"
|
||||
style="opacity:0.92000002;fill:#4d4d4d;fill-opacity:1;stroke:#4d4d4d;stroke-width:0.98900002;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:3.956, 0.989;stroke-dashoffset:0;stroke-opacity:1" />
|
||||
<rect
|
||||
style="opacity:0.92000002;fill:#4d4d4d;fill-opacity:1;stroke:#4d4d4d;stroke-width:0.98900002;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:3.956, 0.989;stroke-dashoffset:0;stroke-opacity:1"
|
||||
id="rect4156"
|
||||
width="65"
|
||||
height="22.142857"
|
||||
x="103.10225"
|
||||
y="351.72913" />
|
||||
<circle
|
||||
r="22.98097"
|
||||
cy="287.06125"
|
||||
cx="135.61298"
|
||||
id="path4158"
|
||||
style="opacity:0.92000002;fill:#4d4d4d;fill-opacity:1;stroke:#4d4d4d;stroke-width:0.98900002;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:3.956, 0.989;stroke-dashoffset:0;stroke-opacity:1" />
|
||||
<ellipse
|
||||
ry="12.608653"
|
||||
rx="11.5985"
|
||||
style="opacity:0.92000002;fill:#4d4d4d;fill-opacity:1;stroke:#4d4d4d;stroke-width:0.52043104;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:2.08172421, 0.52043105;stroke-dashoffset:0;stroke-opacity:1"
|
||||
id="circle4160"
|
||||
cx="135.61298"
|
||||
cy="287.06125" />
|
||||
<rect
|
||||
y="379.72913"
|
||||
x="103.10225"
|
||||
height="22.142857"
|
||||
width="65"
|
||||
id="rect4162"
|
||||
style="opacity:0.92000002;fill:#4d4d4d;fill-opacity:1;stroke:#4d4d4d;stroke-width:0.98900002;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:3.956, 0.989;stroke-dashoffset:0;stroke-opacity:1" />
|
||||
</g>
|
||||
</g>
|
||||
<g
|
||||
inkscape:groupmode="layer"
|
||||
id="layer3"
|
||||
inkscape:label="stylus"
|
||||
style="display:inline"
|
||||
transform="translate(-75.261625,-133.63374)">
|
||||
<g
|
||||
id="g4304"
|
||||
transform="matrix(0.37129971,0.09948946,-0.09618892,0.35898192,295.60339,7.6883643)">
|
||||
<path
|
||||
sodipodi:nodetypes="czcc"
|
||||
inkscape:connector-curvature="0"
|
||||
id="path4286"
|
||||
d="m 387.83544,799.76093 c -1.1128,3.61694 -3.2211,13.05163 -1.08543,14.07769 2.13567,1.02606 7.81039,-3.72162 10.99756,-6.69095 z"
|
||||
style="display:inline;fill:#cccccc;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
|
||||
<path
|
||||
sodipodi:nodetypes="ssssccssscsssssssssssssssssss"
|
||||
inkscape:connector-curvature="0"
|
||||
id="path4283"
|
||||
d="m 392.64431,804.79039 c -8.52094,-5.90399 -8.49394,-11.01546 0.22879,-43.30647 1.03999,-3.85 2.46829,-9.67602 3.17399,-12.9467 0.99731,-4.62219 2.39455,-7.29497 6.27321,-12 2.74456,-3.32932 5.25157,-6.2783 5.57113,-6.5533 40.78433,-60.97488 80.48307,-125.1652 118.27253,-184 9.86283,-15.675 26.59424,-42.225 37.18089,-59 10.58666,-16.775 34.01422,-53.9 52.06125,-82.5 18.04703,-28.6 35.04505,-55.31677 37.77338,-59.37059 l 4.9606,-7.3706 4.1828,0.57332 c 4.16371,0.5707 4.19706,0.54958 7.30887,-4.62941 3.75631,-6.2516 8.82067,-11.57582 12.2516,-12.88026 5.99391,-2.27888 14.03303,2.9506 14.03303,9.12854 0,3.90203 -2.51704,10.62127 -6.02878,16.09385 -1.63417,2.54664 -2.97122,4.85949 -2.97122,5.13969 0,0.28019 0.9,1.54715 2,2.81546 2.28453,2.63408 2.47267,4.21918 0.86833,7.31574 -1.28218,2.47476 -26.61383,45.18798 -55.85724,94.18426 -10.83283,18.15 -25.72943,43.1137 -33.10357,55.47489 -7.37413,12.3612 -13.69273,23.17153 -14.04131,24.02297 -0.34859,0.85144 -7.50972,12.78774 -15.91363,26.52511 -15.54138,25.40455 -32.24417,52.9052 -70.74345,116.47703 -40.26028,66.47968 -43.66308,72.46026 -49.21634,86.5 -1.74036,4.4 -3.92035,8.675 -4.8444,9.5 -0.92405,0.825 -4.36246,3.75 -7.6409,6.5 -3.27845,2.75 -9.57132,8.3067 -13.98415,12.34823 -10.62726,9.73304 -16.99729,13.87361 -22.52334,14.64034 -3.99187,0.55386 -5.03885,0.251 -9.27207,-2.6821 z"
|
||||
style="display:inline;fill:#000000" />
|
||||
<path
|
||||
sodipodi:nodetypes="scccs"
|
||||
inkscape:connector-curvature="0"
|
||||
id="path4292"
|
||||
d="m 450.89044,688.88586 c 8.71518,5.62513 45.74035,-59.18436 43.57923,-75.43494 l -7.07107,-6.56599 c -29.93081,25.86352 -47.78438,74.72281 -47.78438,74.72281 0,0 0,0 11.27622,7.27812 z"
|
||||
style="fill:url(#linearGradient4300);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 8.8 KiB |
|
|
@ -6,7 +6,53 @@ support in libinput. Note that the term "tablet" in libinput refers to
|
|||
graphics tablets only (e.g. Wacom Intuos), not to tablet devices like the
|
||||
Apple iPad.
|
||||
|
||||
@section fake-proximity Handling of proximity events
|
||||
@image html tablet.svg "Illustration of a graphics tablet"
|
||||
|
||||
@section tablet-tools Tablet buttons vs. tablet tools
|
||||
|
||||
Most tablets provide two types of devices. The pysical tablet often provides
|
||||
a number of buttons and a touch ring or strip. Interaction on the drawing
|
||||
surface of the tablet requires a tool, usually in the shape of a stylus.
|
||||
The libinput interface exposed by devices with the @ref
|
||||
LIBINPUT_DEVICE_CAP_TABLET_TOOL applies only to events generated by tools.
|
||||
|
||||
Touch events on the tablet itself are exposed
|
||||
through the @ref LIBINPUT_DEVICE_CAP_TOUCH capability and are often found on
|
||||
a separate libinput device. See libinput_device_get_device_group() for
|
||||
information on how to associate the touch part with other devices exposed by
|
||||
the same physical hardware.
|
||||
|
||||
@section tablet-tip Tool tip events vs. button events
|
||||
|
||||
The primary use of a tablet tool is to draw on the surface of the tablet.
|
||||
When the tool tip comes into contact with the surface, libinput sends an
|
||||
event of type @ref LIBINPUT_EVENT_TABLET_TOOL_TIP, and again when the tip
|
||||
ceases contact with the surface.
|
||||
|
||||
Tablet tools may send button events; these are exclusively for extra buttons
|
||||
unrelated to the tip. A button event is independent of the tip and occur
|
||||
at any time.
|
||||
|
||||
@section tablet-axes Special axes on tablet tools
|
||||
|
||||
A tablet tool usually provides additional information beyond x/y positional
|
||||
information and the tip state. A tool may provide the distance to the tablet
|
||||
surface and the pressure exerted on the tip when in contact. Some tablets
|
||||
additionally provide tilt information along the x and y axis.
|
||||
|
||||
@image html tablet-axes.svg "Illustration of the distance, pressure and tilt axes"
|
||||
|
||||
The granularity and precision of these axes varies between tablet devices
|
||||
and cannot usually be mapped into a physical unit.
|
||||
libinput normalizes distance and pressure into a fixed positive 2-byte
|
||||
integer range. The tilt axes are normalized into a signed 2-byte integer
|
||||
range.
|
||||
|
||||
While the normalization range is identical for these axes, a caller should
|
||||
not interpret identical values as identical across axes, i.e. a value V1 on
|
||||
the distance axis has no relation to the same value V1 on the pressure axis.
|
||||
|
||||
@section tablet-fake-proximity Handling of proximity events
|
||||
|
||||
libinput's @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY events represent the
|
||||
physical proximity limits of the device. In some cases the caller should
|
||||
|
|
@ -31,8 +77,8 @@ static bool in_proximity;
|
|||
|
||||
double value;
|
||||
|
||||
value = libinput_event_pointer_get_axis_value(device,
|
||||
LIBINPUT_TABLET_AXIS_DISTANCE);
|
||||
value = libinput_event_tablet_tool_get_axis_value(device,
|
||||
LIBINPUT_TABLET_TOOL_AXIS_DISTANCE);
|
||||
|
||||
if (value < min) {
|
||||
min = value;
|
||||
|
|
|
|||
|
|
@ -139,6 +139,9 @@ enum libinput_pointer_axis_source {
|
|||
*
|
||||
* Available axis types for a device. It must have the @ref
|
||||
* LIBINPUT_DEVICE_CAP_TABLET_TOOL capability.
|
||||
*
|
||||
* For details on the interpretation of these axes see
|
||||
* libinput_event_tablet_tool_get_axis_value().
|
||||
*/
|
||||
enum libinput_tablet_tool_axis {
|
||||
LIBINPUT_TABLET_TOOL_AXIS_X = 1,
|
||||
|
|
@ -1518,7 +1521,7 @@ libinput_event_tablet_tool_get_tool(struct libinput_event_tablet_tool *event);
|
|||
* Used to check whether or not a tool came in or out of proximity during an
|
||||
* event of type @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY.
|
||||
*
|
||||
* See @ref fake-proximity for recommendations on proximity handling.
|
||||
* See @ref tablet-fake-proximity for recommendations on proximity handling.
|
||||
*
|
||||
* @param event The libinput tablet event
|
||||
* @return The new proximity state of the tool from the event.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue