[gtk+/wip/attachment-parameters: 2/25] gdkattachmentparameters: document GdkAttachmentParameters

[William Hua <williamhua src gnome org>]

commit 667598b4076c3c217aa97484c4df9f5df8a8d904
Author: William Hua <william hua canonical com>
Date:   Wed Oct 14 10:20:24 2015 +0100

    gdkattachmentparameters: document GdkAttachmentParameters

 docs/reference/gdk/gdk3-sections.txt |   30 +++++
 gdk/gdkattachmentparameters.c        |  233 ++++++++++++++++++++++++++++++++++
 gdk/gdkattachmentparameters.h        |   80 ++++++++++++
 gdk/gdkattachmentparametersprivate.h |   20 +++
 4 files changed, 363 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gdk/gdk3-sections.txt b/docs/reference/gdk/gdk3-sections.txt
index 8309d1d..81aebf0 100644
--- a/docs/reference/gdk/gdk3-sections.txt
+++ b/docs/reference/gdk/gdk3-sections.txt
@@ -546,6 +546,36 @@ gdk_fullscreen_mode_get_type
 </SECTION>
 
 <SECTION>
+<TITLE>Attachment Parameters</TITLE>
+<FILE>attachment_parameters</FILE>
+GdkAttachmentParameters
+GdkAttachmentOption
+GdkAttachmentBorder
+GdkAttachmentPositionCallback
+gdk_attachment_parameters_new
+gdk_attachment_parameters_copy
+gdk_attachment_parameters_free
+gdk_attachment_parameters_set_attachment_origin
+gdk_attachment_parameters_set_attachment_rectangle
+gdk_attachment_parameters_set_attachment_margin
+gdk_attachment_parameters_set_window_margin
+gdk_attachment_parameters_set_window_padding
+gdk_attachment_parameters_set_window_offset
+gdk_attachment_parameters_get_window_type_hint
+gdk_attachment_parameters_set_window_type_hint
+gdk_attachment_parameters_set_right_to_left
+gdk_attachment_parameters_add_primary_options
+gdk_attachment_parameters_add_secondary_options
+gdk_attachment_parameters_set_position_callback
+
+<SUBSECTION Private>
+_GdkAttachmentParameters
+gdk_attachment_parameters_choose_position
+gdk_attachment_parameters_choose_position_for_window
+gdk_window_move_using_attachment_parameters
+</SECTION>
+
+<SECTION>
 <TITLE>Selections</TITLE>
 <FILE>selections</FILE>
 GDK_SELECTION_PRIMARY
diff --git a/gdk/gdkattachmentparameters.c b/gdk/gdkattachmentparameters.c
index 37fc011..597602b 100644
--- a/gdk/gdkattachmentparameters.c
+++ b/gdk/gdkattachmentparameters.c
@@ -5,12 +5,49 @@
 #include "gdkscreen.h"
 #include "gdkwindow.h"
 
+/**
+ * SECTION: attachment_parameters
+ * @section_id: attachment_parameters
+ * @title: Attachment Parameters
+ * @short_description: Describing relative window position
+ * @stability: Unstable
+ * @include: gdk/gdkattachmentparameters.h
+ *
+ * A full description of how a window should be positioned relative to an
+ * attachment rectangle.
+ *
+ * Since: 3.20
+ */
+
+/**
+ * gdk_attachment_parameters_new:
+ *
+ * Creates a new #GdkAttachmentParameters for describing the position of a
+ * #GdkWindow relative to an attachment #GdkRectangle.
+ *
+ * Returns: (transfer full): a new #GdkAttachmentParameters, to be freed with
+ *                           gdk_attachment_parameters_free()
+ *
+ * Since: 3.20
+ */
 GdkAttachmentParameters *
 gdk_attachment_parameters_new (void)
 {
   return g_new0 (GdkAttachmentParameters, 1);
 }
 
+/**
+ * gdk_attachment_parameters_copy:
+ * @src: (transfer none) (nullable): the parameters to copy
+ * @data: (transfer none) (nullable): unused
+ *
+ * Creates a deep copy of @src.
+ *
+ * Returns: (transfer full) (nullable): a deep copy of @src, to be freed with
+ *                                      gdk_attachment_parameters_free()
+ *
+ * Since: 3.20
+ */
 gpointer
 gdk_attachment_parameters_copy (gconstpointer src,
                                 gpointer      data)
