[PATCH wayland-protocols] Add action binder protocol

Mon Apr 9 05:49:37 UTC 2018

Hey, look, almost year later and I found this email. In my defence, I was on
an airplane at the time, hence I missed this :)

This came up in #wayland where pekka linked to it, so I figured I might as
well look through it.

On Wed, Aug 16, 2017 at 09:19:06PM +0200, Quentin Glidic wrote:
> From: Quentin Glidic <sardemff7+git at sardemff7.net>
> 
> Signed-off-by: Quentin Glidic <sardemff7+git at sardemff7.net>
> ---
> 
> As for one-off vs. sustained actions, alternative wording was suggested:
> - one-shot vs. sustained
> - instantaneous vs. sustained
> - immediate vs. driven
> - triggered vs. initiated
> 
>  unstable/action-binder/README                      |   4 +
>  .../action-binder/action-binder-unstable-v1.xml    | 121 +++++++++++++++++++++
>  2 files changed, 125 insertions(+)
>  create mode 100644 unstable/action-binder/README
>  create mode 100644 unstable/action-binder/action-binder-unstable-v1.xml
> 
> diff --git a/unstable/action-binder/README b/unstable/action-binder/README
> new file mode 100644
> index 0000000..07fe7d4
> --- /dev/null
> +++ b/unstable/action-binder/README
> @@ -0,0 +1,4 @@
> +action binder protocol
> +
> +Maintainers:
> +Quentin Glidic <sardemff7+wayland at sardemff7.net>
> diff --git a/unstable/action-binder/action-binder-unstable-v1.xml b/unstable/action-binder/action-binder-unstable-v1.xml
> new file mode 100644
> index 0000000..a0e086b
> --- /dev/null
> +++ b/unstable/action-binder/action-binder-unstable-v1.xml
> @@ -0,0 +1,121 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="action_binder_unstable_v1">
> +
> +  <copyright>
> +    Copyright © 2015-2017 Quentin “Sardem FF7” Glidic
> +
> +    Permission to use, copy, modify, distribute, and sell this
> +    software and its documentation for any purpose is hereby granted
> +    without fee, provided that the above copyright notice appear in
> +    all copies and that both that copyright notice and this permission
> +    notice appear in supporting documentation, and that the name of
> +    the copyright holders not be used in advertising or publicity
> +    pertaining to distribution of the software without specific,
> +    written prior permission. The copyright holders make no
> +    representations about the suitability of this software for any
> +    purpose. It is provided "as is" without express or implied
> +    warranty.
> +
> +    THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
> +    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
> +    FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
> +    SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
> +    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
> +    AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
> +    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
> +    THIS SOFTWARE.
> +  </copyright>
> +
> +  <interface name="zwp_action_binder_v1" version="1">
> +    <description summary="action binder">
> +      This interface is designed to allow any application to bind
> +      an action.
> +
> +      An action is an arbitrary couple of a namespace and a name describing the
> +      wanted behaviour. These two strings are not meant to be user-visible.
> +      Some namespaces are well-known and shared by applications while each
> +      application can have its own namespaces for internal actions.
> +      It is possible to have the same action in several namespaces, e.g. to
> +      allow application-specific bindings in addition to global actions.

I may have missed some conversation there but without examples it's a bit
hard to understand  how the namespace and name separation is supposed to
work. Something like "generic" and "copy" maybe? Or "gimp", "tool:eraser"?
Can you expand on that?

> +
> +      It is left to the compositor to determine which client will get events.
> +      The choice can be based on policy, heuristic, user configuration, or any
> +      other mechanism that may be relevant.
> +      Here are some examples of dispatching choice: all applications, last
> +      focused, user-defined preference order, latest fullscreened application.
> +
> +      This object is a singleton global.
> +    </description>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="unbind from the binder interface">
> +	Informs the server that the client will not be using this protocol
> +	object anymore. You must destroy any wp_action_binding created from the
> +	wp_action_binder before.
> +      </description>
> +    </request>
> +
> +    <request name="get_binding">
> +      <description summary="creates a binding object">
> +	Creates a binding object. It will be used by the application to bind
> +	one or more actions and get the corresponding events.
> +      </description>
> +
> +      <arg name="id" type="new_id" interface="zwp_action_binding_v1"
> +           summary="the new binding interface id" />
> +    </request>
> +  </interface>
> +
> +  <interface name="zwp_action_binding_v1" version="1">
> +    <description summary="binding to an action">
> +      This interface represents a binding to a set of actions.
> +
> +      Depending on the user configuration, an action can be either one-off or
> +      sustained. The client must handle all the three events and either make
> +      sense of them or ignore them properly.
> +    </description>
> +
> +    <enum name="error">
> +      <entry name="reserved" value="0"
> +             summary="the action is reserved by the compositor" />
> +    </enum>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="unbind the actions">
> +	The client no longer wants to receive events for these actions.
> +      </description>
> +    </request>
> +
> +    <request name="bind">
> +      <description summary="bind an action">
> +	Bind an action to the object. Multiple actions can be bound at the same
> +	time. That means any combination of events can occur.
> +	If the action is reserved by the compositor a protocol error is raised.
> +      </description>
> +
> +      <arg name="action_namespace" type="string" summary="the action namespace" />
> +      <arg name="action_name" type="string" summary="the action name" />
> +    </request>
> +
> +    <event name="triggered">
> +      <description summary="the action triggered">
> +	This event is sent for one-off actions.
> +
> +	If a binding would trigger both triggered and started events, the
> +	started event must be sent first.
> +      </description>

This almost certainly needs a value, but at that point it gets a bit harder.
The example in the recent #wayland discussion was the wacom tablet pad
strip but this can get more convoluted quickly. A strip has one 
value but 2d manipulations (pinch-and-rotate) can have more axes. So maybe
something like 

   <event name="value">
     <description summary="the value for the subsequent action">
     This event is sent before started, stopped, or triggered and contains
     the value for the subsequent started, stopped, or triggered event. More
     than one value event may be sent, a client must accumulate all values
     in the order they are sent. The values are namespace/action specific.
      </description>
    </event>

It's not any more generic than the rest of the protocol ;)

Cheers,
   Peter

> +    </event>
> +
> +    <event name="started">
> +      <description summary="the action started">
> +	This event is sent when a sustained action is started.
> +      </description>
> +    </event>
> +
> +    <event name="stopped">
> +      <description summary="the action stopped">
> +	This event is sent when a sustained action is stopped.
> +      </description>
> +    </event>
> +  </interface>
> +</protocol>
> -- 
> 2.13.4
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
> 