From 609aae684f590d3c768417e206f4f5ad005fbe4f Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Sat, 24 Apr 2010 17:19:25 -0400
Subject: [PATCH] Export functions to iterate over window transients

https://bugzilla.gnome.org/show_bug.cgi?id=616050
---
 src/core/window-private.h |  9 ---------
 src/core/window.c         | 31 ++++++++++++++++++++++++++-----
 src/include/window.h      | 11 +++++++++++
 3 files changed, 37 insertions(+), 14 deletions(-)

diff --git a/src/core/window-private.h b/src/core/window-private.h
index 0c22675cb..986a33e62 100644
--- a/src/core/window-private.h
+++ b/src/core/window-private.h
@@ -46,9 +46,6 @@
 
 typedef struct _MetaWindowQueue MetaWindowQueue;
 
-typedef gboolean (*MetaWindowForeachFunc) (MetaWindow *window,
-                                           void       *data);
-
 typedef enum {
   META_CLIENT_TYPE_UNKNOWN = 0,
   META_CLIENT_TYPE_APPLICATION = 1,
@@ -580,12 +577,6 @@ void meta_window_refresh_resize_popup (MetaWindow *window);
 
 void meta_window_free_delete_dialog (MetaWindow *window);
 
-void     meta_window_foreach_transient        (MetaWindow            *window,
-                                               MetaWindowForeachFunc  func,
-                                               void                  *data);
-void     meta_window_foreach_ancestor         (MetaWindow            *window,
-                                               MetaWindowForeachFunc  func,
-                                               void                  *data);
 
 void meta_window_begin_grab_op (MetaWindow *window,
                                 MetaGrabOp  op,
diff --git a/src/core/window.c b/src/core/window.c
index 3c544332f..217aca9fb 100644
--- a/src/core/window.c
+++ b/src/core/window.c
@@ -8247,10 +8247,22 @@ meta_window_refresh_resize_popup (MetaWindow *window)
     }
 }
 
+/**
+ * meta_window_foreach_transient:
+ * @window: a #MetaWindow
+ * @func: (scope call): Called for each window which is a transient of @window (transitively)
+ * @user_data: (closure): User data
+ *
+ * Call @func for every window which is either transient for @window, or is
+ * a transient of a window which is in turn transient for @window.
+ * The order of window enumeration is not defined.
+ *
+ * Iteration will stop if @func at any point returns %FALSE.
+ */
 void
 meta_window_foreach_transient (MetaWindow            *window,
                                MetaWindowForeachFunc  func,
-                               void                  *data)
+                               void                  *user_data)
 {
   GSList *windows;
   GSList *tmp;
@@ -8264,7 +8276,7 @@ meta_window_foreach_transient (MetaWindow            *window,
 
       if (meta_window_is_ancestor_of_transient (window, transient))
         {
-          if (!(* func) (transient, data))
+          if (!(* func) (transient, user_data))
             break;
         }
 
@@ -8274,10 +8286,19 @@ meta_window_foreach_transient (MetaWindow            *window,
   g_slist_free (windows);
 }
 
+/**
+ * meta_window_foreach_ancestor:
+ * @window: a #MetaWindow
+ * @func: (scope call): Called for each window which is a transient parent of @window
+ * @user_data: (closure): User data
+ *
+ * If @window is transient, call @func with the window for which it's transient,
+ * repeatedly until either we find a non-transient window, or @func returns %FALSE.
+ */
 void
 meta_window_foreach_ancestor (MetaWindow            *window,
                               MetaWindowForeachFunc  func,
-                              void                  *data)
+                              void                  *user_data)
 {
   MetaWindow *w;
   MetaWindow *tortoise;
@@ -8295,7 +8316,7 @@ meta_window_foreach_ancestor (MetaWindow            *window,
       if (w == NULL || w == tortoise)
         break;
 
-      if (!(* func) (w, data))
+      if (!(* func) (w, user_data))
         break;
 
       if (w->xtransient_for == None ||
@@ -8307,7 +8328,7 @@ meta_window_foreach_ancestor (MetaWindow            *window,
       if (w == NULL || w == tortoise)
         break;
 
-      if (!(* func) (w, data))
+      if (!(* func) (w, user_data))
         break;
 
       tortoise = meta_display_lookup_x_window (tortoise->display,
diff --git a/src/include/window.h b/src/include/window.h
index f869c284b..2f3cd14b3 100644
--- a/src/include/window.h
+++ b/src/include/window.h
@@ -108,6 +108,17 @@ MetaStackLayer meta_window_get_layer (MetaWindow *window);
 MetaWindow* meta_window_find_root_ancestor    (MetaWindow *window);
 gboolean meta_window_is_ancestor_of_transient (MetaWindow            *window,
                                                MetaWindow            *transient);
+
+typedef gboolean (*MetaWindowForeachFunc) (MetaWindow *window,
+                                           void       *data);
+
+void     meta_window_foreach_transient        (MetaWindow            *window,
+                                               MetaWindowForeachFunc  func,
+                                               void                  *user_data);
+void     meta_window_foreach_ancestor         (MetaWindow            *window,
+                                               MetaWindowForeachFunc  func,
+                                               void                  *user_data);
+
 gboolean meta_window_is_mapped (MetaWindow  *window);
 gboolean meta_window_toplevel_is_mapped (MetaWindow  *window);
 gboolean meta_window_get_icon_geometry (MetaWindow    *window,