ext-action-binder: add binding interface

ext-action-binding-v1 as an object that represents a single binded
action.

Signed-off-by: Anna (navi) Figueiredo Gomes <navi@vlhl.dev>

1 files changed, 106 insertions, 105 deletions

diff --git a/staging/ext-action-binder/ext-action-binder-v1.xml b/staging/ext-action-binder/ext-action-binder-v1.xml
index 545b917..9373a62 100644
--- a/staging/ext-action-binder/ext-action-binder-v1.xml
+++ b/staging/ext-action-binder/ext-action-binder-v1.xml
@@ -1,122 +1,123 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <protocol name="action_binder_v1">
-	<copyright>
-		Copyright © 2015-2017 Quentin “Sardem FF7” Glidic, 2023 Anna "navi" Figueiredo Gomes
+  <copyright>
+    Copyright © 2015-2017 Quentin “Sardem FF7” Glidic, 2023 Anna "navi" Figueiredo Gomes
 
-		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.
+    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>
+    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="ext_action_binder_v1" version="1">
-		<description summary="action binder">
-			This interface is designed to allow any application to bind
-			an action.
+  <interface name="ext_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.
+      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.
+      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 interface is exposed as global
-		</description>
+      This interface is exposed as global
+    </description>
 
-		<request name="destroy" type="destructor">
-			<description summary="unbind the actions">
-				The client no longer wants to receive events for any action.
-			</description>
-		</request>
+    <request name="destroy" type="destructor">
+      <description summary="unbind the actions">
+        The client no longer wants to receive events for any action.
+      </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.
-				After calling bind, the "action_bound" event is fired by the compositor
-				with the status of the request.
-			</description>
+    <request name="create_binding">
+      <description summary="create a binding">
+      </description>
+      <arg name="binding" type="new_id" interface="ext_action_binding_v1" summary="the new binding" />
+    </request>
+  </interface>
 
-			<arg name="action_namespace" type="string" summary="the action namespace" />
-			<arg name="action_name" type="string" summary="the action name" />
-			<arg name="description" type="string" summary="a human-readable description of what the binding does" />
-			<arg name="preferred_trigger" type="string" summary="a trigger that the client would like to trigger the action" />
-		</request>
+  <interface name="ext_action_binding_v1" version="1">
+    <request name="destroy" type="destructor">
+      <description summary="unbind the actions">
+        The client no longer wants to receive events for this binding.
+      </description>
+    </request>
 
-		<request name="unbind">
-			<description summary="unbind an action">
-				Removes a specific binding to the object. if the client does not hold any
-				binding to the namespace:name combo, no operation is performed.
-			</description>
-			<arg name="action_namespace" type="string" summary="the action namespace" />
-			<arg name="action_name" type="string" summary="the action name" />
-		</request>
+    <request name="bind">
+      <description summary="binds an action">
+        Bind an action to the object. this is a one-time request.
+        After calling bind, the "action_bound" event is fired by the compositor
+        with the status of the request.
+        Subsequent calls to bind should be ignored.
+      </description>
+      <arg name="action_namespace" type="string" summary="the action namespace" />
+      <arg name="action_name" type="string" summary="the action name" />
+      <arg name="description" type="string" summary="a human-readable description of what the binding does" />
+      <arg name="preferred_trigger" type="string" summary="a trigger that the client would like to trigger the action" />
+    </request>
 
-		<enum name="result">
-			<entry name="bound" value="0"
-				summary="the bind to the action was successful" />
-			<entry name="rejected" value="1"
-				summary="the bind was rejected by the compositor" />
-			<entry name="reserved" value="2"
-				summary="the action is reserved by the compositor" />
-		</enum>
+    <enum name="result">
+      <entry name="bound" value="0"
+        summary="the bind to the action was successful" />
+      <entry name="rejected" value="1"
+        summary="the bind was rejected by the compositor" />
+    </enum>
 
-		<event name="action_bound">
-			<description summary="the compositor processed the bind request">
-				After the compositor processes a bind request, it should call this
-				event to notify the client of the result, as well as the trigger, in
-				case of success.
-			</description>
-			<arg name="status" type="uint" enum="result" summary="" />
-			<arg name="trigger" type="string" summary="human-readable string describing the trigger for the action" />
-		</event>
+    <event name="action_bound">
+      <description summary="the compositor processed the bind request">
+        After the compositor processes a bind request, it calls this
+        event to notify the client of the result.
+        in case of success, the trigger set to this action is returned, if any.
+        in case of failure, this action is destroyed and should not be used anymore.
+      </description>
+      <arg name="status" type="uint" enum="result" summary="" />
+      <arg name="trigger" type="string" summary="human-readable string describing the trigger for the action" />
+    </event>
 
-		<enum name="trigger_type">
-			<description summary="type of binding triggered">
-				Depending on the user configuration, an action can be either one-off or
-				sustained. The client must handle all the three event types and either make
-				sense of them or ignore them properly.
-			</description>
-			<entry name="one_shot" value="0"
-				summary="a one shot action was triggered" />
-			<entry name="pressed" value="1"
-				summary="a sustained action was started" />
-			<entry name="released" value="2"
-				summary="a sustained action ended" />
-		</enum>
+    <enum name="trigger_type">
+      <description summary="type of binding triggered">
+        Depending on the user configuration, an action can be either one-off or
+        sustained. The client must handle all the three event types and either make
+        sense of them or ignore them properly.
+      </description>
+      <entry name="one_shot" value="0"
+        summary="a one shot action was triggered" />
+      <entry name="pressed" value="1"
+        summary="a sustained action was started" />
+      <entry name="released" value="2"
+        summary="a sustained action ended" />
+    </enum>
 
-		<event name="triggered">
-			<description summary="the action triggered">
-				This event is sent when actions are triggered.
-				If a binding would trigger both triggered and started events, the
-				started event must be sent first.
-			</description>
-			<arg name="action_namespace" type="string" summary="the action namespace" />
-			<arg name="action_name" type="string" summary="the action name" />
-			<arg name="trigger_type" type="uint" enum="trigger_type" summary="the type of trigger that was sent" />
-		</event>
-	</interface>
+    <event name="triggered">
+      <description summary="the action triggered">
+        This event is sent when actions are triggered.
+        If a binding would trigger both triggered and started events, the
+        started event must be sent first.
+      </description>
+      <arg name="type" type="uint" enum="trigger_type" summary="the type of trigger that was sent" />
+    </event>
+  </interface>
 </protocol>