[gtk+/wip/attachment-parameters-3: 131/153] gdkwindow: add gdk_window_set_attach_params ()

[William Hua <williamhua src gnome org>]

commit ebd54ce8f460902826f1e4d8a0935770dfca5886
Author: William Hua <william hua canonical com>
Date:   Fri Sep 18 16:09:20 2015 -0400

    gdkwindow: add gdk_window_set_attach_params ()

 docs/reference/gdk/gdk3-sections.txt |    1 +
 gdk/gdkattachparams.c                |    3 ++-
 gdk/gdkattachparams.h                |    4 +++-
 gdk/gdkwindow.c                      |   24 ++++++++++++++++++++++++
 gdk/gdkwindow.h                      |    5 +++++
 gdk/gdkwindowimpl.h                  |    4 ++++
 6 files changed, 39 insertions(+), 2 deletions(-)
---
diff --git a/docs/reference/gdk/gdk3-sections.txt b/docs/reference/gdk/gdk3-sections.txt
index e4e130b..ff813e7 100644
--- a/docs/reference/gdk/gdk3-sections.txt
+++ b/docs/reference/gdk/gdk3-sections.txt
@@ -491,6 +491,7 @@ GdkWMDecoration
 gdk_window_set_functions
 GdkWMFunction
 gdk_get_default_root_window
+gdk_window_set_attach_params
 
 <SUBSECTION>
 gdk_window_get_support_multidevice
diff --git a/gdk/gdkattachparams.c b/gdk/gdkattachparams.c
index 2f8811e..d41f7c2 100644
--- a/gdk/gdkattachparams.c
+++ b/gdk/gdkattachparams.c
@@ -411,7 +411,8 @@ gdk_attach_params_add_secondary_rules (GdkAttachParams *params,
  * @destroy_notify: (nullable): a function to release @user_data
  *
  * Sets the function to be called when the final position of the window is
- * known.
+ * known. Since the position might be determined asynchronously, don't assume
+ * it will be called directly from gdk_window_set_attach_params().
  *
  * Since: 3.20
  */
diff --git a/gdk/gdkattachparams.h b/gdk/gdkattachparams.h
index 4a6a394..d73101d 100644
--- a/gdk/gdkattachparams.h
+++ b/gdk/gdkattachparams.h
@@ -73,7 +73,9 @@ typedef struct _GdkAttachParams GdkAttachParams;
  *             @params
  *
  * A function that can be used to receive information about the final position
- * of a window.
+ * of a window after gdk_window_set_attach_params() is called. Since the
+ * position might be determined asynchronously, don't assume it will be called
+ * directly from gdk_window_set_attach_params().
  *
  * Since: 3.20
  */
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 9206ead..da318ba 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -11519,3 +11519,27 @@ gdk_window_show_window_menu (GdkWindow *window,
   else
     return FALSE;
 }
+
+/**
+ * gdk_window_set_attach_params:
+ * @window: a #GdkWindow
+ * @params: (nullable): information for positioning @window
+ *
+ * Moves @window to the best position according to @params. The best position
+ * is decided by the backend.
+ *
+ * Since: 3.20
+ */
+void
+gdk_window_set_attach_params (GdkWindow             *window,
+                              const GdkAttachParams *params)
+{
+  GdkWindowImplClass *impl_class;
+
+  g_return_if_fail (GDK_IS_WINDOW (window));
+
+  impl_class = GDK_WINDOW_IMPL_GET_CLASS (window->impl);
+
+  if (impl_class->set_attach_params)
+    impl_class->set_attach_params (window, params);
+}
diff --git a/gdk/gdkwindow.h b/gdk/gdkwindow.h
index 2fc934f..8d9d8c9 100644
--- a/gdk/gdkwindow.h
+++ b/gdk/gdkwindow.h
@@ -33,6 +33,7 @@
 #include <gdk/gdktypes.h>
 #include <gdk/gdkevents.h>
 #include <gdk/gdkframeclock.h>
+#include <gdk/gdkattachparams.h>
 
 G_BEGIN_DECLS
 
@@ -1075,6 +1076,10 @@ GDK_AVAILABLE_IN_3_16
 GdkGLContext * gdk_window_create_gl_context    (GdkWindow      *window,
                                                 GError        **error);
 
+GDK_AVAILABLE_IN_3_20
+void       gdk_window_set_attach_params        (GdkWindow             *window,
+                                                const GdkAttachParams *params);
+
 G_END_DECLS
 
 #endif /* __GDK_WINDOW_H__ */
diff --git a/gdk/gdkwindowimpl.h b/gdk/gdkwindowimpl.h
index 07a307c..237b9ff 100644
--- a/gdk/gdkwindowimpl.h
+++ b/gdk/gdkwindowimpl.h
@@ -27,6 +27,7 @@
 
 #include <gdk/gdkwindow.h>
 #include <gdk/gdkproperty.h>
+#include <gdk/gdkattachparams.h>
 
 G_BEGIN_DECLS
 
@@ -301,6 +302,9 @@ struct _GdkWindowImplClass
                                            GError        **error);
   void         (*invalidate_for_new_frame)(GdkWindow      *window,
                                            cairo_region_t *update_area);
+
+  void         (* set_attach_params)      (GdkWindow             *window,
+                                           const GdkAttachParams *params);
 };
 
 /* Interface Functions */