From d296d0760c186e540438174843f3e93849cc4d70 Mon Sep 17 00:00:00 2001
From: Drew DeVault <sir@cmpwn.com>
Date: Thu, 26 Apr 2018 14:23:10 +0200
Subject: xdg-output: Add name and description events
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This adds two events to the protocol. The goal is to allow clients to
give the user the ability to select outputs with the same names the
compositor uses and to identify outputs consistently across sessions.
The output name is a short and stiff identifier with strict limits on
permitted characters, which is suitable for storing in config files,
command line arguments, etc. A warmer "description" event is also
provided to (optionally) provide a more human readable name, and has
much broader restrictions on its form.

Signed-off-by: Drew DeVault <sir@cmpwn.com>
Reviewed-by: Simon Ser <contact@emersion.fr>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
[Jonas: Fixed formatting and commit subject]
Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
---
 unstable/xdg-output/xdg-output-unstable-v1.xml | 49 ++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 2 deletions(-)

(limited to 'unstable')

diff --git a/unstable/xdg-output/xdg-output-unstable-v1.xml b/unstable/xdg-output/xdg-output-unstable-v1.xml
index 0c0c481..bd9a8a8 100644
--- a/unstable/xdg-output/xdg-output-unstable-v1.xml
+++ b/unstable/xdg-output/xdg-output-unstable-v1.xml
@@ -54,7 +54,7 @@
     reset.
   </description>
 
-  <interface name="zxdg_output_manager_v1" version="1">
+  <interface name="zxdg_output_manager_v1" version="2">
     <description summary="manage xdg_output objects">
       A global factory interface for xdg_output objects.
     </description>
@@ -77,7 +77,7 @@
     </request>
   </interface>
 
-  <interface name="zxdg_output_v1" version="1">
+  <interface name="zxdg_output_v1" version="2">
     <description summary="compositor logical output region">
       An xdg_output describes part of the compositor geometry.
 
@@ -157,5 +157,50 @@
       </description>
     </event>
 
+    <!-- Version 2 additions -->
+
+    <event name="name" since="2">
+      <description summary="name of this output">
+	Many compositors will assign names to their outputs, show them to the
+	user, allow them to be configured by name, etc. The client may wish to
+	know this name as well to offer the user similar behaviors.
+
+	The naming convention is compositor defined, but limited to
+	alphanumeric characters and dashes (-). Each name is unique among all
+	wl_output globals, but if a wl_output global is destroyed the same name
+	may be reused later. The names will also remain consistent across
+	sessions with the same hardware and software configuration.
+
+	Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do
+	not assume that the name is a reflection of an underlying DRM
+	connector, X11 connection, etc.
+
+	The name event is sent after creating an xdg_output (see
+	xdg_output_manager.get_xdg_output). This event is only sent once per
+	xdg_output, and the name does not change over the lifetime of the
+	wl_output global.
+      </description>
+      <arg name="name" type="string" summary="output name"/>
+    </event>
+
+    <event name="description" since="2">
+      <description summary="human-readable description of this output">
+	Many compositors can produce human-readable descriptions of their
+	outputs.  The client may wish to know this description as well, to
+	communicate the user for various purposes.
+
+	The description is a UTF-8 string with no convention defined for its
+	contents. Examples might include 'Foocorp 11" Display' or 'Virtual X11
+	output via :1'.
+
+	The description event is sent after creating an xdg_output (see
+	xdg_output_manager.get_xdg_output). This event is only sent once per
+	xdg_output, and the description does not change over the lifetime of
+	the wl_output global. The description is optional, and may not be sent
+	at all.
+      </description>
+      <arg name="description" type="string" summary="output description"/>
+    </event>
+
   </interface>
 </protocol>
-- 
cgit v1.2.3