Add session lock docs

doc/gtk4-layer-shell-docs.sgml

@@ -70,6 +70,7 @@
       </para>
     </partintro>
     <xi:include href="xml/gtk4-layer-shell.xml"/>
+    <xi:include href="xml/gtk4-session-lock.xml"/>
   </part>
 
   <index id="api-index-full">

doc/meson.build

@@ -9,6 +9,7 @@ gnome.gtkdoc(
     main_xml: 'gtk4-layer-shell-docs.sgml',
     src_dir: [
         join_paths(meson.source_root(), 'include'),
+        join_paths(meson.source_root(), 'src'),
         join_paths(meson.build_root(), 'include'),
     ],
     dependencies: [ gtk, wayland_client, wayland_scanner, ],

include/gtk4-session-lock.h

@@ -5,6 +5,14 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GtkSessionLockSingleton:
+ *
+ * The singleton object used to register signals relating to the lock screen's state. `locked`
+ * is fired when the screen is successfully locked, and `finished` is fired when the session is
+ * not locked (either it failed to lock or has been unlocked by the compositor). `finished` is
+ * not fired when gtk_session_lock_unlock() is called.
+ */
 G_DECLARE_FINAL_TYPE(GtkSessionLockSingleton, gtk_session_lock_singleton, GTK_SESSION_LOCK, SESSION_LOCK, GObject)
 
 /**
@@ -14,8 +22,36 @@ G_DECLARE_FINAL_TYPE(GtkSessionLockSingleton, gtk_session_lock_singleton, GTK_SE
  */
 GtkSessionLockSingleton* gtk_session_lock_get_singleton();
 
+/**
+ * gtk_session_lock_lock:
+ *
+ * Lock the screen. This should be called before assigning any windows to monitors.
+ */
 void gtk_session_lock_lock();
+
+/**
+ * gtk_session_lock_unlock:
+ *
+ * Unlock the screen. Has no effect if called when the screen is not locked.
+ */
 void gtk_session_lock_unlock();
+
+/**
+ * gtk_session_lock_is_locked:
+ *
+ * Returns if the screen is currently locked by this library in this process.
+ */
+gboolean gtk_session_lock_is_locked();
+
+/**
+ * gtk_session_lock_assign_window_to_monitor:
+ * @window: The GTK Window to use as a lock surface
+ * @monitor: The monitor to show it on
+ *
+ * This should be called with a different window once for each monitor immediately after calling
+ * gtk_session_lock_lock(). Hiding a window that is active on a monitor or not letting a window be resized by the
+ * library may result in a protocol error.
+ */
 void gtk_session_lock_assign_window_to_monitor(GtkWindow *window, GdkMonitor *monitor);
 
 G_END_DECLS

src/gtk4-session-lock.c

@@ -7,6 +7,7 @@
 
 static const char* lock_surface_key = "wayland_layer_surface";
 static GList* all_lock_surfaces = NULL;
+static gboolean is_locked = FALSE;
 
 static struct ext_session_lock_manager_v1* init_and_get_session_lock_global() {
     gtk_init();
@@ -70,6 +71,7 @@ GtkSessionLockSingleton* gtk_session_lock_get_singleton() {
 }
 
 static void session_lock_locked_callback_impl(bool locked) {
+    is_locked = locked;
     g_signal_emit(
         gtk_session_lock_get_singleton(),
         session_lock_signals[locked ? SESSION_LOCK_SIGNAL_LOCKED : SESSION_LOCK_SIGNAL_FINISHED],
@@ -78,17 +80,35 @@ static void session_lock_locked_callback_impl(bool locked) {
 }
 
 void gtk_session_lock_lock() {
+    if (is_locked) {
+        g_warning("Tried to lock multiple times without unlocking");
+        return;
+    }
     GdkDisplay* gdk_display = gdk_display_get_default();
-    g_return_if_fail(gdk_display);
-    struct wl_display* wl_display = gdk_wayland_display_get_wl_display(gdk_display);
-    g_return_if_fail(wl_display);
+    struct wl_display* wl_display = GDK_IS_WAYLAND_DISPLAY(gdk_display) ?
+        gdk_wayland_display_get_wl_display(gdk_display) :
+        NULL;
+    if (!wl_display) {
+        g_critical("Failed to get Wayland display");
+        g_signal_emit(gtk_session_lock_get_singleton(), session_lock_signals[SESSION_LOCK_SIGNAL_FINISHED], 0);
+        return;
+    }
+    if (!get_session_lock_global_from_display(wl_display)) {
+        g_critical("Session Lock protocol not supported");
+        g_signal_emit(gtk_session_lock_get_singleton(), session_lock_signals[SESSION_LOCK_SIGNAL_FINISHED], 0);
+        return;
+    }
     session_lock_lock(wl_display, session_lock_locked_callback_impl);
 }
 
 void gtk_session_lock_unlock() {
     session_lock_unlock();
 }
 
+gboolean gtk_session_lock_is_locked() {
+    return is_locked;
+}
+
 struct gtk_lock_surface_t {
     struct lock_surface_t super;
     GtkWindow* gtk_window;