[RFC,wayland-protocols] unstable: add xcursor-configuration

Submitted by Johan Helsing on Oct. 16, 2018, 12:10 p.m.

Details

Message ID AM5PR0201MB2369F6F0E7308ABA66F0AC9DE9FE0@AM5PR0201MB2369.eurprd02.prod.outlook.com
State New
Series "unstable: add xcursor-configuration"
Headers show

Commit Message

Johan Helsing Oct. 16, 2018, 12:10 p.m.
Hi Simon,

Thanks for working on this! :)

Is the intention to implement the client side inside libwayland-cursor? No
changes needed for toolkits except calling some new API when initializing
libwayland-cursor?

I guess it's also possible to implement it on the toolkit level using the old
libwayland-cursor API... Which would allow us to use the extension before
everyone has upgraded to the new libwayland-cursor.

> +    <request name="get_xcursor_configuration_seat">

To me, this sounds a bit like we're getting some kind of seat from the
request. How about get_seat_xcursor_configuration? Or simply
get_xcursor_configuration?

> +    <event name="default_cursor">
> +      <description summary="default cursor name">
> +        The default_cursor event describes the default XCursor cursor name to be
> +        used for this seat.
> +      </description>

Maybe explain the use case here?

And another thing, maybe we can explicitly say this is a hint for the client?
I'm asking because I don't think we have a matching concept of a default
cursor in Qt... We just have Qt::QCursorShape::ArrowCursor. We could
make this request override what that shape is, but that might be confusing
to application developers if some compositor decides to set the default
cursor to a cross or some other non-arrow cursor. Anyway, this event is
going to cause some minor issues in Qt, perhaps in other toolkits as well.

Otherwise, this looks great :) Looking forward to having uniform cursor
sizes!

Johan

Patch hide | download patch | download mbox

diff --git a/unstable/xcursor-configuration/README b/unstable/xcursor-configuration/README
new file mode 100644
index 0000000..472e3bf
--- /dev/null
+++ b/unstable/xcursor-configuration/README
@@ -0,0 +1,4 @@ 
+xcursor configuration protocol
+
+Maintainers:
+Simon Ser <contact@emersion.fr>
diff --git a/unstable/xcursor-configuration/xcursor-configuration-unstable-v1.xml b/unstable/xcursor-configuration/xcursor-configuration-unstable-v1.xml
new file mode 100644
index 0000000..9d9d840
--- /dev/null
+++ b/unstable/xcursor-configuration/xcursor-configuration-unstable-v1.xml
@@ -0,0 +1,105 @@ 
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="wp_xcursor_configuration_unstable_v1">
+  <copyright>
+    Copyright © 2018 Simon Ser
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="protocol to configure XCursor themes">
+    This protocol allows compositors to advertize XCursor configuration to
+    clients.
+
+    Once compositor configuration is received, clients are responsible for
+    loading the XCursor theme, creating wl_buffers with cursor images and
+    setting the cursor.
+
+    Warning! The protocol described in this file is experimental and
+    backward incompatible changes may be made. Backward compatible changes
+    may be added together with the corresponding interface version bump.
+    Backward incompatible changes are done by bumping the version number in
+    the protocol and interface names and resetting the interface version.
+    Once the protocol is to be declared stable, the 'z' prefix and the
+    version number in the protocol and interface names are removed and the
+    interface version number is reset.
+  </description>
+
+  <interface name="zwp_xcursor_configuration_manager_v1" version="1">
+    <description summary="XCursor configuration manager">
+      A global factory interface for wp_xcursor_configuration objects.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the XCursor configuration manager object">
+        Destroy the XCursor configuration manager. This doesn't destroy objects
+        created with the manager.
+      </description>
+    </request>
+
+    <request name="get_xcursor_configuration_seat">
+      <description summary="create a wp_xcursor_configuration object for a seat">
+        This creates a new wp_xcursor_configuration object for the given
+        wl_seat.
+      </description>
+      <arg name="id" type="new_id" interface="zwp_xcursor_configuration_v1"/>
+      <arg name="seat" type="object" interface="wl_seat"/>
+    </request>
+  </interface>
+
+  <interface name="zwp_xcursor_configuration_v1" version="1">
+    <description summary="XCursor configuration for a seat">
+      A Xcursor configuration seat object describes XCursor settings for a
+      specific seat.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy this object">
+        Using this request a client can tell the server that it is not going to
+        use this object anymore.
+      </description>
+    </request>
+
+    <event name="done">
+      <description summary="all information about the configuration has been sent">
+        This event is sent after all other properties of a
+        wp_xcursor_configuration have been sent.
+
+        This allows changes to the wp_xcursor_configuration properties to be
+        seen as atomic, even if they happen via multiple events.
+      </description>
+    </event>
+
+    <event name="theme">
+      <description summary="theme configuration">
+        The theme event describes XCursor theme configuration for this seat.
+      </description>
+      <arg name="name" type="string" summary="theme name"/>
+      <arg name="size" type="uint" summary="theme size"/>
+    </event>
+
+    <event name="default_cursor">
+      <description summary="default cursor name">
+        The default_cursor event describes the default XCursor cursor name to be
+        used for this seat.
+      </description>
+      <arg name="name" type="string" summary="default cursor name"/>
+    </event>
+  </interface>
+</protocol>

