From c00bb3cb24d22cfe417874228dd4086729da8fa3 Mon Sep 17 00:00:00 2001
From: "Anna (navi) Figueiredo Gomes" <navi@vlhl.dev>
Date: Wed, 11 Oct 2023 10:33:05 +0200
Subject: ext-action-binder: split events and requests

action_bound split into bound and rejected
done to simplify binding logic and allow for rejecting a binding after
it was made

bind split into set_description, set_trigger_hint, set_name, and bind
done to allow future extensibilty

Signed-off-by: Anna (navi) Figueiredo Gomes <navi@vlhl.dev>
---
 staging/ext-action-binder/ext-action-binder-v1.xml | 65 +++++++++++++++-------
 1 file changed, 45 insertions(+), 20 deletions(-)

diff --git a/staging/ext-action-binder/ext-action-binder-v1.xml b/staging/ext-action-binder/ext-action-binder-v1.xml
index 9373a62..a32c463 100644
--- a/staging/ext-action-binder/ext-action-binder-v1.xml
+++ b/staging/ext-action-binder/ext-action-binder-v1.xml
@@ -53,8 +53,7 @@
     </request>
 
     <request name="create_binding">
-      <description summary="create a binding">
-      </description>
+      <description summary="create a binding"/>
       <arg name="binding" type="new_id" interface="ext_action_binding_v1" summary="the new binding" />
     </request>
   </interface>
@@ -66,37 +65,63 @@
       </description>
     </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.
+    <request name="set_name">
+      <description summary="sets the namespace:name of a binding">
+        Sets the namespace:name of the binding. This a kind of action.
       </description>
       <arg name="action_namespace" type="string" summary="the action namespace" />
       <arg name="action_name" type="string" summary="the action name" />
+    </request>
+
+    <request name="set_description">
+      <description summary="sets the human-readable description of a binding">
+        This description may be used by the compositor to render a ui for bindings.
+      </description>
       <arg name="description" type="string" summary="a human-readable description of what the binding does" />
+    </request>
+
+    <request name="set_trigger_hint">
+      <description summary="sets the machine-readable trigger of a binding">
+        The trigger is a suggestion to the compositor, and the action should not rely
+        to being set to that specific trigger.
+        The client does not know which trigger was actually set, but when a binding is
+        bound, it recieves from the compositor a human readable string describing the trigger,
+        if any, so it could show it in a ui.
+      </description>
       <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" />
+    <request name="bind">
+      <description summary="binds an action">
+        Bind an action to the object. this is a one-time request.
+        After calling bind, either the "bound" or "rejected" event is sent.
+        Subsequent calls to bind should be ignored.
+        If no action has been set for the binding, the error "invalid_action" is raised.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="invalid_action" value="0" summary="the binding has no action set"/>
     </enum>
 
-    <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.
+    <event name="bound">
+      <description summary="the compositor bound the binding to an action">
+        After the compositor processes a bind request, if the action was
+        bound to this binding, it calls this event to notify the client of the result.
       </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="rejected">
+      <description summary="the compositor rejected the binding">
+        After the compositor processes a bind request, if the binding was
+        rejected, it calls this event to notify the client of the result.
+        This event may be sent after a binding was bound, should the compositor
+        want to remove the binding.
+        After this event, the binding is destroyed and can't be used anymore.
+      </description>
+    </event>
+
     <enum name="trigger_type">
       <description summary="type of binding triggered">
         Depending on the user configuration, an action can be either one-off or
-- 
cgit v1.2.3