forked from AuroraMiddleware/gtk
gadget: Add some documentation
This commit is contained in:
Matthias Clasen
parent
9c88256441
commit
ad349caa00
@ -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,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user