scrolling.html 9.91 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
<!-- HTML header for doxygen 1.8.8-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
<html xmlns="">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <!-- For Mobile Devices -->
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
        <meta name="generator" content="Doxygen 1.8.13"/>
        <script type="text/javascript" src=""></script>
        <title>libinput: Scrolling</title>
        <!--<link href="tabs.css" rel="stylesheet" type="text/css"/>-->
        <script type="text/javascript" src="dynsections.js"></script>
        <script type="text/x-mathjax-config">
    extensions: ["tex2jax.js"],
    jax: ["input/TeX","output/HTML-CSS"],
</script><script type="text/javascript" src=""></script>
        <link href="doxygen.css" rel="stylesheet" type="text/css" />
        <link href="bootstrap.css" rel="stylesheet" type="text/css"/>
<link href="customdoxygen.css" rel="stylesheet" type="text/css"/>
<link href="libinputdoxygen.css" rel="stylesheet" type="text/css"/>
        <script src=""></script>
        <script type="text/javascript" src="doxy-boot.js"></script>
        <nav class="navbar navbar-default" role="navigation">
            <div class="container">
                <div class="navbar-header">
                    <a class="navbar-brand">libinput 1.10.7</a>
        <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
            <div class="content" id="content">
                <div class="container">
                    <div class="row">
                        <div class="col-sm-12 panel panel-default" style="padding-bottom: 15px;">
                            <div style="margin-bottom: 15px;">
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
<div id="main-nav"></div>
<div id="nav-path" class="navpath">
<li class="navelem"><a class="el" href="touchpads.html">Touchpads</a></li>  </ul>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Scrolling </div>  </div>
<div class="contents">
<div class="textblock"><p>libinput supports three different types of scrolling methods: <a class="el" href="scrolling.html#twofinger_scrolling">Two-finger scrolling</a>, <a class="el" href="scrolling.html#edge_scrolling">Edge scrolling</a> and <a class="el" href="scrolling.html#button_scrolling">On-Button scrolling</a>.</p>
<p>Some devices support multiple methods, though only one can be enabled at a time. As a general overview:</p><ul>
<li>touchpad devices with physical buttons below the touchpad support edge and two-finger scrolling</li>
<li>touchpad devices without physical buttons (<a class="el" href="clickpad_softbuttons.html">clickpads</a>) support two-finger scrolling only</li>
<li>pointing sticks provide on-button scrolling by default</li>
<li>mice and other pointing devices support on-button scrolling but it is not enabled by default</li>
<p>A device may differ from the above based on its capabilities. See <a class="el" href="group__config.html#ga482951a2b1faf837e43d30d9c92dc9d3" title="Set the scroll method for this device. ">libinput_device_config_scroll_set_method()</a> for documentation on how to switch methods and <a class="el" href="group__config.html#gacaad48862a67ca61cb8e257a7e80ee8c" title="Check which scroll methods a device supports. ">libinput_device_config_scroll_get_methods()</a> for documentation on how to query a device for available scroll methods.</p>
<h1><a class="anchor" id="horizontal_scrolling"></a>
Horizontal scrolling</h1>
<p>Scroll movements provide vertical and horizontal directions, each scroll event contains both directions where applicable, see <a class="el" href="group__event__pointer.html#ga81ad7d8a95c456731a874e584c4c8dda" title="Return the axis value of the given axis. ">libinput_event_pointer_get_axis_value()</a>. libinput does not provide separate toggles to enable or disable horizontal scrolling. Instead, horizontal scrolling is always enabled. This is intentional, libinput does not have enough context to know when horizontal scrolling is appropriate for a given widget. The task of filtering horizontal movements is up to the caller.</p>
<h1><a class="anchor" id="twofinger_scrolling"></a>
Two-finger scrolling</h1>
<p>The default on two-finger capable touchpads (almost all modern touchpads are capable of detecting two fingers). Scrolling is triggered by two fingers being placed on the surface of the touchpad, then moving those fingers vertically or horizontally.</p>
<div class="image">
<object type="image/svg+xml" data="twofinger-scrolling.svg">twofinger-scrolling.svg</object>
<div class="caption">
Vertical and horizontal two-finger scrolling</div></div>
<p> For scrolling to trigger, a built-in distance threshold has to be met but once engaged any movement will scroll. In other words, to start scrolling a sufficiently large movement is required, once scrolling tiny amounts of movements will translate into tiny scroll movements. Scrolling in both directions at once is possible by meeting the required distance thresholds to enable each direction separately.</p>
<p>Two-finger scrolling requires the touchpad to track both touch points with reasonable precision. Unfortunately, some so-called "semi-mt" touchpads can only track the bounding box of the two fingers rather than the actual position of each finger. In addition, that bounding box usually suffers from a low resolution, causing jumpy movement during two-finger scrolling. libinput does not provide two-finger scrolling on those touchpads.</p>
<h1><a class="anchor" id="edge_scrolling"></a>
Edge scrolling</h1>
<p>On some touchpads, edge scrolling is available, triggered by moving a single finger along the right edge (vertical scroll) or bottom edge (horizontal scroll).</p>
<div class="image">
<object type="image/svg+xml" data="edge-scrolling.svg">edge-scrolling.svg</object>
<div class="caption">
Vertical and horizontal edge scrolling</div></div>
<p> Due to the layout of the edges, diagonal scrolling is not possible. The behavior of edge scrolling using both edges at the same time is undefined.</p>
<p>Edge scrolling overlaps with <a class="el" href="clickpad_softbuttons.html">Clickpad software button behavior</a>. A physical click on a clickpad ends scrolling.</p>
<h1><a class="anchor" id="button_scrolling"></a>
On-Button scrolling</h1>
<p>On-button scrolling converts the motion of a device into scroll events while a designated button is held down. For example, Lenovo devices provide a <a href="">pointing stick</a> that emulates scroll events when the trackstick's middle mouse button is held down.</p>
<dl class="section note"><dt>Note</dt><dd>On-button scrolling is enabled by default for pointing sticks. This prevents middle-button dragging; all motion events while the middle button is down are converted to scroll events.</dd></dl>
<div class="image">
<object type="image/svg+xml" data="button-scrolling.svg">button-scrolling.svg</object>
<div class="caption">
Button scrolling</div></div>
<p> The button may be changed with <a class="el" href="group__config.html#gac95a25055b22c3631e3c10c0463ca332" title="Set the button for the LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method for this device. ">libinput_device_config_scroll_set_button()</a> but must be on the same device as the motion events. Cross-device scrolling is not supported but for one exception: libinput's <a class="el" href="t440_support.html">Lenovo *40 series touchpad support</a> enables the use of the middle button for button scrolling (even when the touchpad is disabled).</p>
<h1><a class="anchor" id="scroll_sources"></a>
Scroll sources</h1>
<p>libinput provides a pointer axis <em>source</em> for each scroll event. The source can be obtained with the <a class="el" href="group__event__pointer.html#ga2116f4bbedb61532e71d16c4f87bd4ca" title="Return the source for a given axis event. ">libinput_event_pointer_get_axis_source()</a> function and is one of <b>wheel</b>, <b>finger</b>, or <b>continuous</b>. The source information lets a caller decide when to implement kinetic scrolling. Usually, a caller will process events of source wheel as they come in. For events of source finger a caller should calculate the velocity of the scroll motion and upon finger release start a kinetic scrolling motion (i.e. continue executing a scroll according to some friction factor). libinput expects the caller to be in charge of widget handling, the source information is thus enough to provide kinetic scrolling on a per-widget basis. A caller should cancel kinetic scrolling when the pointer leaves the current widget or when a key is pressed.</p>
<p>See the <a class="el" href="group__event__pointer.html#ga2116f4bbedb61532e71d16c4f87bd4ca" title="Return the source for a given axis event. ">libinput_event_pointer_get_axis_source()</a> for details on the behavior of each scroll source.</p>
<p>See also <a href=""></a> </p>
</div></div><!-- contents -->
<!-- HTML footer for doxygen 1.8.8-->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13