[gtk+] gadget: Add some documentation

[Matthias Clasen <matthiasc src gnome org>]

commit ad349caa0013996c65b4263c808b0cc5437accfa
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Dec 6 14:27:40 2015 -0500

    gadget: Add some documentation

 gtk/gtkcsscustomgadget.c |  109 ++++++++++++++++++++++++++++++++++++++++++++++
 gtk/gtkcssgadget.c       |   98 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 207 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkcsscustomgadget.c b/gtk/gtkcsscustomgadget.c
index 1dcc5a3..d627a19 100644
--- a/gtk/gtkcsscustomgadget.c
+++ b/gtk/gtkcsscustomgadget.c
@@ -23,6 +23,77 @@
 
 #include "gtkcssnodeprivate.h"
 
+/*
+ * GtkCssCustomGadget is a subclass that lets widgets customize size
+ * requests, size allocation and drawing of gadgets. The gadget is passed
+ * to the callbacks as the first argument, and you can use gtk_css_gadget_get_owner()
+ * to obtain the widget. Note that the widgets style context is not saved,
+ * so if you want to query style properties or call gtk_render functions which
+ * take the style context as an argument, you should use
+ * gtk_style_context_save_to_node to make the gadget's CSS node take effect.
+ *
+ * The callbacks are
+ *
+ * GtkCssPreferredSizeFunc:
+ * @gadget: the #GtkCssCustomGadget
+ * @orientation: whether a width (ie horizontal) or height (ie vertical) is requested
+ * @for_size: the available size in the opposite direction, or -1
+ * @minimum: return location for the minimum size
+ * @natural: return location for the natural size
+ * @minimum_baseline: (nullable): return location for the baseline at minimum size
+ * @natural_baseline: (nullable): return location for the baseline at natural size
+ * @data: data provided when registering the callback
+ *
+ * The GtkCssPreferredSizeFunc is called to determine the content size in
+ * gtk_css_gadget_get_preferred_size(). @for_size is a content size (ie excluding
+ * CSS padding, border and margin) and the returned @minimum, @natural,
+ * @minimum_baseline, @natural_baseline should be content sizes excluding CSS
+ * padding, border and margin as well.
+ *
+ * Typically, GtkCssPreferredSizeFunc will query the size of sub-gadgets and
+ * child widgets that are placed relative to the gadget and determine its own
+ * needed size from the results. If the gadget has no sub-gadgets or child
+ * widgets that it needs to place, then a GtkCssPreferredSizeFunc is only
+ * needed if you want to enforce a minimum size independent of CSS min-width
+ * and min-height (e.g. if size-related style properties need to be supported
+ * for compatibility).
+ *
+ * GtkCssAllocateFunc:
+ * @gadget: the #GtkCssCustomGadget
+ * @allocation: the allocation
+ * @baseline: the baseline
+ * @out_clip: (out): return location for the content clip
+ * @data: data provided when registering the callback
+ *
+ * The GtkCssAllocateFunc is called to allocate the gadgets content in
+ * gtk_css_gadget_allocate(). @allocation and @baseline are content sizes
+ * (ie excluding CSS padding, border and margin).
+ *
+ * Typically, GtkCssAllocateFunc will allocate sub-gadgets and child widgets
+ * that are placed relative to the gadget, and merge their clips into the
+ * value returned as @out_clip. For clip handling in the main gadget of
+ * containers, gtk_container_get_children_clip() can be useful. Gadgets that
+ * don't have sub-gadgets of child widgets don't need a GtkCssAllocateFunc
+ * (although it is still required to call gtk_css_gadget_allocate() on them).
+ *
+ * GtkCssDrawFunc:
+ * @gadget: the #GtkCssCustomGadget
+ * @cr: the cairo context to draw on
+ * @x: the x origin of the content area
+ * @y: the y origin of the content area
+ * @width: the width of the content area
+ * @height: the height of the content area
+ * @data: data provided when registering the callback
+ *
+ * The GtkCssDrawFunc is called to draw the gadgets content in
+ * gtk_css_gadget_draw(). It gets passed an untransformed cairo context
+ * and the coordinates of the area to draw the content in.
+ *
+ * Typically, GtkCssDrawFunc will draw sub-gadgets and child widgets
+ * that are placed relative to the gadget, as well as custom content
+ * such as icons, checkmarks, arrows or text.
+ */
+
 typedef struct _GtkCssCustomGadgetPrivate GtkCssCustomGadgetPrivate;
 struct _GtkCssCustomGadgetPrivate {
   GtkCssPreferredSizeFunc          preferred_size_func;
@@ -117,6 +188,27 @@ gtk_css_custom_gadget_init (GtkCssCustomGadget *custom_gadget)
 
 }
 
+/**
+ * gtk_css_custom_gadget_new_for_node:
+ * @node: the #GtkCssNode to use for the gadget
+ * @owner: the widget that the gadget belongs to
+ * @preferred_size_func: (nullable): the GtkCssPreferredSizeFunc to use
+ * @allocate_func: (nullable): the GtkCssAllocateFunc to use
+ * @draw_func: (nullable): the GtkCssDrawFunc to use
+ * @data: (nullable): user data to pass to the callbacks
+ * @destroy_func: (nullable): destroy notify for @data
+ *
+ * Creates a #GtkCssCustomGadget for an existing CSS node.
+ * This function is typically used in the widgets init function
+ * to create the main gadget for the widgets main CSS node (which
+ * is obtained with gtk_widget_get_css_node()), as well as other
+ * permanent sub-gadgets. Sub-gadgets that only exist sometimes
+ * (e.g. depending on widget properties) should be created and
+ * destroyed as needed. All gadgets should be destroyed in the
+ * finalize (or dispose) vfunc.
+ *
+ * Returns: (transfer full): the new gadget
+ */
 GtkCssGadget *
 gtk_css_custom_gadget_new_for_node (GtkCssNode                 *node,
                                     GtkWidget                  *owner,
@@ -145,6 +237,23 @@ gtk_css_custom_gadget_new_for_node (GtkCssNode                 *node,
   return result;
 }
 
+/**
+ * gtk_css_custom_gadget_new:
+ * @name: the name for the CSS node
+ * @owner: the widget that the gadget belongs to
+ * @parent: the gadget that has the parent CSS node
+ * @next_sibling: the gadget that has the sibling CSS node
+ * @preferred_size_func: (nullable): the GtkCssPreferredSizeFunc to use
+ * @allocate_func: (nullable): the GtkCssAllocateFunc to use
+ * @draw_func: (nullable): the GtkCssDrawFunc to use
+ * @data: (nullable): user data to pass to the callbacks
+ * @destroy_func: (nullable): destroy notify for @data
+ *
+ * Creates a #GtkCssCustomGadget with a new CSS node which gets
+ * placed below the @parent's and before the @next_sibling's CSS node.
+ *
+ * Returns: (transfer full): the new gadget
+ */
 GtkCssGadget *
 gtk_css_custom_gadget_new (const char                 *name,
                            GtkWidget                  *owner,
diff --git a/gtk/gtkcssgadget.c b/gtk/gtkcssgadget.c
index 60bb9d2..b3bf1c6 100644
--- a/gtk/gtkcssgadget.c
+++ b/gtk/gtkcssgadget.c
@@ -31,6 +31,34 @@
 #include "gtkrenderbackgroundprivate.h"
 #include "gtkrenderborderprivate.h"
 
+/*
+ * Gadgets are 'next-generation widgets' - they combine a CSS node
+ * for style matching with geometry management and drawing. Each gadget
+ * corresponds to 'CSS box'. Compared to traditional widgets, they are more
+ * like building blocks - a typical GTK+ widget will have multiple gadgets,
+ * for example a check button has its main gadget, and sub-gadgets for
+ * the checkmark and the text.
+ *
+ * Gadgets are not themselves hierarchically organized, but it is common
+ * to have a 'main' gadget, which gets used by the widgets size_allocate,
+ * get_preferred_width, etc. and draw callbacks, and which in turn calls out
+ * to the sub-gadgets. This call tree might extend further if there are
+ * sub-sub-gadgets that a allocated relative to sub-gadgets. In typical
+ * situations, the callback chain will reflect the tree structure of the
+ * gadgets CSS nodes.
+ *
+ * Geometry management - Gadgets implement much of the CSS box model for you:
+ * margins, border, padding, shadows, min-width/height are all applied automatically.
+ *
+ * Drawing - Gadgets implement standardized CSS drawing for you: background,
+ * shadows and border are drawn before any custom drawing, and the focus outline
+ * is (optionally) drawn afterwards.
+ *
+ * Invalidation - Gadgets sit 'between' widgets and CSS nodes, and connect
+ * to the nodes ::style-changed signal and trigger appropriate invalidations
+ * on the widget side.
+ */
+
 typedef struct _GtkCssGadgetPrivate GtkCssGadgetPrivate;
 struct _GtkCssGadgetPrivate {
   GtkCssNode    *node;
@@ -261,6 +289,14 @@ gtk_css_gadget_init (GtkCssGadget *gadget)
 
 }
 
+/**
+ * gtk_css_gadget_get_node:
+ * @gadget: a #GtkCssGadget
+ *
+ * Get the CSS node for this gadget.
+ *
+  * Returns: (transfer none):  the CSS node
+ */
 GtkCssNode *
 gtk_css_gadget_get_node (GtkCssGadget *gadget)
 {
@@ -269,6 +305,14 @@ gtk_css_gadget_get_node (GtkCssGadget *gadget)
   return priv->node;
 }
 
+/**
+ * gtk_css_gadget_get_style:
+ * @gadget: a #GtkCssGadget
+ *
+ * Get the CSS style for this gadget.
+ *
+ * Returns: (transfer none):  the CSS style
+ */
 GtkCssStyle *
 gtk_css_gadget_get_style (GtkCssGadget *gadget)
 {
@@ -277,6 +321,14 @@ gtk_css_gadget_get_style (GtkCssGadget *gadget)
   return gtk_css_node_get_style (priv->node);
 }
 
+/**
+ * gtk_css_gadget_get_style:
+ * @gadget: a #GtkCssGadget
+ *
+ * Get the widget to which this gadget belongs.
+ *
+ * Returns: (transfer none):  the widget to which @gadget belongs
+ */
 GtkWidget *
 gtk_css_gadget_get_owner (GtkCssGadget *gadget)
 {
@@ -285,6 +337,13 @@ gtk_css_gadget_get_owner (GtkCssGadget *gadget)
   return priv->owner;
 }
 
+/**
+ * gtk_css_gadget_add_class:
+ * @gadget: a #GtkCssGadget
+ * @name: class name to use in CSS matching
+ *
+ * Adds a style class to the gadgets CSS node.
+ */
 void
 gtk_css_gadget_add_class (GtkCssGadget *gadget,
                           const char   *name)
@@ -297,6 +356,13 @@ gtk_css_gadget_add_class (GtkCssGadget *gadget,
   gtk_css_node_add_class (priv->node, quark);
 }
 
+/**
+ * gtk_css_gadget_remove_class:
+ * @gadget: a #GtkCssGadget
+ * @name: class name
+ *
+ * Removes a style class from the gadgets CSS node.
+ */
 void
 gtk_css_gadget_remove_class (GtkCssGadget *gadget,
                              const char   *name)
@@ -353,6 +419,24 @@ get_box_padding (GtkCssStyle *style,
   border->right = get_number (style, GTK_CSS_PROPERTY_PADDING_RIGHT);
 }
 
+/**
+ * gtk_css_gadget_get_preferred_size:
+ * @gadget: the #GtkCssGadget whose size is requested
+ * @orientation: whether a width (ie horizontal) or height (ie vertical) size is requested
+ * @for_size: the available size in the opposite direction, or -1
+ * @minimum: (nullable): return location for the minimum size
+ * @natural: (nullable): return location for the natural size
+ * @minimum_baseline: (nullable): return location for the baseline at minimum size
+ * @natural_baseline: (nullable): return location for the baseline at natural size
+ *
+ * Gets the gadgets minimum and natural size (and, optionally, baseline)
+ * in the given orientation for the specified size in the opposite direction.
+ *
+ * The returned values include CSS padding, border and margin in addition to the
+ * gadgets content size, and respect the CSS min-with or min-height properties.
+ *
+ * The @for_size is assumed to include CSS padding, border and margins as well.
+ */
 void
 gtk_css_gadget_get_preferred_size (GtkCssGadget   *gadget,
                                    GtkOrientation  orientation,
@@ -419,6 +503,20 @@ gtk_css_gadget_get_preferred_size (GtkCssGadget   *gadget,
     *natural_baseline += extra_baseline;
 }
 
+/**
+ * gtk_css_gadget_allocate:
+ * @gadget: the #GtkCssGadget to allocate
+ * @allocation: the allocation
+ * @baseline: the baseline for the allocation
+ * @out_clip: (out): return location for the gadgets clip region
+ *
+ * Allocates the gadget.
+ *
+ * The @allocation is assumed to include CSS padding, border and margin.
+ * The gadget content will be allocated a smaller area that excludes these.
+ * The @out_clip includes the shadow extents of the gadget in addition to
+ * any content clip.
+ */
 void
 gtk_css_gadget_allocate (GtkCssGadget        *gadget,
                          const GtkAllocation *allocation,