X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=gtk%2Fgtkcellareacontext.c;h=f464c3ab30233d59b231042cba94e8a29d969b83;hb=0ba92bc26d1b716f2f9c0543593f13cd5a92c521;hp=5a3ee8b28a518808ba0c91070858dad0b0ad7b9b;hpb=487223d480578457f924470c1a1d73eb261eefd7;p=~andy%2Fgtk diff --git a/gtk/gtkcellareacontext.c b/gtk/gtkcellareacontext.c index 5a3ee8b28..f464c3ab3 100644 --- a/gtk/gtkcellareacontext.c +++ b/gtk/gtkcellareacontext.c @@ -16,9 +16,24 @@ * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public - * License along with this library; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place - Suite 330, - * Boston, MA 02111-1307, USA. + * License along with this library. If not, see . + */ + +/** + * SECTION:gtkcellareacontext + * @Short_Description: Stores geometrical information for a series of rows in a GtkCellArea + * @Title: GtkCellAreaContext + * + * The #GtkCellAreaContext object is created by a given #GtkCellArea + * implementation via its #GtkCellAreaClass.create_context() virtual + * method and is used to store cell sizes and alignments for a series of + * #GtkTreeModel rows that are requested and rendered in the same context. + * + * #GtkCellLayout widgets can create any number of contexts in which to + * request and render groups of data rows. However, it's important that the + * same context which was used to request sizes for a given #GtkTreeModel + * row also be used for the same row when calling other #GtkCellArea APIs + * such as gtk_cell_area_render() and gtk_cell_area_event(). */ #include "config.h" @@ -28,23 +43,21 @@ #include "gtkprivate.h" /* GObjectClass */ -static void gtk_cell_area_context_dispose (GObject *object); -static void gtk_cell_area_context_get_property (GObject *object, - guint prop_id, - GValue *value, - GParamSpec *pspec); -static void gtk_cell_area_context_set_property (GObject *object, - guint prop_id, - const GValue *value, - GParamSpec *pspec); +static void gtk_cell_area_context_dispose (GObject *object); +static void gtk_cell_area_context_get_property (GObject *object, + guint prop_id, + GValue *value, + GParamSpec *pspec); +static void gtk_cell_area_context_set_property (GObject *object, + guint prop_id, + const GValue *value, + GParamSpec *pspec); /* GtkCellAreaContextClass */ -static void gtk_cell_area_context_real_flush_preferred_width (GtkCellAreaContext *context); -static void gtk_cell_area_context_real_flush_preferred_height (GtkCellAreaContext *context); -static void gtk_cell_area_context_real_flush_allocation (GtkCellAreaContext *context); -static void gtk_cell_area_context_real_allocate (GtkCellAreaContext *context, - gint width, - gint height); +static void gtk_cell_area_context_real_reset (GtkCellAreaContext *context); +static void gtk_cell_area_context_real_allocate (GtkCellAreaContext *context, + gint width, + gint height); struct _GtkCellAreaContextPrivate { @@ -72,20 +85,12 @@ G_DEFINE_TYPE (GtkCellAreaContext, gtk_cell_area_context, G_TYPE_OBJECT); static void gtk_cell_area_context_init (GtkCellAreaContext *context) { - GtkCellAreaContextPrivate *priv; - context->priv = G_TYPE_INSTANCE_GET_PRIVATE (context, - GTK_TYPE_CELL_AREA_CONTEXT, - GtkCellAreaContextPrivate); - priv = context->priv; - - priv->min_width = -1; - priv->nat_width = -1; - priv->min_height = -1; - priv->nat_height = -1; + GTK_TYPE_CELL_AREA_CONTEXT, + GtkCellAreaContextPrivate); } -static void +static void gtk_cell_area_context_class_init (GtkCellAreaContextClass *class) { GObjectClass *object_class = G_OBJECT_CLASS (class); @@ -96,60 +101,99 @@ gtk_cell_area_context_class_init (GtkCellAreaContextClass *class) object_class->set_property = gtk_cell_area_context_set_property; /* GtkCellAreaContextClass */ - class->flush_preferred_width = gtk_cell_area_context_real_flush_preferred_width; - class->flush_preferred_height = gtk_cell_area_context_real_flush_preferred_height; - class->flush_allocation = gtk_cell_area_context_real_flush_allocation; - class->sum_preferred_width = NULL; - class->sum_preferred_height = NULL; - class->allocate = gtk_cell_area_context_real_allocate; - + class->reset = gtk_cell_area_context_real_reset; + class->allocate = gtk_cell_area_context_real_allocate; + + /** + * GtkCellAreaContext:area: + * + * The #GtkCellArea this context was created by + * + * Since: 3.0 + */ g_object_class_install_property (object_class, PROP_CELL_AREA, g_param_spec_object ("area", - P_("Area"), - P_("The Cell Area this context was created for"), - GTK_TYPE_CELL_AREA, - GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY)); - + P_("Area"), + P_("The Cell Area this context was created for"), + GTK_TYPE_CELL_AREA, + GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY)); + + /** + * GtkCellAreaContext:minimum-width: + * + * The minimum width for the #GtkCellArea in this context + * for all #GtkTreeModel rows that this context was requested + * for using gtk_cell_area_get_preferred_width(). + * + * Since: 3.0 + */ g_object_class_install_property (object_class, PROP_MIN_WIDTH, g_param_spec_int ("minimum-width", - P_("Minimum Width"), - P_("Minimum cached width"), - -1, - G_MAXINT, - -1, - G_PARAM_READABLE)); - + P_("Minimum Width"), + P_("Minimum cached width"), + -1, + G_MAXINT, + -1, + G_PARAM_READABLE)); + + /** + * GtkCellAreaContext:natural-width: + * + * The natural width for the #GtkCellArea in this context + * for all #GtkTreeModel rows that this context was requested + * for using gtk_cell_area_get_preferred_width(). + * + * Since: 3.0 + */ g_object_class_install_property (object_class, PROP_NAT_WIDTH, g_param_spec_int ("natural-width", - P_("Minimum Width"), - P_("Minimum cached width"), - -1, - G_MAXINT, - -1, - G_PARAM_READABLE)); - + P_("Minimum Width"), + P_("Minimum cached width"), + -1, + G_MAXINT, + -1, + G_PARAM_READABLE)); + + /** + * GtkCellAreaContext:minimum-height: + * + * The minimum height for the #GtkCellArea in this context + * for all #GtkTreeModel rows that this context was requested + * for using gtk_cell_area_get_preferred_height(). + * + * Since: 3.0 + */ g_object_class_install_property (object_class, PROP_MIN_HEIGHT, g_param_spec_int ("minimum-height", - P_("Minimum Height"), - P_("Minimum cached height"), - -1, - G_MAXINT, - -1, - G_PARAM_READABLE)); - + P_("Minimum Height"), + P_("Minimum cached height"), + -1, + G_MAXINT, + -1, + G_PARAM_READABLE)); + + /** + * GtkCellAreaContext:natural-height: + * + * The natural height for the #GtkCellArea in this context + * for all #GtkTreeModel rows that this context was requested + * for using gtk_cell_area_get_preferred_height(). + * + * Since: 3.0 + */ g_object_class_install_property (object_class, PROP_NAT_HEIGHT, g_param_spec_int ("natural-height", - P_("Minimum Height"), - P_("Minimum cached height"), - -1, - G_MAXINT, - -1, - G_PARAM_READABLE)); + P_("Minimum Height"), + P_("Minimum cached height"), + -1, + G_MAXINT, + -1, + G_PARAM_READABLE)); g_type_class_add_private (object_class, sizeof (GtkCellAreaContextPrivate)); } @@ -175,9 +219,9 @@ gtk_cell_area_context_dispose (GObject *object) static void gtk_cell_area_context_set_property (GObject *object, - guint prop_id, - const GValue *value, - GParamSpec *pspec) + guint prop_id, + const GValue *value, + GParamSpec *pspec) { GtkCellAreaContext *context = GTK_CELL_AREA_CONTEXT (object); GtkCellAreaContextPrivate *priv = context->priv; @@ -195,9 +239,9 @@ gtk_cell_area_context_set_property (GObject *object, static void gtk_cell_area_context_get_property (GObject *object, - guint prop_id, - GValue *value, - GParamSpec *pspec) + guint prop_id, + GValue *value, + GParamSpec *pspec) { GtkCellAreaContext *context = GTK_CELL_AREA_CONTEXT (object); GtkCellAreaContextPrivate *priv = context->priv; @@ -226,49 +270,49 @@ gtk_cell_area_context_get_property (GObject *object, } /************************************************************* - * GtkCellAreaContextClass * + * GtkCellAreaContextClass * *************************************************************/ static void -gtk_cell_area_context_real_flush_preferred_width (GtkCellAreaContext *context) +gtk_cell_area_context_real_reset (GtkCellAreaContext *context) { GtkCellAreaContextPrivate *priv = context->priv; - - priv->min_width = -1; - priv->nat_width = -1; g_object_freeze_notify (G_OBJECT (context)); - g_object_notify (G_OBJECT (context), "minimum-width"); - g_object_notify (G_OBJECT (context), "natural-width"); - g_object_thaw_notify (G_OBJECT (context)); -} -static void -gtk_cell_area_context_real_flush_preferred_height (GtkCellAreaContext *context) -{ - GtkCellAreaContextPrivate *priv = context->priv; - - priv->min_height = -1; - priv->nat_height = -1; + if (priv->min_width != 0) + { + priv->min_width = 0; + g_object_notify (G_OBJECT (context), "minimum-width"); + } - g_object_freeze_notify (G_OBJECT (context)); - g_object_notify (G_OBJECT (context), "minimum-height"); - g_object_notify (G_OBJECT (context), "natural-height"); - g_object_thaw_notify (G_OBJECT (context)); -} + if (priv->nat_width != 0) + { + priv->nat_width = 0; + g_object_notify (G_OBJECT (context), "natural-width"); + } -static void -gtk_cell_area_context_real_flush_allocation (GtkCellAreaContext *context) -{ - GtkCellAreaContextPrivate *priv = context->priv; + if (priv->min_height != 0) + { + priv->min_height = 0; + g_object_notify (G_OBJECT (context), "minimum-height"); + } + + if (priv->nat_height != 0) + { + priv->nat_height = 0; + g_object_notify (G_OBJECT (context), "natural-height"); + } priv->alloc_width = 0; priv->alloc_height = 0; + + g_object_thaw_notify (G_OBJECT (context)); } static void gtk_cell_area_context_real_allocate (GtkCellAreaContext *context, - gint width, - gint height) + gint width, + gint height) { GtkCellAreaContextPrivate *priv = context->priv; @@ -279,6 +323,25 @@ gtk_cell_area_context_real_allocate (GtkCellAreaContext *context, /************************************************************* * API * *************************************************************/ +/** + * gtk_cell_area_context_get_area: + * @context: a #GtkCellAreaContext + * + * Fetches the #GtkCellArea this @context was created by. + * + * This is generally unneeded by layouting widgets; however, + * it is important for the context implementation itself to + * fetch information about the area it is being used for. + * + * For instance at #GtkCellAreaContextClass.allocate() time + * it's important to know details about any cell spacing + * that the #GtkCellArea is configured with in order to + * compute a proper allocation. + * + * Return value: (transfer none): the #GtkCellArea this context was created by. + * + * Since: 3.0 + */ GtkCellArea * gtk_cell_area_context_get_area (GtkCellAreaContext *context) { @@ -291,84 +354,94 @@ gtk_cell_area_context_get_area (GtkCellAreaContext *context) return priv->cell_area; } +/** + * gtk_cell_area_context_reset: + * @context: a #GtkCellAreaContext + * + * Resets any previously cached request and allocation + * data. + * + * When underlying #GtkTreeModel data changes its + * important to reset the context if the content + * size is allowed to shrink. If the content size + * is only allowed to grow (this is usually an option + * for views rendering large data stores as a measure + * of optimization), then only the row that changed + * or was inserted needs to be (re)requested with + * gtk_cell_area_get_preferred_width(). + * + * When the new overall size of the context requires + * that the allocated size changes (or whenever this + * allocation changes at all), the variable row + * sizes need to be re-requested for every row. + * + * For instance, if the rows are displayed all with + * the same width from top to bottom then a change + * in the allocated width necessitates a recalculation + * of all the displayed row heights using + * gtk_cell_area_get_preferred_height_for_width(). + * + * Since 3.0 + */ void -gtk_cell_area_context_flush (GtkCellAreaContext *context) -{ - g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context)); - - gtk_cell_area_context_flush_preferred_width (context); - gtk_cell_area_context_flush_preferred_height (context); - gtk_cell_area_context_flush_allocation (context); -} - -void -gtk_cell_area_context_flush_preferred_width (GtkCellAreaContext *context) -{ - g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context)); - - GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->flush_preferred_width (context); -} - -void -gtk_cell_area_context_flush_preferred_height (GtkCellAreaContext *context) -{ - g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context)); - - GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->flush_preferred_height (context); -} - -void -gtk_cell_area_context_flush_allocation (GtkCellAreaContext *context) -{ - g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context)); - - GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->flush_allocation (context); -} - -void -gtk_cell_area_context_sum_preferred_width (GtkCellAreaContext *context) +gtk_cell_area_context_reset (GtkCellAreaContext *context) { - GtkCellAreaContextClass *class; - g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context)); - class = GTK_CELL_AREA_CONTEXT_GET_CLASS (context); - - if (class->sum_preferred_width) - class->sum_preferred_width (context); -} - -void -gtk_cell_area_context_sum_preferred_height (GtkCellAreaContext *context) -{ - GtkCellAreaContextClass *class; - - g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context)); - - class = GTK_CELL_AREA_CONTEXT_GET_CLASS (context); - - if (class->sum_preferred_height) - class->sum_preferred_height (context); + GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->reset (context); } +/** + * gtk_cell_area_context_allocate: + * @context: a #GtkCellAreaContext + * @width: the allocated width for all #GtkTreeModel rows rendered + * with @context, or -1. + * @height: the allocated height for all #GtkTreeModel rows rendered + * with @context, or -1. + * + * Allocates a width and/or a height for all rows which are to be + * rendered with @context. + * + * Usually allocation is performed only horizontally or sometimes + * vertically since a group of rows are usually rendered side by + * side vertically or horizontally and share either the same width + * or the same height. Sometimes they are allocated in both horizontal + * and vertical orientations producing a homogeneous effect of the + * rows. This is generally the case for #GtkTreeView when + * #GtkTreeView:fixed-height-mode is enabled. + * + * Since 3.0 + */ void gtk_cell_area_context_allocate (GtkCellAreaContext *context, - gint width, - gint height) + gint width, + gint height) { - GtkCellAreaContextClass *class; - g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context)); - class = GTK_CELL_AREA_CONTEXT_GET_CLASS (context); - - class->allocate (context, width, height); + GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->allocate (context, width, height); } +/** + * gtk_cell_area_context_get_preferred_width: + * @context: a #GtkCellAreaContext + * @minimum_width: (out) (allow-none): location to store the minimum width, + * or %NULL + * @natural_width: (out) (allow-none): location to store the natural width, + * or %NULL + * + * Gets the accumulative preferred width for all rows which have been + * requested with this context. + * + * After gtk_cell_area_context_reset() is called and/or before ever + * requesting the size of a #GtkCellArea, the returned values are 0. + * + * Since: 3.0 + */ void gtk_cell_area_context_get_preferred_width (GtkCellAreaContext *context, - gint *minimum_width, - gint *natural_width) + gint *minimum_width, + gint *natural_width) { GtkCellAreaContextPrivate *priv; @@ -383,10 +456,26 @@ gtk_cell_area_context_get_preferred_width (GtkCellAreaContext *context, *natural_width = priv->nat_width; } +/** + * gtk_cell_area_context_get_preferred_height: + * @context: a #GtkCellAreaContext + * @minimum_height: (out) (allow-none): location to store the minimum height, + * or %NULL + * @natural_height: (out) (allow-none): location to store the natural height, + * or %NULL + * + * Gets the accumulative preferred height for all rows which have been + * requested with this context. + * + * After gtk_cell_area_context_reset() is called and/or before ever + * requesting the size of a #GtkCellArea, the returned values are 0. + * + * Since: 3.0 + */ void gtk_cell_area_context_get_preferred_height (GtkCellAreaContext *context, - gint *minimum_height, - gint *natural_height) + gint *minimum_height, + gint *natural_height) { GtkCellAreaContextPrivate *priv; @@ -401,10 +490,88 @@ gtk_cell_area_context_get_preferred_height (GtkCellAreaContext *context, *natural_height = priv->nat_height; } +/** + * gtk_cell_area_context_get_preferred_height_for_width: + * @context: a #GtkCellAreaContext + * @width: a proposed width for allocation + * @minimum_height: (out) (allow-none): location to store the minimum height, + * or %NULL + * @natural_height: (out) (allow-none): location to store the natural height, + * or %NULL + * + * Gets the accumulative preferred height for @width for all rows + * which have been requested for the same said @width with this context. + * + * After gtk_cell_area_context_reset() is called and/or before ever + * requesting the size of a #GtkCellArea, the returned values are -1. + * + * Since: 3.0 + */ +void +gtk_cell_area_context_get_preferred_height_for_width (GtkCellAreaContext *context, + gint width, + gint *minimum_height, + gint *natural_height) +{ + g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context)); + + if (GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->get_preferred_height_for_width) + GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->get_preferred_height_for_width (context, + width, + minimum_height, + natural_height); +} + +/** + * gtk_cell_area_context_get_preferred_width_for_height: + * @context: a #GtkCellAreaContext + * @height: a proposed height for allocation + * @minimum_width: (out) (allow-none): location to store the minimum width, + * or %NULL + * @natural_width: (out) (allow-none): location to store the natural width, + * or %NULL + * + * Gets the accumulative preferred width for @height for all rows which + * have been requested for the same said @height with this context. + * + * After gtk_cell_area_context_reset() is called and/or before ever + * requesting the size of a #GtkCellArea, the returned values are -1. + * + * Since: 3.0 + */ +void +gtk_cell_area_context_get_preferred_width_for_height (GtkCellAreaContext *context, + gint height, + gint *minimum_width, + gint *natural_width) +{ + g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context)); + + if (GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->get_preferred_width_for_height) + GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->get_preferred_width_for_height (context, + height, + minimum_width, + natural_width); +} + +/** + * gtk_cell_area_context_get_allocation: + * @context: a #GtkCellAreaContext + * @width: (out) (allow-none): location to store the allocated width, or %NULL + * @height: (out) (allow-none): location to store the allocated height, or %NULL + * + * Fetches the current allocation size for @context. + * + * If the context was not allocated in width or height, or if the + * context was recently reset with gtk_cell_area_context_reset(), + * the returned value will be -1. + * + * Since: 3.0 + */ void gtk_cell_area_context_get_allocation (GtkCellAreaContext *context, - gint *width, - gint *height) + gint *width, + gint *height) { GtkCellAreaContextPrivate *priv; @@ -419,10 +586,26 @@ gtk_cell_area_context_get_allocation (GtkCellAreaContext *context, *height = priv->alloc_height; } +/** + * gtk_cell_area_context_push_preferred_width: + * @context: a #GtkCellAreaContext + * @minimum_width: the proposed new minimum width for @context + * @natural_width: the proposed new natural width for @context + * + * Causes the minimum and/or natural width to grow if the new + * proposed sizes exceed the current minimum and natural width. + * + * This is used by #GtkCellAreaContext implementations during + * the request process over a series of #GtkTreeModel rows to + * progressively push the requested width over a series of + * gtk_cell_area_get_preferred_width() requests. + * + * Since: 3.0 + */ void gtk_cell_area_context_push_preferred_width (GtkCellAreaContext *context, - gint minimum_width, - gint natural_width) + gint minimum_width, + gint natural_width) { GtkCellAreaContextPrivate *priv; @@ -449,13 +632,29 @@ gtk_cell_area_context_push_preferred_width (GtkCellAreaContext *context, g_object_thaw_notify (G_OBJECT (context)); } +/** + * gtk_cell_area_context_push_preferred_height: + * @context: a #GtkCellAreaContext + * @minimum_height: the proposed new minimum height for @context + * @natural_height: the proposed new natural height for @context + * + * Causes the minimum and/or natural height to grow if the new + * proposed sizes exceed the current minimum and natural height. + * + * This is used by #GtkCellAreaContext implementations during + * the request process over a series of #GtkTreeModel rows to + * progressively push the requested height over a series of + * gtk_cell_area_get_preferred_height() requests. + * + * Since: 3.0 + */ void gtk_cell_area_context_push_preferred_height (GtkCellAreaContext *context, - gint minimum_height, - gint natural_height) + gint minimum_height, + gint natural_height) { GtkCellAreaContextPrivate *priv; - + g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context)); priv = context->priv;