[gtk/matthiasc/for-master: 16/17] docs: Flesh out Popup layout docs

[Matthias Clasen <matthiasc src gnome org>]

commit 9595d440cf6c6d4fe010e71aabe888d4ff1fbd86
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Jan 5 08:20:36 2021 -0500

    docs: Flesh out Popup layout docs
    
    We have nice illustrations for this, lets use them.

 .../{gtk => gdk}/images/popup-anchors.png          | Bin
 docs/reference/{gtk => gdk}/images/popup-flip.png  | Bin
 docs/reference/{gtk => gdk}/images/popup-slide.png | Bin
 docs/reference/gdk/meson.build                     |   3 +++
 docs/reference/{gtk/images => gdk}/popup-at.svg    |   0
 docs/reference/gtk/meson.build                     |   4 ----
 gdk/gdkpopuplayout.c                               |  26 +++++++++++++++++++++
 7 files changed, 29 insertions(+), 4 deletions(-)
---
diff --git a/docs/reference/gtk/images/popup-anchors.png b/docs/reference/gdk/images/popup-anchors.png
similarity index 100%
rename from docs/reference/gtk/images/popup-anchors.png
rename to docs/reference/gdk/images/popup-anchors.png
diff --git a/docs/reference/gtk/images/popup-flip.png b/docs/reference/gdk/images/popup-flip.png
similarity index 100%
rename from docs/reference/gtk/images/popup-flip.png
rename to docs/reference/gdk/images/popup-flip.png
diff --git a/docs/reference/gtk/images/popup-slide.png b/docs/reference/gdk/images/popup-slide.png
similarity index 100%
rename from docs/reference/gtk/images/popup-slide.png
rename to docs/reference/gdk/images/popup-slide.png
diff --git a/docs/reference/gdk/meson.build b/docs/reference/gdk/meson.build
index c895131a3d..cdd018def9 100644
--- a/docs/reference/gdk/meson.build
+++ b/docs/reference/gdk/meson.build
@@ -146,6 +146,9 @@ images = [
   'images/nwse_resize_cursor.png',
   'images/zoom_in_cursor.png',
   'images/zoom_out_cursor.png',
+  'images/popup-anchors.png',
+  'images/popup-flip.png',
+  'images/popup-slide.png',
 ]
 
 src_dir = [ gdkinc ]
diff --git a/docs/reference/gtk/images/popup-at.svg b/docs/reference/gdk/popup-at.svg
similarity index 100%
rename from docs/reference/gtk/images/popup-at.svg
rename to docs/reference/gdk/popup-at.svg
diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index cdd53d61e8..a2e28b586f 100644
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -413,10 +413,6 @@ images = [
   'images/password-entry.png',
   'images/picture.png',
   'images/popover.png',
-  'images/popup-anchors.png',
-  'images/popup-at.svg',
-  'images/popup-flip.png',
-  'images/popup-slide.png',
   'images/printdialog.png',
   'images/progressbar.png',
   'images/right-center.png',
diff --git a/gdk/gdkpopuplayout.c b/gdk/gdkpopuplayout.c
index 0542bec811..bff14a935c 100644
--- a/gdk/gdkpopuplayout.c
+++ b/gdk/gdkpopuplayout.c
@@ -30,6 +30,32 @@
  * Popups are positioned relative to their parent surface.
  * The GdkPopupLayout struct contains information that is
  * necessary to do so.
+ *
+ * The positioning requires a negotiation with the windowing system,
+ * since it depends on external constraints, such as the position of
+ * the parent surface, and the screen dimensions.
+ *
+ * The basic ingredients are a rectangle on the parent surface,
+ * and the anchor on both that rectangle and the popup. The anchors
+ * specify a side or corner to place next to each other.
+ *
+ * ![Popup anchors](popup-anchors.png)
+ *
+ * For cases where placing the anchors next to each other would make
+ * the popup extend offscreen, the layout includes some hints for how
+ * to resolve this problem. The hints may suggest to flip the anchor
+ * position to the other side, or to 'slide' the popup along a side,
+ * or to resize it.
+ *
+ * ![Flipping popups](popup-flip.png)
+ *
+ * ![Sliding popups](popup-slide.png)
+ *
+ * These hints may be combined, but it is ultimatively up to the windowing
+ * system to determine the position and size of the popup. You can learn
+ * about the result by calling gdk_popup_get_position_x(),
+ * gdk_popup_get_position_y(), gdk_popup_get_rect_anchor() and
+ * gdk_popup_get_surface_anchor() after the popup has been presented.
  */
 
 struct _GdkPopupLayout