Merge branch 'matthiasc/for-master' into 'master'

some docs tweaks

See merge request GNOME/gtk!3036

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 ]

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',

gdk/gdkdrawcontext.c

@@ -280,7 +280,7 @@ gdk_draw_context_get_surface (GdkDrawContext *context)
  * implementation must use gdk_draw_context_get_frame_region() to query the
  * region that must be drawn.
  *
- * When using GTK+, the widget system automatically places calls to
+ * When using GTK, the widget system automatically places calls to
  * gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the
  * use of #GskRenderers, so application code does not need to call these
  * functions explicitly.

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