@@ -31,6 +68,14 @@ gdk_attachment_parameters_copy (gconstpointer src,
   return copy;
 }
 
+/**
+ * gdk_attachment_parameters_free:
+ * @data: (transfer full) (nullable): the parameters to free
+ *
+ * Releases @data.
+ *
+ * Since: 3.20
+ */
 void
 gdk_attachment_parameters_free (gpointer data)
 {
@@ -50,6 +95,16 @@ gdk_attachment_parameters_free (gpointer data)
   g_free (parameters);
 }
 
+/**
+ * gdk_attachment_parameters_set_attachment_origin:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @origin: (transfer none) (nullable): the attachment rectangle's origin
+ *
+ * Sets the origin of the attachment rectangle's coordinate system in root
+ * coordinates.
+ *
+ * Since: 3.20
+ */
 void
 gdk_attachment_parameters_set_attachment_origin (GdkAttachmentParameters *parameters,
                                                  const GdkPoint          *origin)
@@ -61,6 +116,15 @@ gdk_attachment_parameters_set_attachment_origin (GdkAttachmentParameters *parame
   parameters->attachment_origin = origin ? *origin : zero;
 }
 
+/**
+ * gdk_attachment_parameters_set_attachment_rectangle:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @rectangle: (transfer none) (nullable): the attachment rectangle
+ *
+ * Sets the attachment rectangle the window needs to be aligned relative to.
+ *
+ * Since: 3.20
+ */
 void
 gdk_attachment_parameters_set_attachment_rectangle (GdkAttachmentParameters *parameters,
                                                     const GdkRectangle      *rectangle)
@@ -76,6 +140,15 @@ gdk_attachment_parameters_set_attachment_rectangle (GdkAttachmentParameters *par
     parameters->has_attachment_rectangle = FALSE;
 }
 
+/**
+ * gdk_attachment_parameters_set_attachment_margin:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @margin: (transfer none) (nullable): the space around the attachment rectangle
+ *
+ * Sets the amount of space to leave around the attachment rectangle.
+ *
+ * Since: 3.20
+ */
 void
 gdk_attachment_parameters_set_attachment_margin (GdkAttachmentParameters   *parameters,
                                                  const GdkAttachmentBorder *margin)
@@ -87,6 +160,15 @@ gdk_attachment_parameters_set_attachment_margin (GdkAttachmentParameters   *para
   parameters->attachment_margin = margin ? *margin : zero;
 }
 
+/**
+ * gdk_attachment_parameters_set_window_margin:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @margin: (transfer none) (nullable): the space around the window
+ *
+ * Sets the amount of space to leave around the window.
+ *
+ * Since: 3.20
+ */
 void
 gdk_attachment_parameters_set_window_margin (GdkAttachmentParameters   *parameters,
                                              const GdkAttachmentBorder *margin)
@@ -98,6 +180,15 @@ gdk_attachment_parameters_set_window_margin (GdkAttachmentParameters   *paramete
   parameters->window_margin = margin ? *margin : zero;
 }
 
+/**
+ * gdk_attachment_parameters_set_window_padding:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @padding: (transfer none) (nullable): the space between the window and its contents.
+ *
+ * Sets the amount of space between the window and its contents.
+ *
+ * Since: 3.20
+ */
 void
 gdk_attachment_parameters_set_window_padding (GdkAttachmentParameters   *parameters,
                                               const GdkAttachmentBorder *padding)
@@ -109,6 +200,15 @@ gdk_attachment_parameters_set_window_padding (GdkAttachmentParameters   *paramet
   parameters->window_padding = padding ? *padding : zero;
 }
 
+/**
+ * gdk_attachment_parameters_set_window_offset:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @offset: (transfer none) (nullable): the window displacement
+ *
+ * Sets the offset to displace the window by.
+ *
+ * Since: 3.20
+ */
 void
 gdk_attachment_parameters_set_window_offset (GdkAttachmentParameters *parameters,
                                              const GdkPoint          *offset)
