Add API for making monitor label via wayland protocol

Author: leolost2605

protocol/pantheon-desktop-shell-v1.xml

@@ -159,5 +159,14 @@
 
       <arg name="dim" type="uint" summary="1 to dim, 0 to not dim"/>
     </request>
+
+    <request name="make_monitor_label">
+      <description summary="makes the surface a monitor label for the given monitor">
+        Request to make the surface a monitor label for the given monitor. The surface will be placed
+        in the top left corner of the monitor and will be kept above other surfaces.
+      </description>
+
+      <arg name="monitor_index" type="int" summary="the index of the monitor this surface should label"/>
+    </request>
   </interface>
 </protocol>

protocol/pantheon-desktop-shell.vapi

@@ -62,6 +62,7 @@ namespace Pantheon.Desktop {
         public MakeCentered make_centered;
         public Focus focus;
         public MakeModal make_modal;
+        public MakeMonitorLabel make_monitor_label;
     }
 
     [CCode (has_target = false, has_typedef = false)]
@@ -91,5 +92,7 @@ namespace Pantheon.Desktop {
     [CCode (has_target = false, has_typedef = false)]
     public delegate void MakeModal (Wl.Client client, Wl.Resource resource, uint dim);
     [CCode (has_target = false, has_typedef = false)]
+    public delegate void MakeMonitorLabel (Wl.Client client, Wl.Resource resource, int monitor_index);
+    [CCode (has_target = false, has_typedef = false)]
     public delegate void Destroy (Wl.Client client, Wl.Resource resource);
 }

src/PantheonShell.vala

@@ -54,6 +54,7 @@ namespace Gala {
             make_centered,
             focus_extended_behavior,
             make_modal,
+            make_monitor_label,
         };
 
         PanelSurface.quark = GLib.Quark.from_string ("-gala-wayland-panel-surface-data");
@@ -392,6 +393,21 @@ namespace Gala {
         ShellClientsManager.get_instance ().make_modal (window, dim == 1);
     }
 
+    internal static void make_monitor_label (Wl.Client client, Wl.Resource resource, int monitor_index) {
+        unowned ExtendedBehaviorSurface? eb_surface = resource.get_user_data<ExtendedBehaviorSurface> ();
+        if (eb_surface.wayland_surface == null) {
+            return;
+        }
+
+        Meta.Window? window;
+        eb_surface.wayland_surface.get ("window", out window, null);
+        if (window == null) {
+            return;
+        }
+
+        ShellClientsManager.get_instance ().make_monitor_label (window, monitor_index);
+    }
+
     internal static void destroy_panel_surface (Wl.Client client, Wl.Resource resource) {
         resource.destroy ();
     }

src/ShellClients/MonitorLabelWindow.vala

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2025 elementary, Inc. (https://elementary.io)
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * Authored by: Leonhard Kargl <leo.kargl@proton.me>
+ */
+
+public class Gala.MonitorLabelWindow : PositionedWindow {
+    private const int MARGIN = 24;
+
+    public int monitor_index { get; construct; }
+
+    public MonitorLabelWindow (Meta.Window window, int monitor_index) {
+        Object (window: window, monitor_index: monitor_index);
+    }
+
+    protected override void get_window_position (Mtk.Rectangle window_rect, out int x, out int y) {
+        var monitor_rect = window.display.get_monitor_geometry (monitor_index);
+
+        x = monitor_rect.x + MARGIN;
+        y = monitor_rect.y + MARGIN;
+    }
+}

src/ShellClients/ShellClientsManager.vala

@@ -29,6 +29,7 @@ public class Gala.ShellClientsManager : Object, GestureTarget {
 
     private GLib.HashTable<Meta.Window, PanelWindow> panel_windows = new GLib.HashTable<Meta.Window, PanelWindow> (null, null);
     private GLib.HashTable<Meta.Window, ExtendedBehaviorWindow> positioned_windows = new GLib.HashTable<Meta.Window, ExtendedBehaviorWindow> (null, null);
+    private GLib.HashTable<Meta.Window, MonitorLabelWindow> monitor_label_windows = new GLib.HashTable<Meta.Window, MonitorLabelWindow> (null, null);
 
     private ShellClientsManager (WindowManager wm) {
         Object (wm: wm);
@@ -244,6 +245,18 @@ public class Gala.ShellClientsManager : Object, GestureTarget {
         positioned_windows[window].make_modal (dim);
     }
 
+    public void make_monitor_label (Meta.Window window, int monitor_index) requires (!is_itself_shell_window (window)) {
+        if (monitor_index < 0 || monitor_index > wm.get_display ().get_n_monitors ()) {
+            warning ("Invalid monitor index provided: %d", monitor_index);
+            return;
+        }
+
+        monitor_label_windows[window] = new MonitorLabelWindow (window, monitor_index);
+
+        // connect_after so we make sure that any queued move is unqueued
+        window.unmanaging.connect_after ((_window) => monitor_label_windows.remove (_window));
+    }
+
     public void propagate (UpdateType update_type, GestureAction action, double progress) {
         foreach (var window in positioned_windows.get_values ()) {
             window.propagate (update_type, action, progress);
@@ -258,6 +271,7 @@ public class Gala.ShellClientsManager : Object, GestureTarget {
         return (
             (window in positioned_windows && positioned_windows[window].modal) ||
             (window in panel_windows) ||
+            (window in monitor_label_windows) ||
             NotificationStack.is_notification (window)
         );
     }
@@ -387,6 +401,15 @@ public class Gala.ShellClientsManager : Object, GestureTarget {
                     set_restore_previous_x11_region (window);
                     break;
 
+                case "monitor-label":
+                    int parsed;
+                    if (int.try_parse (val, out parsed)) {
+                        make_monitor_label (window, parsed);
+                    } else {
+                        warning ("Failed to parse %s as monitor label", val);
+                    }
+                    break;
+
                 default:
                     break;
             }

src/meson.build

@@ -46,6 +46,7 @@ gala_bin_sources = files(
     'ShellClients/ExtendedBehaviorWindow.vala',
     'ShellClients/HideTracker.vala',
     'ShellClients/ManagedClient.vala',
+    'ShellClients/MonitorLabelWindow.vala',
     'ShellClients/NotificationsClient.vala',
     'ShellClients/PanelWindow.vala',
     'ShellClients/PositionedWindow.vala',