xref: /third_party/libinput/export_include/libinput.h

82  * An object representing a tool being used by a device with the @ref
85  * Tablet events generated by such a device are bound to a specific tool
87  * is possible to track the same physical tool across multiple
151  * Tablet tool event representing an axis update, button press, or tool
326  * Available tool types for a device with the @ref
327  * LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. The tool type defines the default
328  * usage of the tool as advertised by the manufacturer. Multiple different
329  * physical tools may share the same tool type, e.g. a Wacom Classic Pen,
334  * Note that on some device, the eraser tool is on the tail end of a pen
340  * the tool type remains the same, i.e. putting a Wacom stroke nib into a
341  * classic pen leaves the tool type as @ref LIBINPUT_TABLET_TOOL_TYPE_PEN.
348 	LIBINPUT_TABLET_TOOL_TYPE_BRUSH,	/**< A paintbrush-like tool */
349 	LIBINPUT_TABLET_TOOL_TYPE_PENCIL,	/**< Physical drawing tool, e.g.
351 	LIBINPUT_TABLET_TOOL_TYPE_AIRBRUSH,	/**< An airbrush-like tool */
353 	LIBINPUT_TABLET_TOOL_TYPE_LENS,		/**< A mouse tool with a lens */
362  * The state of proximity for a tool on a device. The device must have the @ref
365  * The proximity of a tool is a binary state signalling whether the tool is
366  * within a detectable distance of the tablet device. A tool that is out of
369  * On some hardware a tool goes out of proximity when it ceases to touch the
370  * surface. On other hardware, the tool is still detectable within a short
383  * The tip contact state for a tool on a device. The device must have
386  * The tip contact state of a tool is a binary state signalling whether the tool is
838 	 * when the tool is in proximity, see @ref
842 	 * tool comes into proximity. An event of type @ref
844 	 * changes from this initial state. It is possible for a tool to
856 	 * Signals that a tool has come in or out of proximity of a device with
869 	 * If the tool that comes into proximity supports x/y coordinates,
873 	 * When a tool goes out of proximity, the value of every axis should be
883 	 * Signals that a tool has come in contact with the surface of a
908 	 * Signals that a tool has changed a logical button state on a
1107  * Return the tablet tool event that is this input event. If the event type
1108  * does not match the tablet tool event types, this function returns NULL.
1112  * @return A tablet tool event, or NULL for other events
2133  * @param event The libinput tablet tool event
2156  * @param event The libinput tablet tool event
2179  * @param event The libinput tablet tool event
2195  * For tablet tool events of type @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY,
2204  * @param event The libinput tablet tool event
2227  * @param event The libinput tablet tool event
2250  * @param event The libinput tablet tool event
2272  * @param event The libinput tablet tool event
2294  * @param event The libinput tablet tool event
2317  * @param event The libinput tablet tool event
2338  * @param event The libinput tablet tool event
2359  * @param event The libinput tablet tool event
2371  * Returns the X coordinate of the tablet tool, in mm from the top left
2379  * @param event The libinput tablet tool event
2390  * Returns the Y coordinate of the tablet tool, in mm from the top left
2398  * @param event The libinput tablet tool event
2410  * If the tool employs pointer acceleration, the delta returned by this
2429  * If the tool employs pointer acceleration, the delta returned by this
2447  * Returns the current pressure being applied on the tool in use, normalized
2450  * If this axis does not exist on the current tool, this function returns 0.
2452  * @param event The libinput tablet tool event
2466  * If this axis does not exist on the current tool, this function returns 0.
2468  * @param event The libinput tablet tool event
2480  * orientation, in degrees off the tablet's z axis. That is, if the tool is
2486  * If this axis does not exist on the current tool, this function returns 0.
2488  * @param event The libinput tablet tool event
2500  * orientation, in degrees off the tablet's z axis. That is, if the tool is
2506  * If this axis does not exist on the current tool, this function returns 0.
2508  * @param event The libinput tablet tool event
2519  * Returns the current z rotation of the tool in degrees, clockwise from the
2520  * tool's logical neutral position.
2528  * If this axis does not exist on the current tool, this function returns 0.
2530  * @param event The libinput tablet tool event
2541  * Returns the current position of the slider on the tool, normalized to the
2546  * If this axis does not exist on the current tool, this function returns 0.
2548  * @param event The libinput tablet tool event
2563  * Where no rotation is available on a tool, or where rotation is zero, the
2566  * If this axis does not exist on the current tool, this function returns 0.
2568  * @param event The libinput tablet tool event
2581  * Where no rotation is available on a tool, or where rotation is zero, the
2584  * If this axis does not exist on the current tool, this function returns 0.
2586  * @param event The libinput tablet tool event
2597  * @param event The libinput tablet tool event
2611  * @param event The libinput tablet tool event
2625  * Return the current absolute x coordinate of the tablet tool event,
2635  * @param event The libinput tablet tool event
2648  * Return the current absolute y coordinate of the tablet tool event,
2658  * @param event The libinput tablet tool event
2671  * Returns the tool that was in use during this event.
2673  * The returned tablet tool is not refcounted and may become invalid after
2681  * @note Physical tool tracking requires hardware support. If unavailable,
2682  * libinput creates one tool per type per tablet. See
2685  * @param event The libinput tablet tool event
2686  * @return The new tool triggering this event
2696  * Returns the new proximity state of a tool from a proximity event.
2697  * Used to check whether or not a tool came in or out of proximity during an
2701  * necessarily match when a tool comes into sensor range or leaves the
2703  * range but a reduced tool-specific logical range. If the range is reduced,
2708  * the interaction normal mouse movements have, i.e. slightly lift the tool and
2711  * tool may not be lifted out of physical proximity. For such tools, libinput
2714  * @param event The libinput tablet tool event
2715  * @return The new proximity state of the tool from the event.
2725  * Returns the new tip state of a tool from a tip event.
2726  * Used to check whether or not a tool came in contact with the tablet
2730  * @param event The libinput tablet tool event
2731  * @return The new tip state of the tool from the event.
2747  * @param event The libinput tablet tool event
2763  * @param event The libinput tablet tool event
2781  * @param event The libinput tablet tool event
2795  * @param event The libinput tablet tool event
2809  * @param event The libinput tablet tool event
2820  * Return the high-level tool type for a tool object.
2822  * The high level tool describes general interaction expected with the tool.
2823  * For example, a user would expect a tool of type @ref
2825  * taking pressure and tilt into account. The default virtual tool assigned
2826  * should be a drawing tool, e.g. a virtual pen or brush.
2827  * A tool of type @ref LIBINPUT_TABLET_TOOL_TYPE_ERASER would normally be
2828  * mapped to an eraser-like virtual tool.
2830  * If supported by the hardware, a more specific tool id is always
2833  * @param tool The libinput tool
2834  * @return The tool type for this tool object
2841 libinput_tablet_tool_get_type(struct libinput_tablet_tool *tool);
2846  * Return the tool ID for a tool object. If nonzero, this number identifies
2847  * the specific type of the tool with more precision than the type returned in
2848  * libinput_tablet_tool_get_type(). Not all tablets support a tool ID.
2850  * Tablets known to support tool IDs include the Wacom Intuos 3, 4, 5, Wacom
2851  * Cintiq and Wacom Intuos Pro series. The tool ID can be used to
2853  * the caller's responsibility to interpret the tool ID.
2855  * @param tool The libinput tool
2856  * @return The tool ID for this tool object or 0 if none is provided
2863 libinput_tablet_tool_get_tool_id(struct libinput_tablet_tool *tool);
2868  * Increment the reference count of the tool by one. A tool is destroyed
2871  * @param tool The tool to increment the ref count of
2872  * @return The passed tool
2879 libinput_tablet_tool_ref(struct libinput_tablet_tool *tool);
2884  * Decrement the reference count of the tool by one. When the reference
2885  * count of the tool reaches 0, the memory allocated for the tool will be
2888  * @param tool The tool to decrement the ref count of
2889  * @return NULL if the tool was destroyed otherwise the passed tool
2896 libinput_tablet_tool_unref(struct libinput_tablet_tool *tool);
2901  * Return whether the tablet tool supports pressure.
2903  * @param tool The tool to check the axis capabilities of
2909 libinput_tablet_tool_has_pressure(struct libinput_tablet_tool *tool);
2914  * Return whether the tablet tool supports distance.
2916  * @param tool The tool to check the axis capabilities of
2922 libinput_tablet_tool_has_distance(struct libinput_tablet_tool *tool);
2927  * Return whether the tablet tool supports tilt.
2929  * @param tool The tool to check the axis capabilities of
2935 libinput_tablet_tool_has_tilt(struct libinput_tablet_tool *tool);
2940  * Return whether the tablet tool supports z-rotation.
2942  * @param tool The tool to check the axis capabilities of
2948 libinput_tablet_tool_has_rotation(struct libinput_tablet_tool *tool);
2953  * Return whether the tablet tool has a slider axis.
2955  * @param tool The tool to check the axis capabilities of
2961 libinput_tablet_tool_has_slider(struct libinput_tablet_tool *tool);
2966  * Return whether the tablet tool has a ellipsis major and minor.
2971  * @param tool The tool to check the axis capabilities of
2975 libinput_tablet_tool_has_size(struct libinput_tablet_tool *tool);
2980  * Return whether the tablet tool has a relative wheel.
2982  * @param tool The tool to check the axis capabilities of
2988 libinput_tablet_tool_has_wheel(struct libinput_tablet_tool *tool);
2993  * Check if a tablet tool has a button with the
2996  * @param tool A tablet tool
2999  * @return 1 if the tool supports this button code, 0 if it does not
3004 libinput_tablet_tool_has_button(struct libinput_tablet_tool *tool,
3010  * Return nonzero if the physical tool can be uniquely identified by
3011  * libinput, or nonzero otherwise. If a tool can be uniquely identified,
3012  * keeping a reference to the tool allows tracking the tool across
3016  * @param tool A tablet tool
3017  * @return 1 if the tool can be uniquely identified, 0 otherwise.
3024 libinput_tablet_tool_is_unique(struct libinput_tablet_tool *tool);
3029  * Return the serial number of a tool. If the tool does not report a serial
3036  * tool can be identified uniquely, a caller should use
3037  * libinput_tablet_tool_is_unique() to check if the tool is unique.
3040  * proximity in of this tool. By default, this struct is destroyed on
3042  * keeps a reference to the tool by using libinput_tablet_tool_ref()
3043  * libinput re-uses this struct whenever that same physical tool comes into
3045  * recognized by libinput. It is possible to attach tool-specific virtual
3046  * state to the tool. For example, a graphics program such as the GIMP may
3047  * assign a specific color to each tool, allowing the artist to use the
3049  * also possible to track the tool across devices.
3051  * If the tool does not have a unique identifier, libinput creates a single
3052  * struct @ref libinput_tablet_tool per tool type on each tablet the tool is
3055  * @param tool The libinput tool
3056  * @return The tool serial number
3063 libinput_tablet_tool_get_serial(struct libinput_tablet_tool *tool);
3068  * Return the user data associated with a tool object. libinput does
3072  * @param tool The libinput tool
3073  * @return The user data associated with the tool object
3078 libinput_tablet_tool_get_user_data(struct libinput_tablet_tool *tool);
3083  * Set the user data associated with a tool object, if any.
3085  * @param tool The libinput tool
3086  * @param user_data The user data to associate with the tool object
3091 libinput_tablet_tool_set_user_data(struct libinput_tablet_tool *tool,

Indexes created Thu Nov 07 10:32:03 CST 2024