Comments

Simon Ser Oct. 18, 2018, 10:08 a.m.
On Tuesday, October 16, 2018 2:10 PM, Johan Helsing <johan.helsing@qt.io> wrote:
> Hi Simon,
>
> Thanks for working on this! :)

Thanks for your feedback! I've sent a first version of this patch. I've
added per-device configuration and addressed your comments. Let me know what
you think.

> Is the intention to implement the client side inside libwayland-cursor? No
> changes needed for toolkits except calling some new API when initializing
> libwayland-cursor?

Yeah, this is what's planned. The new design of the libwayland-cursor API will
be the difficult part of this task. I'll try to send a proposal soon.

> I guess it's also possible to implement it on the toolkit level using the old
> libwayland-cursor API... Which would allow us to use the extension before
> everyone has upgraded to the new libwayland-cursor.

Aye, this is possible.

> > +    <request name="get_xcursor_configuration_seat">
>
> To me, this sounds a bit like we're getting some kind of seat from the
> request. How about get_seat_xcursor_configuration? Or simply
> get_xcursor_configuration?

This makes sense, I'll rename to get_device_xcursor_configuration. I'd like to
make sure we can add new requests to create xcursor configuration objects in
the future, so I'd like to keep "device" in there.

> > +    <event name="default_cursor">
> > +      <description summary="default cursor name">
> > +        The default_cursor event describes the default XCursor cursor name to be
> > +        used for this seat.
> > +      </description>
>
> Maybe explain the use case here?

The use-case is to be able to tell the difference between two cursors without
having to pick two different cursor themes. For instance one could choose
left_ptr for the pointer and cross for the tablet tool.

Do you think we should include this example in the protocol?

> And another thing, maybe we can explicitly say this is a hint for the client?
> I'm asking because I don't think we have a matching concept of a default
> cursor in Qt... We just have Qt::QCursorShape::ArrowCursor. We could
> make this request override what that shape is, but that might be confusing
> to application developers if some compositor decides to set the default
> cursor to a cross or some other non-arrow cursor. Anyway, this event is
> going to cause some minor issues in Qt, perhaps in other toolkits as well.

You're right, I've mentioned this in the protocol description. Everything in
this protocol is a hint, clients could use it to e.g. just choose the cursor
size and use a custom theme.

For Qt, you could e.g. use default_cursor if the app doesn't set the cursor
itself, and switch to Qt::QCursorShape::ArrowCursor if the app requests it.
Of course, having Qt::QCursorShape::DefaultCursor would be nice too.

> Otherwise, this looks great :) Looking forward to having uniform cursor
> sizes!
>
> Johan