[PATCH libinput 08/26] tablet: document what the tool type means

[Benjamin Tissoires]

On Tue, Feb 24, 2015 at 1:21 AM, Peter Hutterer
<peter.hutterer at who-t.net> wrote:
> It's a rough guide only, but still precise enough to make some decisions.
>
> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> ---
>  src/libinput.h | 32 +++++++++++++++++++++++---------
>  1 file changed, 23 insertions(+), 9 deletions(-)
>
> diff --git a/src/libinput.h b/src/libinput.h
> index f5c4e9f..984e8e3 100644
> --- a/src/libinput.h
> +++ b/src/libinput.h
> @@ -156,17 +156,31 @@ struct libinput_tool;
>   * @ingroup device
>   *
>   * Available tool types for a device. It must have the @ref
> - * LIBINPUT_DEVICE_CAP_TABLET capability.
> + * LIBINPUT_DEVICE_CAP_TABLET capability. The tool type defines the default
> + * usage of the tool as advertised by the manufacturer. Multiple different
> + * physical tools may share the same tool type, e.g. a Wacom Classic Pen,
> + * Wacom Pro Pen and a Wacom Grip Pen are all of type LIBINPUT_TOOL_PEN.
> + * Use libinput_tool_get_tool_id() to get a specific model where applicable.

We might need to @ref libinput_tool_get_tool_id()

And BTW, libinput_tool_get_tool_id() is added in the next commit :)

Cheers,
Benjamin

> + *
> + * Note that on some device, the eraser tool is on the tail end of a pen
> + * device. On other devices, e.g. MS Surface 3, the eraser is the pen tip
> + * while a button is held down.
> + *
> + * @note The @ref libinput_tool_type can only describe the default physical
> + * type of the device. For devices with adjustible physical properties
> + * the tool type remains the same, i.e. putting a Wacom stroke nib into a
> + * classic pen leaves the tool type as @ref LIBINPUT_TOOL_PEN.
>   */
>  enum libinput_tool_type {
> -       LIBINPUT_TOOL_PEN = 1,
> -       LIBINPUT_TOOL_ERASER,
> -       LIBINPUT_TOOL_BRUSH,
> -       LIBINPUT_TOOL_PENCIL,
> -       LIBINPUT_TOOL_AIRBRUSH,
> -       LIBINPUT_TOOL_FINGER,
> -       LIBINPUT_TOOL_MOUSE,
> -       LIBINPUT_TOOL_LENS
> +       LIBINPUT_TOOL_PEN = 1,          /**< A generic pen */
> +       LIBINPUT_TOOL_ERASER,           /**< Eraser */
> +       LIBINPUT_TOOL_BRUSH,            /**< A paintbrush-like tool */
> +       LIBINPUT_TOOL_PENCIL,           /**< Physical drawing tool, e.g.
> +                                            Wacom Inking Pen */
> +       LIBINPUT_TOOL_AIRBRUSH,         /**< An airbrush-like tool */
> +       LIBINPUT_TOOL_FINGER,           /**< Touch */
> +       LIBINPUT_TOOL_MOUSE,            /**< A mouse bound to the tablet */
> +       LIBINPUT_TOOL_LENS,             /**< A mouse tool with a lens */
>  };
>
>  /**
> --
> 2.1.0
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel