[gtk] docs: Expand opacity docs

[Matthias Clasen <matthiasc src gnome org>]

commit 34625142f4d81a48f1d3ccf246b761d202b3bfbc
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Oct 15 22:39:01 2020 -0400

    docs: Expand opacity docs
    
    Explain the situation with popovers and opacity.
    
    Fixes: #3246

 gtk/gtkwidget.c | 34 ++++++++++++++++++++++------------
 1 file changed, 22 insertions(+), 12 deletions(-)
---
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index a1c3a069b7..5b5729dfdf 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -9660,18 +9660,28 @@ gtk_widget_get_allocated_baseline (GtkWidget *widget)
  * @widget: a #GtkWidget
  * @opacity: desired opacity, between 0 and 1
  *
- * Request the @widget to be rendered partially transparent,
- * with opacity 0 being fully transparent and 1 fully opaque. (Opacity values
- * are clamped to the [0,1] range.).
- * This works on both toplevel widget, and child widgets, although there
- * are some limitations:
- *
- * For toplevel widgets this depends on the capabilities of the windowing
- * system. On X11 this has any effect only on X displays with a compositing manager
- * running. See gdk_display_is_composited(). On Windows it should work
- * always, although setting a window’s opacity after the window has been
- * shown causes it to flicker once on Windows.
- **/
+ * Request the @widget to be rendered partially transparent, with
+ * opacity 0 being fully transparent and 1 fully opaque. (Opacity
+ * values are clamped to the [0,1] range).
+ *
+ * Opacity works on both toplevel widgets and child widgets, although
+ * there are some limitations: For toplevel widgets, applying opacity
+ * depends on the capabilities of the windowing system. On X11, this
+ * has any effect only on X displays with a compositing manager,
+ * see gdk_display_is_composited(). On Windows and Wayland it should
+ * always work, although setting a window’s opacity after the window
+ * has been shown may cause some flicker.
+ *
+ * Note that the opacity is inherited through inclusion — if you set
+ * a toplevel to be partially translucent, all of its content will
+ * appear translucent, since it is ultimatively rendered on that
+ * toplevel. The opacity value itself is not inherited by child
+ * widgets (since that would make widgets deeper in the hierarchy
+ * progressively more translucent). As a consequence, #GtkPopovers
+ * and other #GtkNative widgets with their own surface will use their
+ * own opacity value, and thus by default appear non-translucent,
+ * even if they are attached to a toplevel that is translucent.
+ */
 void
 gtk_widget_set_opacity (GtkWidget *widget,
                         double     opacity)