Commit ad349caa authored by Matthias Clasen's avatar Matthias Clasen

gadget: Add some documentation

parent 9c882564
......@@ -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,
......
......@@ -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,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment