Add action binder protocol

Signed-off-by: Quentin Glidic <sardemff7+git@sardemff7.net>

1 files changed, 121 insertions, 0 deletions

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.
+
+      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>
+    </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>