[PATCH libinput] Add doc to discourage use of libinput_device_get_output_name()

[Pekka Paalanen]

On Mon, 24 Apr 2017 10:01:49 +1000
Peter Hutterer <peter.hutterer at who-t.net> wrote:

> This is a leftover from when libinput was part of weston and we could
> interpret properties correctly. Realistically, the only way this could work
> with libinput as external library is if we define precisely what the
> definition of an output is. Practically, it's a lot easier to just throw up
> our hands and leave it all to the caller.
> 
> https://bugs.freedesktop.org/show_bug.cgi?id=100707
> 
> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> Reviewed-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> ---
> Pekka: I added the last sentence on top of the patch from 100707, but left
> your rev-by on it. If you disagree with that, we'll have to figure it out
> over a bout of fisticuffs in the sand pit ;)

Nah, all good!


Thanks,
pq

>  src/libinput.h | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/src/libinput.h b/src/libinput.h
> index aa30cfa..430fe18 100644
> --- a/src/libinput.h
> +++ b/src/libinput.h
> @@ -3491,6 +3491,14 @@ libinput_device_get_id_vendor(struct libinput_device *device);
>   * beyond the boundaries of this output. An absolute device has its input
>   * coordinates mapped to the extents of this output.
>   *
> + * @note <b>Use of this function is discouraged.</b> Its return value is not
> + * precisely defined and may not be understood by the caller or may be
> + * insufficient to map the device. Instead, the system configuration could
> + * set a udev property the caller understands and interprets correctly. The
> + * caller could then obtain device with libinput_device_get_udev_device()
> + * and query it for this property. For more complex cases, the caller
> + * must implement monitor-to-device association heuristics.
> + *
>   * @return The name of the output this device is mapped to, or NULL if no
>   * output is set
>   */

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20170424/8f1cba48/attachment.sig>