[PATCH libinput 2/5] Add a "switch" interface for parts of the SW_* range

[Peter Hutterer]

On Thu, Jan 05, 2017 at 05:11:26PM +1100, James Ye wrote:
> Adapted from:
> https://lists.freedesktop.org/archives/wayland-devel/2016-January/026349.html

Note: libinput requires patches to be signed-off please, thanks.

Only two doxygen nitpicks here, but given the diffstat to the patch you
linked to I'd like at least a Co-authored-by: for me ;)

and please also link to the bug report and expand the commit message to
contain enough information of what's planned. Most of that is available from
the patch above.

[...]

>  /**
> + * @ingroup device
> + *
> + * The state of a switch.
> + */
> +enum libinput_switch_state {
> +	LIBINPUT_SWITCH_STATE_OFF = 0,
> +	LIBINPUT_SWITCH_STATE_ON = 1,
> +};
> +
> +/**
> + * @ingroup device
> + *
> + * The type of a switch.
> + */
> +enum libinput_switch {
> +	/**
> +	 * The laptop lid was closed (LIBINPUT_SWITCH_STATE_ON) or opened
> +	 * (LIBINPUT_SWITCH_STATE_OFF).

Add @ref before the enum values so doxygen can pick them up

> +	 */
> +	LIBINPUT_SWITCH_LID = 1,
> +	/**
> +	 * The device was switched to or from tablet mode, usually by
> +	 * rotating the screen and fixating it in place over the keyboard so
> +	 * that the device now looks like a tablet.
> +	 */
> +	LIBINPUT_SWITCH_TABLET_MODE = 2,

Please add which mode corresponds to the switch state.

> +};
> +
> +/**
> + * @ingroup event_switch
> + * @struct libinput_event_switch
> + *
> + * A switch event representing a changed state in a switch.
> + */
> +struct libinput_event_switch;
> +
> +/**
>   * @ingroup base
>   *
>   * Event type for events returned by libinput_get_event().
> @@ -746,6 +784,8 @@ enum libinput_event_type {
>  	LIBINPUT_EVENT_GESTURE_PINCH_BEGIN,
>  	LIBINPUT_EVENT_GESTURE_PINCH_UPDATE,
>  	LIBINPUT_EVENT_GESTURE_PINCH_END,
> +
> +	LIBINPUT_EVENT_SWITCH_TOGGLE = 900,
>  };
>  
>  /**
> @@ -883,6 +923,17 @@ struct libinput_event_tablet_pad *
>  libinput_event_get_tablet_pad_event(struct libinput_event *event);
>  
>  /**
> + * Return the switch event that is this input event. If the event type does
> + * not match the switch event types, this function returns NULL.
> + *
> + * The inverse of this function is libinput_event_switch_get_base_event().
> + *
> + * @return A switch event, or NULL for other events
> + */
> +struct libinput_event_switch *
> +libinput_event_get_switch_event(struct libinput_event *event);
> +
> +/**
>   * @ingroup event
>   *
>   * Return the device event that is this input event. If the event type does
> @@ -2684,6 +2735,62 @@ uint64_t
>  libinput_event_tablet_pad_get_time_usec(struct libinput_event_tablet_pad *event);
>  
>  /**
> + * @ingroup event_switch
> + *
> + * Return the switch that triggered this event.
> + * For pointer events that are not of type @ref
> + * LIBINPUT_EVENT_SWITCH_TOGGLE, this function returns 0.
> + *
> + * @note It is an application bug to call this function for events other than
> + * @ref LIBINPUT_EVENT_SWITCH_TOGGLE.
> + *
> + * @return The switch triggering this event
> + */
> +enum libinput_switch
> +libinput_event_switch_get_switch(struct libinput_event_switch *event);

double-check with the other event functions to see if we usually document
@param for them. I think we do, let's keep it consistent.

Cheers,
   Peter