From ddaab5a69cd6b579b9f6bd8f8de260edbca8df69 Mon Sep 17 00:00:00 2001
From: vaxerski <43317083+vaxerski@users.noreply.github.com>
Date: Wed, 21 Dec 2022 21:09:44 +0000
Subject: [PATCH] first draft of the protocol

---
 protocols/hyprland-global-shortcuts-v1.xml | 98 ++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 protocols/hyprland-global-shortcuts-v1.xml

diff --git a/protocols/hyprland-global-shortcuts-v1.xml b/protocols/hyprland-global-shortcuts-v1.xml
new file mode 100644
index 0000000..18291e2
--- /dev/null
+++ b/protocols/hyprland-global-shortcuts-v1.xml
@@ -0,0 +1,98 @@
+<?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 keystrokes that will be passed
+    to it regardless of its focus state.
+  </description>
+
+  <interface name="hyprland_global_shortcuts_manager_v1">
+    <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 keystroke is composed in a format of:
+        [MOD...+]KEY
+
+        for example:
+        SUPER+A or ALT+SHIFT+K
+
+        A keystroke is not required to have a MOD, although compositors might implement
+        security measures and reject such keybinds.
+      </description>
+      <arg name="shortcut" type="new_id" interface="hyprland_global_shortcut_v1"/>
+      <arg name="keystroke" type="string" summary="the keystroke"/>
+    </request>
+  </interface>
+
+  <interface name="hyprland_global_shortcut_v1">
+    <description summary="a shortcut">
+      This object represents a single shortcut.
+    </description>
+
+    <event name="status">
+      <description summary="keystroke status">
+        This is the first event sent by the compositor to indicate the status of this
+        global shortcut.
+
+        It will also be fired again shall the status of this shortcut change in the future.
+
+        If the status is not "ok", this hyprland_global_shortcut_v1 will not emit any
+        events other than a possible another status event if the status is changed.
+        <arg name="status" type="shortcut_status"/>
+      </description>
+    </event>
+
+    <event name="pressed">
+      <description summary="keystroke pressed">
+        The keystroke was pressed.
+      </description>
+    </event>
+
+    <event name="released">
+      <description summary="keystroke released">
+        The keystroke was released.
+      </description>
+    </event>
+  </interface>
+
+  <enum name="shortcut_status">
+    <entry name="ok" value="0" summary="This shortcut has been acknowledged and accepted by the compositor."/>
+    <entry name="rejected_policy" value="1" summary="The shortcut has been rejected by the compositor due to it violating the compositor's security policy."/>
+    <entry name="rejected_invalid" value="2" summary="The shortcut has been rejected by the compositor due to an error in parsing the keystroke string."/>
+    <entry name="rejected_other" value="3" summary="The shortcut has been rejected by the compositor due to an unspecified error."/>
+  </enum>
+</protocol>