hyprland-global-shortcuts-v1: protocol implementation (#3)

protocols/hyprland-global-shortcuts-v1.xml

@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="hyprland_global_shortcuts_v1">
+  <copyright>
+    Copyright © 2022 Vaxry
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice, this
+       list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright notice,
+       this list of conditions and the following disclaimer in the documentation
+       and/or other materials provided with the distribution.
+
+    3. Neither the name of the copyright holder nor the names of its
+       contributors may be used to endorse or promote products derived from
+       this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+  </copyright>
+
+  <description summary="registering global shortcuts">
+    This protocol allows a client to register triggerable actions,
+    meant to be global shortcuts.
+  </description>
+
+  <interface name="hyprland_global_shortcuts_manager_v1" version="1">
+    <description summary="manager to register global shortcuts">
+      This object is a manager which offers requests to create global shortcuts.
+    </description>
+
+    <request name="register_shortcut">
+      <description summary="register a shortcut">
+        Register a new global shortcut.
+
+        A global shortcut is anonymous, meaning the app does not know what key(s) trigger it.
+
+        The shortcut's keybinding shall be dealt with by the compositor.
+
+        In the case of a duplicate app_id + id combination, the already_taken protocol error is raised.
+      </description>
+      <arg name="shortcut" type="new_id" interface="hyprland_global_shortcut_v1"/>
+      <arg name="id" type="string" summary="a unique id for the shortcut"/>
+      <arg name="app_id" type="string" summary="the app_id of the application requesting the shortcut"/>
+      <arg name="description" type="string" summary="user-readable text describing what the shortcut does."/>
+      <arg name="trigger_description" type="string" summary="user-readable text describing how to trigger the shortcut for the client to render."/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager">
+        All objects created by the manager will still remain valid, until their
+        appropriate destroy request has been called.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="already_taken" value="0"
+        summary="the app_id + id combination has already been registered."/>
+    </enum>
+  </interface>
+
+  <interface name="hyprland_global_shortcut_v1" version="1">
+    <description summary="a shortcut">
+      This object represents a single shortcut.
+    </description>
+
+    <event name="pressed">
+      <description summary="keystroke pressed">
+        The keystroke was pressed.
+
+        tv_ values hold the timestamp of the occurrence.
+      </description>
+      <arg name="tv_sec_hi" type="uint"
+           summary="high 32 bits of the seconds part of the timestamp"/>
+      <arg name="tv_sec_lo" type="uint"
+           summary="low 32 bits of the seconds part of the timestamp"/>
+      <arg name="tv_nsec" type="uint"
+           summary="nanoseconds part of the timestamp"/>
+    </event>
+
+    <event name="released">
+      <description summary="keystroke released">
+        The keystroke was released.
+
+        tv_ values hold the timestamp of the occurrence.
+      </description>
+      <arg name="tv_sec_hi" type="uint"
+           summary="high 32 bits of the seconds part of the timestamp"/>
+      <arg name="tv_sec_lo" type="uint"
+           summary="low 32 bits of the seconds part of the timestamp"/>
+      <arg name="tv_nsec" type="uint"
+           summary="nanoseconds part of the timestamp"/>
+    </event>
+
+    <request name="destroy" type="destructor">
+      <description summary="delete this object, used or not">
+        Destroys the shortcut. Can be sent at any time by the client.
+      </description>
+    </request>
+  </interface>
+</protocol>