@@ -120,6 +220,16 @@ gdk_attachment_parameters_set_window_offset (GdkAttachmentParameters *parameters
   parameters->window_offset = offset ? *offset : zero;
 }
 
+/**
+ * gdk_attachment_parameters_get_window_type_hint:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ *
+ * Gets the window type hint set on @parameters.
+ *
+ * Returns: the window type hint set on @parameters
+ *
+ * Since: 3.20
+ */
 GdkWindowTypeHint
 gdk_attachment_parameters_get_window_type_hint (GdkAttachmentParameters *parameters)
 {
@@ -128,6 +238,15 @@ gdk_attachment_parameters_get_window_type_hint (GdkAttachmentParameters *paramet
   return parameters->window_type_hint;
 }
 
+/**
+ * gdk_attachment_parameters_set_window_type_hint:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @window_type_hint: the window type hint
+ *
+ * Sets the window type hint.
+ *
+ * Since: 3.20
+ */
 void
 gdk_attachment_parameters_set_window_type_hint (GdkAttachmentParameters *parameters,
                                                 GdkWindowTypeHint        window_type_hint)
@@ -137,6 +256,15 @@ gdk_attachment_parameters_set_window_type_hint (GdkAttachmentParameters *paramet
   parameters->window_type_hint = window_type_hint;
 }
 
+/**
+ * gdk_attachment_parameters_set_right_to_left:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @is_right_to_left: #TRUE if the text direction is right to left
+ *
+ * Sets the window text direction.
+ *
+ * Since: 3.20
+ */
 void
 gdk_attachment_parameters_set_right_to_left (GdkAttachmentParameters *parameters,
                                              gboolean                 is_right_to_left)
@@ -157,6 +285,28 @@ add_options (GList               **list,
     *list = g_list_append (*list, GINT_TO_POINTER (option));
 }
 
+/**
+ * gdk_attachment_parameters_add_primary_options:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @first_option: first primary option
+ * @...: a %NULL-terminated list of options
+ *
+ * Appends to the list of primary positioning options to try.
+ *
+ * A typical backend will try each primary option in the order they're added.
+ * If an option can be satisfied, it will then try each secondary option until
+ * it finds a satisfiable secondary option that doesn't conflict with the
+ * primary option. If it finds a pair of satisfiable non-conflicting options,
+ * then it will place the window there. If it cannot find a pair, it proceeds
+ * to the next primary option and tries again.
+ *
+ * If %GDK_ATTACHMENT_FORCE_FIRST_OPTION or %GDK_ATTACHMENT_FORCE_LAST_OPTION
+ * is encountered, the backend will probably retry the first or most recent
+ * option respectively, ignoring its satisfiability and forcing the window
+ * on-screen.
+ *
+ * Since: 3.20
+ */
 void
 gdk_attachment_parameters_add_primary_options (GdkAttachmentParameters *parameters,
                                                GdkAttachmentOption      first_option,
@@ -173,6 +323,32 @@ gdk_attachment_parameters_add_primary_options (GdkAttachmentParameters *paramete
   va_end (args);
 }
 
+/**
+ * gdk_attachment_parameters_add_secondary_options:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @first_option: first secondary option
+ * @...: a %NULL-terminated list of options
+ *
+ * Appends to the list of secondary positioning options to try.
+ *
+ * A typical backend will try each primary option in the order they're added.
+ * If an option can be satisfied, it will then try each secondary option until
+ * it finds a satisfiable secondary option that doesn't conflict with the
+ * primary option. If it finds a pair of satisfiable non-conflicting options,
+ * then it will place the window there. If it cannot find a pair, it proceeds
+ * to the next primary option and tries again.
+ *
+ * If %GDK_ATTACHMENT_FORCE_FIRST_OPTION or %GDK_ATTACHMENT_FORCE_LAST_OPTION
+ * is encountered, the backend will probably retry the first or most recent
+ * option respectively, ignoring its satisfiability and forcing the window
+ * on-screen. If %GDK_ATTACHMENT_FORCE_FIRST_OPTION_IF_PRIMARY_FORCED or
+ * %GDK_ATTACHMENT_FORCE_LAST_OPTION_IF_PRIMARY_FORCED is encountered, the
+ * backend will probably retry it as above, but only if the current primary
+ * option is being forced. These last two flags exist for defining fallback
+ * positioning behaviour.
+ *
+ * Since: 3.20
+ */
 void
 gdk_attachment_parameters_add_secondary_options (GdkAttachmentParameters *parameters,
                                                  GdkAttachmentOption      first_option,
@@ -189,6 +365,20 @@ gdk_attachment_parameters_add_secondary_options (GdkAttachmentParameters *parame
   va_end (args);
 }
 
+/**
+ * gdk_attachment_parameters_set_position_callback:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @callback: (nullable): a function to be called when the final position of
+ *                        the window is known
+ * @user_data: (transfer full) (nullable): additional data to pass to @callback
+ * @destroy_notify: (nullable): a function to release @user_data
+ *
+ * Sets the function to be called when the final position of the window is
+ * known. Since the position might be determined asynchronously, don't assume
+ * it will be called directly from gdk_window_set_attachment_parameters().
+ *
+ * Since: 3.20
+ */
 void
 gdk_attachment_parameters_set_position_callback (GdkAttachmentParameters       *parameters,
                                                  GdkAttachmentPositionCallback  callback,
@@ -521,6 +711,25 @@ is_satisfiable (const GdkAttachmentParameters *parameters,
                  || (*axis == 1 && bounds->y <= *value && *value + height <= bounds->y + bounds->height);
 }
 
+/**
+ * gdk_attachment_parameters_choose_position:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @width: window width
+ * @height: window height
+ * @bounds: (transfer none): monitor geometry
+ * @position: (out) (optional): the best position for the window
+ * @offset: (out) (optional): the displacement needed to push the window on-screen
+ * @primary_option: (out) (optional): the best primary option
+ * @secondary_option: (out) (optional): the best secondary option
+ *
+ * Finds the best position for a window of size @width and @height on a screen
+ * with @bounds using the given @parameters.
+ *
+ * Returns: #TRUE if there is a pair of satisfiable primary and secondary
+ *          options that do not conflict with each other
+ *
+ * Since: 3.20
+ */
 gboolean
 gdk_attachment_parameters_choose_position (const GdkAttachmentParameters *parameters,
                                            gint                           width,
@@ -809,6 +1018,21 @@ gdk_attachment_parameters_choose_position (const GdkAttachmentParameters *parame
   return FALSE;
 }
 
+/**
+ * gdk_attachment_parameters_choose_position_for_window:
+ * @parameters: (transfer none): a #GdkAttachmentParameters
+ * @window: (transfer none): the #GdkWindow to find the best position for
+ * @position: (out) (optional): the best position for the window
+ * @offset: (out) (optional): the displacement needed to push the window on-screen
+ * @primary_option: (out) (optional): the best primary option
+ * @secondary_option: (out) (optional): the best secondary option
+ *
+ * Finds the best position for @window according to @parameters.
+ *
+ * Returns: #TRUE if there's a best position
+ *
+ * Since: 3.20
+ */
 gboolean
 gdk_attachment_parameters_choose_position_for_window (const GdkAttachmentParameters *parameters,
                                                       GdkWindow                     *window,
@@ -847,6 +1071,15 @@ gdk_attachment_parameters_choose_position_for_window (const GdkAttachmentParamet
                                                     secondary_option);
 }
 
+/**
+ * gdk_window_move_using_attachment_parameters:
+ * @window: (transfer none): the #GdkWindow to position
+ * @parameters: (transfer none) (nullable): a description of how to position @window
+ *
+ * Moves @window to the best position according to @parameters.
+ *
+ * Since: 3.20
+ */
 void
 gdk_window_move_using_attachment_parameters (GdkWindow                     *window,
                                              const GdkAttachmentParameters *parameters)
diff --git a/gdk/gdkattachmentparameters.h b/gdk/gdkattachmentparameters.h
index e7803d2..00c02ce 100644
--- a/gdk/gdkattachmentparameters.h
+++ b/gdk/gdkattachmentparameters.h
@@ -10,6 +10,50 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GdkAttachmentOption:
+ * @GDK_ATTACHMENT_END_OPTIONS: no more options
+ * @GDK_ATTACHMENT_UNKNOWN_OPTION: indicates that the backend doesn't know
+ *  what option was selected for GdkAttachmentPositionCallback(). Only used
+ *  for GdkAttachmentPositionCallback().
+ * @GDK_ATTACHMENT_FORCE_FIRST_OPTION: retry first option, pushing on-screen if needed
+ * @GDK_ATTACHMENT_FORCE_FIRST_OPTION_IF_PRIMARY_FORCED: retry first secondary
+ *  option if retrying a primary option, pushing on-screen if needed, should
+ *  only be used as a secondary option
+ * @GDK_ATTACHMENT_FORCE_LAST_OPTION: retry recent option, pushing on-screen if needed
+ * @GDK_ATTACHMENT_FORCE_LAST_OPTION_IF_PRIMARY_FORCED: retry recent secondary
+ *  option if retrying a primary option, pushing on-screen if needed, should
+ *  only be used as a secondary option
+ * @GDK_ATTACHMENT_ATTACH_TOP_EDGE: attach to top edge of attachment rectangle
+ * @GDK_ATTACHMENT_ATTACH_LEFT_EDGE: attach to left edge of attachment rectangle
+ * @GDK_ATTACHMENT_ATTACH_RIGHT_EDGE: attach to right edge of attachment rectangle
+ * @GDK_ATTACHMENT_ATTACH_BOTTOM_EDGE: attach to bottom edge of attachment rectangle
+ * @GDK_ATTACHMENT_ATTACH_FORWARD_EDGE: attach to forward edge of attachment rectangle
+ * @GDK_ATTACHMENT_ATTACH_BACKWARD_EDGE: attach to backward edge of attachment rectangle
+ * @GDK_ATTACHMENT_ALIGN_TOP_EDGES: align top edges of attachment rectangle and window
+ * @GDK_ATTACHMENT_ALIGN_LEFT_EDGES: align left edges of attachment rectangle and window
+ * @GDK_ATTACHMENT_ALIGN_RIGHT_EDGES: align right edges of attachment rectangle and window
+ * @GDK_ATTACHMENT_ALIGN_BOTTOM_EDGES: align bottom edges of attachment rectangle and window
+ * @GDK_ATTACHMENT_ALIGN_FORWARD_EDGES: align forward edges of attachment rectangle and window
+ * @GDK_ATTACHMENT_ALIGN_BACKWARD_EDGES: align backward edges of attachment rectangle and window
+ * @GDK_ATTACHMENT_CENTER_HORIZONTALLY: center window horizontally on attachment rectangle
+ * @GDK_ATTACHMENT_CENTER_VERTICALLY: center window vertically on attachment rectangle
+ * @GDK_ATTACHMENT_CENTER_ON_TOP_EDGE: center window on top edge of attachment rectangle
+ * @GDK_ATTACHMENT_CENTER_ON_LEFT_EDGE: center window on left edge of attachment rectangle
+ * @GDK_ATTACHMENT_CENTER_ON_RIGHT_EDGE: center window on right edge of attachment rectangle
+ * @GDK_ATTACHMENT_CENTER_ON_BOTTOM_EDGE: center window on bottom edge of attachment rectangle
+ * @GDK_ATTACHMENT_CENTER_ON_FORWARD_EDGE: center window on forward edge of attachment rectangle
+ * @GDK_ATTACHMENT_CENTER_ON_BACKWARD_EDGE: center window on backward edge of attachment rectangle
+ * @GDK_ATTACHMENT_ATTACH_ABOVE_CENTER: align bottom edge of window with center of attachment rectangle
+ * @GDK_ATTACHMENT_ATTACH_BELOW_CENTER: align top edge of window with center of attachment rectangle
+ * @GDK_ATTACHMENT_ATTACH_LEFT_OF_CENTER: align right edge of window with center of attachment rectangle
+ * @GDK_ATTACHMENT_ATTACH_RIGHT_OF_CENTER: align left edge of window with center of attachment rectangle
+ * @GDK_ATTACHMENT_ATTACH_FORWARD_OF_CENTER: align backward edge of window with center of attachment 
rectangle
+ * @GDK_ATTACHMENT_ATTACH_BACKWARD_OF_CENTER: align forward edge of window with center of attachment 
rectangle
+ *
+ * Constraints on the position of the window relative to its attachment
+ * rectangle.
+ */
 enum _GdkAttachmentOption
 {
   GDK_ATTACHMENT_END_OPTIONS = 0,
@@ -48,6 +92,15 @@ enum _GdkAttachmentOption
 
 typedef enum _GdkAttachmentOption GdkAttachmentOption;
 
+/**
+ * GdkAttachmentBorder:
+ * @top: space above
+ * @left: space to the left
+ * @right: space to the right
+ * @bottom: space below
+ *
+ * The space around the perimeter of an attachment rectangle.
+ */
 struct _GdkAttachmentBorder
 {
   gint top;
@@ -57,7 +110,34 @@ struct _GdkAttachmentBorder
 };
 
 typedef struct _GdkAttachmentBorder GdkAttachmentBorder;
+
+/**
+ * GdkAttachmentParameters:
+ *
+ * Opaque type containing the information needed to position a window relative
+ * to an attachment rectangle.
+ */
 typedef struct _GdkAttachmentParameters GdkAttachmentParameters;
+
+/**
+ * GdkAttachmentPositionCallback:
+ * @window: (transfer none): the #GdkWindow that was moved
+ * @parameters: (transfer none): the #GdkAttachmentParameters that was used
+ * @position: (transfer none) (nullable): the chosen position of @window
+ * @offset: (transfer none) (nullable): the displacement applied to keep
+ *                                      @window on-screen
+ * @primary_option: the primary option that was used for positioning. If
+ *                  unknown, this will be #GDK_ATTACHMENT_UNKNOWN_OPTION
+ * @secondary_option: the secondary option that was used for positioning. If
+ *                    unknown, this will be #GDK_ATTACHMENT_UNKNOWN_OPTION
+ * @user_data: (transfer none) (nullable): the user data that was set on
+ *                                         @parameters
+ *
+ * A function that can be used to receive information about the final position
+ * of a window after gdk_window_set_attachment_parameters() is called. Since
+ * the position might be determined asynchronously, don't assume it will be
+ * called directly from gdk_window_set_attachment_parameters().
+ */
 typedef void (*GdkAttachmentPositionCallback) (GdkWindow                     *window,
                                                const GdkAttachmentParameters *parameters,
                                                const GdkPoint                *position,
diff --git a/gdk/gdkattachmentparametersprivate.h b/gdk/gdkattachmentparametersprivate.h
index ce1ccb3..35498f0 100644
--- a/gdk/gdkattachmentparametersprivate.h
+++ b/gdk/gdkattachmentparametersprivate.h
@@ -5,6 +5,26 @@
 
 G_BEGIN_DECLS
 
+/**
+ * _GdkAttachmentParameters:
+ * @attachment_origin: root origin of @attachment_rectangle coordinate system
+ * @has_attachment_rectangle: #TRUE if @attachment_rectangle is valid
+ * @attachment_rectangle: the attachment rectangle to attach the window to
+ * @attachment_margin: the space to leave around @attachment_rectangle
+ * @window_margin: the space to leave around the window
+ * @window_padding: the space between the window and its contents
+ * @window_offset: the offset to displace the window by
+ * @window_type_hint: the window type hint
+ * @is_right_to_left: #TRUE if the text direction is right to left
+ * @primary_options: a #GList of primary #GdkAttachmentOptions
+ * @secondary_options: a #GList of secondary #GdkAttachmentOptions
+ * @position_callback: a function to call when the final position is known
+ * @position_callback_user_data: additional data to pass to @position_callback
+ * @position_callback_destroy_notify: a function to free @position_callback_user_data
+ *
+ * Opaque type containing the information needed to position a window relative
+ * to an attachment rectangle.
+ */
 struct _GdkAttachmentParameters
 {
   GdkPoint attachment_origin;