2 * Copyright (C) 2000 Red Hat, Inc. Jonathan Blandford
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
21 #include "gtkcellrenderer.h"
23 #include "gtkmarshalers.h"
24 #include "gtktypebuiltins.h"
25 #include "gtkprivate.h"
26 #include "gtktreeprivate.h"
30 * SECTION:gtkcellrenderer
31 * @Short_description: An object for rendering a single cell
32 * @Title: GtkCellRenderer
33 * @See_also: #GtkCellRendererText, #GtkCellRendererPixbuf, #GtkCellRendererToggle
35 * The #GtkCellRenderer is a base class of a set of objects used for
36 * rendering a cell to a #cairo_t. These objects are used primarily by
37 * the #GtkTreeView widget, though they aren't tied to them in any
38 * specific way. It is worth noting that #GtkCellRenderer is not a
39 * #GtkWidget and cannot be treated as such.
41 * The primary use of a #GtkCellRenderer is for drawing a certain graphical
42 * elements on a #cairo_t. Typically, one cell renderer is used to
43 * draw many cells on the screen. To this extent, it isn't expected that a
44 * CellRenderer keep any permanent state around. Instead, any state is set
45 * just prior to use using #GObject<!-- -->s property system. Then, the
46 * cell is measured using gtk_cell_renderer_get_size(). Finally, the cell
47 * is rendered in the correct location using gtk_cell_renderer_render().
49 * There are a number of rules that must be followed when writing a new
50 * #GtkCellRenderer. First and formost, it's important that a certain set
51 * of properties will always yield a cell renderer of the same size,
52 * barring a #GtkStyle change. The #GtkCellRenderer also has a number of
53 * generic properties that are expected to be honored by all children.
55 * Beyond merely rendering a cell, cell renderers can optionally
56 * provide active user interface elements. A cell renderer can be
57 * <firstterm>activatable</firstterm> like #GtkCellRendererToggle,
58 * which toggles when it gets activated by a mouse click, or it can be
59 * <firstterm>editable</firstterm> like #GtkCellRendererText, which
60 * allows the user to edit the text using a #GtkEntry.
61 * To make a cell renderer activatable or editable, you have to
62 * implement the #GtkCellRendererClass.activate or
63 * #GtkCellRendererClass.start_editing virtual functions, respectively.
67 #define DEBUG_CELL_SIZE_REQUEST 0
69 static void gtk_cell_renderer_init (GtkCellRenderer *cell);
70 static void gtk_cell_renderer_class_init (GtkCellRendererClass *class);
71 static void gtk_cell_renderer_get_property (GObject *object,
75 static void gtk_cell_renderer_set_property (GObject *object,
79 static void set_cell_bg_color (GtkCellRenderer *cell,
82 /* Fallback GtkCellRenderer implementation to use remaining ->get_size() implementations */
83 static void gtk_cell_renderer_real_get_preferred_width (GtkCellRenderer *cell,
87 static void gtk_cell_renderer_real_get_preferred_height (GtkCellRenderer *cell,
91 static void gtk_cell_renderer_real_get_preferred_height_for_width(GtkCellRenderer *cell,
95 gint *natural_height);
96 static void gtk_cell_renderer_real_get_preferred_width_for_height(GtkCellRenderer *cell,
100 gint *natural_width);
101 static void gtk_cell_renderer_real_get_aligned_area (GtkCellRenderer *cell,
103 GtkCellRendererState flags,
104 const GdkRectangle *cell_area,
105 GdkRectangle *aligned_area);
108 struct _GtkCellRendererPrivate
121 guint is_expander : 1;
122 guint is_expanded : 1;
123 guint cell_background_set : 1;
127 GdkRGBA cell_background;
144 PROP_CELL_BACKGROUND,
145 PROP_CELL_BACKGROUND_GDK,
146 PROP_CELL_BACKGROUND_RGBA,
147 PROP_CELL_BACKGROUND_SET,
158 static guint cell_renderer_signals[LAST_SIGNAL] = { 0 };
160 G_DEFINE_ABSTRACT_TYPE(GtkCellRenderer, gtk_cell_renderer, G_TYPE_INITIALLY_UNOWNED)
163 gtk_cell_renderer_init (GtkCellRenderer *cell)
165 GtkCellRendererPrivate *priv;
167 cell->priv = G_TYPE_INSTANCE_GET_PRIVATE (cell,
168 GTK_TYPE_CELL_RENDERER,
169 GtkCellRendererPrivate);
172 priv->mode = GTK_CELL_RENDERER_MODE_INERT;
173 priv->visible = TRUE;
180 priv->sensitive = TRUE;
181 priv->is_expander = FALSE;
182 priv->is_expanded = FALSE;
183 priv->editing = FALSE;
187 gtk_cell_renderer_class_init (GtkCellRendererClass *class)
189 GObjectClass *object_class = G_OBJECT_CLASS (class);
191 object_class->get_property = gtk_cell_renderer_get_property;
192 object_class->set_property = gtk_cell_renderer_set_property;
194 class->render = NULL;
195 class->get_size = NULL;
196 class->get_preferred_width = gtk_cell_renderer_real_get_preferred_width;
197 class->get_preferred_height = gtk_cell_renderer_real_get_preferred_height;
198 class->get_preferred_width_for_height = gtk_cell_renderer_real_get_preferred_width_for_height;
199 class->get_preferred_height_for_width = gtk_cell_renderer_real_get_preferred_height_for_width;
200 class->get_aligned_area = gtk_cell_renderer_real_get_aligned_area;
203 * GtkCellRenderer::editing-canceled:
204 * @renderer: the object which received the signal
206 * This signal gets emitted when the user cancels the process of editing a
207 * cell. For example, an editable cell renderer could be written to cancel
208 * editing when the user presses Escape.
210 * See also: gtk_cell_renderer_stop_editing().
214 cell_renderer_signals[EDITING_CANCELED] =
215 g_signal_new (I_("editing-canceled"),
216 G_OBJECT_CLASS_TYPE (object_class),
218 G_STRUCT_OFFSET (GtkCellRendererClass, editing_canceled),
220 _gtk_marshal_VOID__VOID,
224 * GtkCellRenderer::editing-started:
225 * @renderer: the object which received the signal
226 * @editable: the #GtkCellEditable
227 * @path: the path identifying the edited cell
229 * This signal gets emitted when a cell starts to be edited.
230 * The intended use of this signal is to do special setup
231 * on @editable, e.g. adding a #GtkEntryCompletion or setting
232 * up additional columns in a #GtkComboBox.
234 * Note that GTK+ doesn't guarantee that cell renderers will
235 * continue to use the same kind of widget for editing in future
236 * releases, therefore you should check the type of @editable
237 * before doing any specific setup, as in the following example:
240 * text_editing_started (GtkCellRenderer *cell,
241 * GtkCellEditable *editable,
245 * if (GTK_IS_ENTRY (editable))
247 * GtkEntry *entry = GTK_ENTRY (editable);
249 * /* ... create a GtkEntryCompletion */
251 * gtk_entry_set_completion (entry, completion);
258 cell_renderer_signals[EDITING_STARTED] =
259 g_signal_new (I_("editing-started"),
260 G_OBJECT_CLASS_TYPE (object_class),
262 G_STRUCT_OFFSET (GtkCellRendererClass, editing_started),
264 _gtk_marshal_VOID__OBJECT_STRING,
266 GTK_TYPE_CELL_EDITABLE,
269 g_object_class_install_property (object_class,
271 g_param_spec_enum ("mode",
273 P_("Editable mode of the CellRenderer"),
274 GTK_TYPE_CELL_RENDERER_MODE,
275 GTK_CELL_RENDERER_MODE_INERT,
276 GTK_PARAM_READWRITE));
278 g_object_class_install_property (object_class,
280 g_param_spec_boolean ("visible",
282 P_("Display the cell"),
284 GTK_PARAM_READWRITE));
285 g_object_class_install_property (object_class,
287 g_param_spec_boolean ("sensitive",
289 P_("Display the cell sensitive"),
291 GTK_PARAM_READWRITE));
293 g_object_class_install_property (object_class,
295 g_param_spec_float ("xalign",
301 GTK_PARAM_READWRITE));
303 g_object_class_install_property (object_class,
305 g_param_spec_float ("yalign",
311 GTK_PARAM_READWRITE));
313 g_object_class_install_property (object_class,
315 g_param_spec_uint ("xpad",
321 GTK_PARAM_READWRITE));
323 g_object_class_install_property (object_class,
325 g_param_spec_uint ("ypad",
331 GTK_PARAM_READWRITE));
333 g_object_class_install_property (object_class,
335 g_param_spec_int ("width",
337 P_("The fixed width"),
341 GTK_PARAM_READWRITE));
343 g_object_class_install_property (object_class,
345 g_param_spec_int ("height",
347 P_("The fixed height"),
351 GTK_PARAM_READWRITE));
353 g_object_class_install_property (object_class,
355 g_param_spec_boolean ("is-expander",
357 P_("Row has children"),
359 GTK_PARAM_READWRITE));
362 g_object_class_install_property (object_class,
364 g_param_spec_boolean ("is-expanded",
366 P_("Row is an expander row, and is expanded"),
368 GTK_PARAM_READWRITE));
370 g_object_class_install_property (object_class,
371 PROP_CELL_BACKGROUND,
372 g_param_spec_string ("cell-background",
373 P_("Cell background color name"),
374 P_("Cell background color as a string"),
376 GTK_PARAM_WRITABLE));
378 g_object_class_install_property (object_class,
379 PROP_CELL_BACKGROUND_GDK,
380 g_param_spec_boxed ("cell-background-gdk",
381 P_("Cell background color"),
382 P_("Cell background color as a GdkColor"),
384 GTK_PARAM_READWRITE));
386 * GtkCellRenderer:cell-background-rgba:
388 * Cell background as a #GdkRGBA
392 g_object_class_install_property (object_class,
393 PROP_CELL_BACKGROUND_RGBA,
394 g_param_spec_boxed ("cell-background-rgba",
395 P_("Cell background RGBA color"),
396 P_("Cell background color as a GdkRGBA"),
398 GTK_PARAM_READWRITE));
400 g_object_class_install_property (object_class,
402 g_param_spec_boolean ("editing",
404 P_("Whether the cell renderer is currently in editing mode"),
406 GTK_PARAM_READABLE));
409 #define ADD_SET_PROP(propname, propval, nick, blurb) g_object_class_install_property (object_class, propval, g_param_spec_boolean (propname, nick, blurb, FALSE, GTK_PARAM_READWRITE))
411 ADD_SET_PROP ("cell-background-set", PROP_CELL_BACKGROUND_SET,
412 P_("Cell background set"),
413 P_("Whether this tag affects the cell background color"));
415 g_type_class_add_private (class, sizeof (GtkCellRendererPrivate));
419 gtk_cell_renderer_get_property (GObject *object,
424 GtkCellRenderer *cell = GTK_CELL_RENDERER (object);
425 GtkCellRendererPrivate *priv = cell->priv;
430 g_value_set_enum (value, priv->mode);
433 g_value_set_boolean (value, priv->visible);
436 g_value_set_boolean (value, priv->sensitive);
439 g_value_set_boolean (value, priv->editing);
442 g_value_set_float (value, priv->xalign);
445 g_value_set_float (value, priv->yalign);
448 g_value_set_uint (value, priv->xpad);
451 g_value_set_uint (value, priv->ypad);
454 g_value_set_int (value, priv->width);
457 g_value_set_int (value, priv->height);
459 case PROP_IS_EXPANDER:
460 g_value_set_boolean (value, priv->is_expander);
462 case PROP_IS_EXPANDED:
463 g_value_set_boolean (value, priv->is_expanded);
465 case PROP_CELL_BACKGROUND_GDK:
469 color.red = (guint16) (priv->cell_background.red * 65535);
470 color.green = (guint16) (priv->cell_background.green * 65535);
471 color.blue = (guint16) (priv->cell_background.blue * 65535);
473 g_value_set_boxed (value, &color);
476 case PROP_CELL_BACKGROUND_RGBA:
477 g_value_set_boxed (value, &priv->cell_background);
479 case PROP_CELL_BACKGROUND_SET:
480 g_value_set_boolean (value, priv->cell_background_set);
482 case PROP_CELL_BACKGROUND:
484 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, param_id, pspec);
491 gtk_cell_renderer_set_property (GObject *object,
496 GtkCellRenderer *cell = GTK_CELL_RENDERER (object);
497 GtkCellRendererPrivate *priv = cell->priv;
502 priv->mode = g_value_get_enum (value);
505 priv->visible = g_value_get_boolean (value);
508 priv->sensitive = g_value_get_boolean (value);
511 priv->editing = g_value_get_boolean (value);
514 priv->xalign = g_value_get_float (value);
517 priv->yalign = g_value_get_float (value);
520 priv->xpad = g_value_get_uint (value);
523 priv->ypad = g_value_get_uint (value);
526 priv->width = g_value_get_int (value);
529 priv->height = g_value_get_int (value);
531 case PROP_IS_EXPANDER:
532 priv->is_expander = g_value_get_boolean (value);
534 case PROP_IS_EXPANDED:
535 priv->is_expanded = g_value_get_boolean (value);
537 case PROP_CELL_BACKGROUND:
541 if (!g_value_get_string (value))
542 set_cell_bg_color (cell, NULL);
543 else if (gdk_rgba_parse (&rgba, g_value_get_string (value)))
544 set_cell_bg_color (cell, &rgba);
546 g_warning ("Don't know color `%s'", g_value_get_string (value));
548 g_object_notify (object, "cell-background-gdk");
551 case PROP_CELL_BACKGROUND_GDK:
555 color = g_value_get_boxed (value);
560 rgba.red = color->red / 65535.;
561 rgba.green = color->green / 65535.;
562 rgba.blue = color->blue / 65535.;
565 set_cell_bg_color (cell, &rgba);
569 set_cell_bg_color (cell, NULL);
573 case PROP_CELL_BACKGROUND_RGBA:
574 set_cell_bg_color (cell, g_value_get_boxed (value));
576 case PROP_CELL_BACKGROUND_SET:
577 priv->cell_background_set = g_value_get_boolean (value);
580 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, param_id, pspec);
586 set_cell_bg_color (GtkCellRenderer *cell,
589 GtkCellRendererPrivate *priv = cell->priv;
593 if (!priv->cell_background_set)
595 priv->cell_background_set = TRUE;
596 g_object_notify (G_OBJECT (cell), "cell-background-set");
599 priv->cell_background = *rgba;
603 if (priv->cell_background_set)
605 priv->cell_background_set = FALSE;
606 g_object_notify (G_OBJECT (cell), "cell-background-set");
612 * gtk_cell_renderer_get_size:
613 * @cell: a #GtkCellRenderer
614 * @widget: the widget the renderer is rendering to
615 * @cell_area: (allow-none): The area a cell will be allocated, or %NULL
616 * @x_offset: (allow-none): location to return x offset of cell relative to @cell_area, or %NULL
617 * @y_offset: (allow-none): location to return y offset of cell relative to @cell_area, or %NULL
618 * @width: (allow-none): location to return width needed to render a cell, or %NULL
619 * @height: (allow-none): location to return height needed to render a cell, or %NULL
621 * Obtains the width and height needed to render the cell. Used by view
622 * widgets to determine the appropriate size for the cell_area passed to
623 * gtk_cell_renderer_render(). If @cell_area is not %NULL, fills in the
624 * x and y offsets (if set) of the cell relative to this location.
626 * Please note that the values set in @width and @height, as well as those
627 * in @x_offset and @y_offset are inclusive of the xpad and ypad properties.
630 * Deprecated: 3.0: Use gtk_cell_renderer_get_preferred_size() instead.
633 gtk_cell_renderer_get_size (GtkCellRenderer *cell,
635 const GdkRectangle *cell_area,
641 GtkRequisition request;
643 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
645 gtk_cell_renderer_get_preferred_size (cell, widget, &request, NULL);
648 *width = request.width;
651 *height = request.height;
654 _gtk_cell_renderer_calc_offset (cell, cell_area, gtk_widget_get_direction (widget),
655 request.width, request.height, x_offset, y_offset);
659 * gtk_cell_renderer_render:
660 * @cell: a #GtkCellRenderer
661 * @cr: a cairo context to draw to
662 * @widget: the widget owning @window
663 * @background_area: entire cell area (including tree expanders and maybe
664 * padding on the sides)
665 * @cell_area: area normally rendered by a cell renderer
666 * @flags: flags that affect rendering
668 * Invokes the virtual render function of the #GtkCellRenderer. The three
669 * passed-in rectangles are areas in @cr. Most renderers will draw within
670 * @cell_area; the xalign, yalign, xpad, and ypad fields of the #GtkCellRenderer
671 * should be honored with respect to @cell_area. @background_area includes the
672 * blank space around the cell, and also the area containing the tree expander;
673 * so the @background_area rectangles for all cells tile to cover the entire
677 gtk_cell_renderer_render (GtkCellRenderer *cell,
680 const GdkRectangle *background_area,
681 const GdkRectangle *cell_area,
682 GtkCellRendererState flags)
684 gboolean selected = FALSE;
685 GtkCellRendererPrivate *priv = cell->priv;
687 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
688 g_return_if_fail (GTK_CELL_RENDERER_GET_CLASS (cell)->render != NULL);
689 g_return_if_fail (cr != NULL);
691 selected = (flags & GTK_CELL_RENDERER_SELECTED) == GTK_CELL_RENDERER_SELECTED;
695 if (priv->cell_background_set && !selected)
697 gdk_cairo_rectangle (cr, background_area);
698 gdk_cairo_set_source_rgba (cr, &priv->cell_background);
702 gdk_cairo_rectangle (cr, background_area);
705 GTK_CELL_RENDERER_GET_CLASS (cell)->render (cell,
716 * gtk_cell_renderer_activate:
717 * @cell: a #GtkCellRenderer
718 * @event: a #GdkEvent
719 * @widget: widget that received the event
720 * @path: widget-dependent string representation of the event location;
721 * e.g. for #GtkTreeView, a string representation of #GtkTreePath
722 * @background_area: background area as passed to gtk_cell_renderer_render()
723 * @cell_area: cell area as passed to gtk_cell_renderer_render()
724 * @flags: render flags
726 * Passes an activate event to the cell renderer for possible processing.
727 * Some cell renderers may use events; for example, #GtkCellRendererToggle
728 * toggles when it gets a mouse click.
730 * Return value: %TRUE if the event was consumed/handled
733 gtk_cell_renderer_activate (GtkCellRenderer *cell,
737 const GdkRectangle *background_area,
738 const GdkRectangle *cell_area,
739 GtkCellRendererState flags)
741 GtkCellRendererPrivate *priv;
743 g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
747 if (priv->mode != GTK_CELL_RENDERER_MODE_ACTIVATABLE)
750 if (GTK_CELL_RENDERER_GET_CLASS (cell)->activate == NULL)
753 return GTK_CELL_RENDERER_GET_CLASS (cell)->activate (cell,
757 (GdkRectangle *) background_area,
758 (GdkRectangle *) cell_area,
763 * gtk_cell_renderer_start_editing:
764 * @cell: a #GtkCellRenderer
765 * @event: a #GdkEvent
766 * @widget: widget that received the event
767 * @path: widget-dependent string representation of the event location;
768 * e.g. for #GtkTreeView, a string representation of #GtkTreePath
769 * @background_area: background area as passed to gtk_cell_renderer_render()
770 * @cell_area: cell area as passed to gtk_cell_renderer_render()
771 * @flags: render flags
773 * Passes an activate event to the cell renderer for possible processing.
775 * Return value: (transfer full): A new #GtkCellEditable, or %NULL
778 gtk_cell_renderer_start_editing (GtkCellRenderer *cell,
782 const GdkRectangle *background_area,
783 const GdkRectangle *cell_area,
784 GtkCellRendererState flags)
787 GtkCellRendererPrivate *priv;
788 GtkCellEditable *editable;
790 g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), NULL);
794 if (priv->mode != GTK_CELL_RENDERER_MODE_EDITABLE)
797 if (GTK_CELL_RENDERER_GET_CLASS (cell)->start_editing == NULL)
800 editable = GTK_CELL_RENDERER_GET_CLASS (cell)->start_editing (cell,
804 (GdkRectangle *) background_area,
805 (GdkRectangle *) cell_area,
809 cell_renderer_signals[EDITING_STARTED], 0,
812 priv->editing = TRUE;
818 * gtk_cell_renderer_set_fixed_size:
819 * @cell: A #GtkCellRenderer
820 * @width: the width of the cell renderer, or -1
821 * @height: the height of the cell renderer, or -1
823 * Sets the renderer size to be explicit, independent of the properties set.
826 gtk_cell_renderer_set_fixed_size (GtkCellRenderer *cell,
830 GtkCellRendererPrivate *priv;
832 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
833 g_return_if_fail (width >= -1 && height >= -1);
837 if ((width != priv->width) || (height != priv->height))
839 g_object_freeze_notify (G_OBJECT (cell));
841 if (width != priv->width)
844 g_object_notify (G_OBJECT (cell), "width");
847 if (height != priv->height)
849 priv->height = height;
850 g_object_notify (G_OBJECT (cell), "height");
853 g_object_thaw_notify (G_OBJECT (cell));
858 * gtk_cell_renderer_get_fixed_size:
859 * @cell: A #GtkCellRenderer
860 * @width: (allow-none): location to fill in with the fixed width of the cell, or %NULL
861 * @height: (allow-none): location to fill in with the fixed height of the cell, or %NULL
863 * Fills in @width and @height with the appropriate size of @cell.
866 gtk_cell_renderer_get_fixed_size (GtkCellRenderer *cell,
870 GtkCellRendererPrivate *priv;
872 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
877 *width = priv->width;
879 *height = priv->height;
883 * gtk_cell_renderer_set_alignment:
884 * @cell: A #GtkCellRenderer
885 * @xalign: the x alignment of the cell renderer
886 * @yalign: the y alignment of the cell renderer
888 * Sets the renderer's alignment within its available space.
893 gtk_cell_renderer_set_alignment (GtkCellRenderer *cell,
897 GtkCellRendererPrivate *priv;
899 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
900 g_return_if_fail (xalign >= 0.0 && xalign <= 1.0);
901 g_return_if_fail (yalign >= 0.0 && yalign <= 1.0);
905 if ((xalign != priv->xalign) || (yalign != priv->yalign))
907 g_object_freeze_notify (G_OBJECT (cell));
909 if (xalign != priv->xalign)
911 priv->xalign = xalign;
912 g_object_notify (G_OBJECT (cell), "xalign");
915 if (yalign != priv->yalign)
917 priv->yalign = yalign;
918 g_object_notify (G_OBJECT (cell), "yalign");
921 g_object_thaw_notify (G_OBJECT (cell));
926 * gtk_cell_renderer_get_alignment:
927 * @cell: A #GtkCellRenderer
928 * @xalign: (allow-none): location to fill in with the x alignment of the cell, or %NULL
929 * @yalign: (allow-none): location to fill in with the y alignment of the cell, or %NULL
931 * Fills in @xalign and @yalign with the appropriate values of @cell.
936 gtk_cell_renderer_get_alignment (GtkCellRenderer *cell,
940 GtkCellRendererPrivate *priv;
942 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
947 *xalign = priv->xalign;
949 *yalign = priv->yalign;
953 * gtk_cell_renderer_set_padding:
954 * @cell: A #GtkCellRenderer
955 * @xpad: the x padding of the cell renderer
956 * @ypad: the y padding of the cell renderer
958 * Sets the renderer's padding.
963 gtk_cell_renderer_set_padding (GtkCellRenderer *cell,
967 GtkCellRendererPrivate *priv;
969 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
970 g_return_if_fail (xpad >= 0 && xpad >= 0);
974 if ((xpad != priv->xpad) || (ypad != priv->ypad))
976 g_object_freeze_notify (G_OBJECT (cell));
978 if (xpad != priv->xpad)
981 g_object_notify (G_OBJECT (cell), "xpad");
984 if (ypad != priv->ypad)
987 g_object_notify (G_OBJECT (cell), "ypad");
990 g_object_thaw_notify (G_OBJECT (cell));
995 * gtk_cell_renderer_get_padding:
996 * @cell: A #GtkCellRenderer
997 * @xpad: (allow-none): location to fill in with the x padding of the cell, or %NULL
998 * @ypad: (allow-none): location to fill in with the y padding of the cell, or %NULL
1000 * Fills in @xpad and @ypad with the appropriate values of @cell.
1005 gtk_cell_renderer_get_padding (GtkCellRenderer *cell,
1009 GtkCellRendererPrivate *priv;
1011 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1022 * gtk_cell_renderer_set_visible:
1023 * @cell: A #GtkCellRenderer
1024 * @visible: the visibility of the cell
1026 * Sets the cell renderer's visibility.
1031 gtk_cell_renderer_set_visible (GtkCellRenderer *cell,
1034 GtkCellRendererPrivate *priv;
1036 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1040 if (priv->visible != visible)
1042 priv->visible = visible ? TRUE : FALSE;
1043 g_object_notify (G_OBJECT (cell), "visible");
1048 * gtk_cell_renderer_get_visible:
1049 * @cell: A #GtkCellRenderer
1051 * Returns the cell renderer's visibility.
1053 * Returns: %TRUE if the cell renderer is visible
1058 gtk_cell_renderer_get_visible (GtkCellRenderer *cell)
1060 g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
1062 return cell->priv->visible;
1066 * gtk_cell_renderer_set_sensitive:
1067 * @cell: A #GtkCellRenderer
1068 * @sensitive: the sensitivity of the cell
1070 * Sets the cell renderer's sensitivity.
1075 gtk_cell_renderer_set_sensitive (GtkCellRenderer *cell,
1078 GtkCellRendererPrivate *priv;
1080 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1084 if (priv->sensitive != sensitive)
1086 priv->sensitive = sensitive ? TRUE : FALSE;
1087 g_object_notify (G_OBJECT (cell), "sensitive");
1092 * gtk_cell_renderer_get_sensitive:
1093 * @cell: A #GtkCellRenderer
1095 * Returns the cell renderer's sensitivity.
1097 * Returns: %TRUE if the cell renderer is sensitive
1102 gtk_cell_renderer_get_sensitive (GtkCellRenderer *cell)
1104 g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
1106 return cell->priv->sensitive;
1111 * gtk_cell_renderer_is_activatable:
1112 * @cell: A #GtkCellRenderer
1114 * Checks whether the cell renderer can do something when activated.
1116 * Returns: %TRUE if the cell renderer can do anything when activated.
1121 gtk_cell_renderer_is_activatable (GtkCellRenderer *cell)
1123 GtkCellRendererPrivate *priv;
1125 g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
1129 return (cell->priv->visible &&
1130 (cell->priv->mode == GTK_CELL_RENDERER_MODE_EDITABLE ||
1131 cell->priv->mode == GTK_CELL_RENDERER_MODE_ACTIVATABLE));
1136 * gtk_cell_renderer_stop_editing:
1137 * @cell: A #GtkCellRenderer
1138 * @canceled: %TRUE if the editing has been canceled
1140 * Informs the cell renderer that the editing is stopped.
1141 * If @canceled is %TRUE, the cell renderer will emit the
1142 * #GtkCellRenderer::editing-canceled signal.
1144 * This function should be called by cell renderer implementations
1145 * in response to the #GtkCellEditable::editing-done signal of
1151 gtk_cell_renderer_stop_editing (GtkCellRenderer *cell,
1154 GtkCellRendererPrivate *priv;
1156 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1162 priv->editing = FALSE;
1164 g_signal_emit (cell, cell_renderer_signals[EDITING_CANCELED], 0);
1169 gtk_cell_renderer_real_get_preferred_size (GtkCellRenderer *cell,
1171 GtkOrientation orientation,
1175 GtkRequisition min_req;
1177 /* Fallback on the old API to get the size. */
1178 if (GTK_CELL_RENDERER_GET_CLASS (cell)->get_size)
1179 GTK_CELL_RENDERER_GET_CLASS (cell)->get_size (GTK_CELL_RENDERER (cell), widget, NULL, NULL, NULL,
1180 &min_req.width, &min_req.height);
1187 if (orientation == GTK_ORIENTATION_HORIZONTAL)
1190 *minimum_size = min_req.width;
1193 *natural_size = min_req.width;
1198 *minimum_size = min_req.height;
1201 *natural_size = min_req.height;
1206 gtk_cell_renderer_real_get_preferred_width (GtkCellRenderer *cell,
1211 gtk_cell_renderer_real_get_preferred_size (cell, widget, GTK_ORIENTATION_HORIZONTAL,
1212 minimum_size, natural_size);
1216 gtk_cell_renderer_real_get_preferred_height (GtkCellRenderer *cell,
1221 gtk_cell_renderer_real_get_preferred_size (cell, widget, GTK_ORIENTATION_VERTICAL,
1222 minimum_size, natural_size);
1227 gtk_cell_renderer_real_get_preferred_height_for_width (GtkCellRenderer *cell,
1230 gint *minimum_height,
1231 gint *natural_height)
1233 /* Fall back on the height reported from ->get_size() */
1234 gtk_cell_renderer_get_preferred_height (cell, widget, minimum_height, natural_height);
1238 gtk_cell_renderer_real_get_preferred_width_for_height (GtkCellRenderer *cell,
1241 gint *minimum_width,
1242 gint *natural_width)
1244 /* Fall back on the width reported from ->get_size() */
1245 gtk_cell_renderer_get_preferred_width (cell, widget, minimum_width, natural_width);
1249 /* Default implementation assumes that a cell renderer will never use more
1250 * space than it's natural size (this is fine for toggles and pixbufs etc
1251 * but needs to be overridden from wrapping/ellipsizing text renderers) */
1253 gtk_cell_renderer_real_get_aligned_area (GtkCellRenderer *cell,
1255 GtkCellRendererState flags,
1256 const GdkRectangle *cell_area,
1257 GdkRectangle *aligned_area)
1259 gint opposite_size, x_offset, y_offset;
1262 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1263 g_return_if_fail (GTK_IS_WIDGET (widget));
1264 g_return_if_fail (cell_area != NULL);
1265 g_return_if_fail (aligned_area != NULL);
1267 *aligned_area = *cell_area;
1269 /* Trim up the aligned size */
1270 if (gtk_cell_renderer_get_request_mode (cell) == GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH)
1272 gtk_cell_renderer_get_preferred_width (cell, widget,
1273 NULL, &natural_size);
1275 aligned_area->width = MIN (aligned_area->width, natural_size);
1277 gtk_cell_renderer_get_preferred_height_for_width (cell, widget,
1278 aligned_area->width,
1279 NULL, &opposite_size);
1281 aligned_area->height = MIN (opposite_size, aligned_area->height);
1285 gtk_cell_renderer_get_preferred_height (cell, widget,
1286 NULL, &natural_size);
1288 aligned_area->height = MIN (aligned_area->width, natural_size);
1290 gtk_cell_renderer_get_preferred_width_for_height (cell, widget,
1291 aligned_area->height,
1292 NULL, &opposite_size);
1294 aligned_area->width = MIN (opposite_size, aligned_area->width);
1297 /* offset the cell position */
1298 _gtk_cell_renderer_calc_offset (cell, cell_area,
1299 gtk_widget_get_direction (widget),
1300 aligned_area->width,
1301 aligned_area->height,
1302 &x_offset, &y_offset);
1304 aligned_area->x += x_offset;
1305 aligned_area->y += y_offset;
1309 /* An internal convenience function for some containers to peek at the
1310 * cell alignment in a target allocation (used to draw focus and align
1311 * cells in the icon view).
1313 * Note this is only a trivial 'align * (allocation - request)' operation.
1316 _gtk_cell_renderer_calc_offset (GtkCellRenderer *cell,
1317 const GdkRectangle *cell_area,
1318 GtkTextDirection direction,
1324 GtkCellRendererPrivate *priv;
1326 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1327 g_return_if_fail (cell_area != NULL);
1328 g_return_if_fail (x_offset || y_offset);
1334 *x_offset = (((direction == GTK_TEXT_DIR_RTL) ?
1335 (1.0 - priv->xalign) : priv->xalign) *
1336 (cell_area->width - width));
1337 *x_offset = MAX (*x_offset, 0);
1341 *y_offset = (priv->yalign *
1342 (cell_area->height - height));
1343 *y_offset = MAX (*y_offset, 0);
1348 * gtk_cell_renderer_get_request_mode:
1349 * @cell: a #GtkCellRenderer instance
1351 * Gets whether the cell renderer prefers a height-for-width layout
1352 * or a width-for-height layout.
1354 * Returns: The #GtkSizeRequestMode preferred by this renderer.
1359 gtk_cell_renderer_get_request_mode (GtkCellRenderer *cell)
1361 GtkCellRendererClass *klass;
1363 g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
1365 klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1366 if (klass->get_request_mode)
1367 return klass->get_request_mode (cell);
1369 /* By default cell renderers are height-for-width. */
1370 return GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH;
1374 * gtk_cell_renderer_get_preferred_width:
1375 * @cell: a #GtkCellRenderer instance
1376 * @widget: the #GtkWidget this cell will be rendering to
1377 * @minimum_size: location to store the minimum size, or %NULL
1378 * @natural_size: location to store the natural size, or %NULL
1380 * Retreives a renderer's natural size when rendered to @widget.
1385 gtk_cell_renderer_get_preferred_width (GtkCellRenderer *cell,
1390 GtkCellRendererClass *klass;
1393 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1394 g_return_if_fail (GTK_IS_WIDGET (widget));
1395 g_return_if_fail (NULL != minimum_size || NULL != natural_size);
1397 gtk_cell_renderer_get_fixed_size (GTK_CELL_RENDERER (cell), &width, NULL);
1401 klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1402 klass->get_preferred_width (cell, widget, minimum_size, natural_size);
1407 *minimum_size = width;
1409 *natural_size = width;
1412 #if DEBUG_CELL_SIZE_REQUEST
1413 g_message ("%s returning minimum width: %d and natural width: %d",
1414 G_OBJECT_TYPE_NAME (cell),
1415 minimum_size ? *minimum_size : 20000,
1416 natural_size ? *natural_size : 20000);
1422 * gtk_cell_renderer_get_preferred_height:
1423 * @cell: a #GtkCellRenderer instance
1424 * @widget: the #GtkWidget this cell will be rendering to
1425 * @minimum_size: location to store the minimum size, or %NULL
1426 * @natural_size: location to store the natural size, or %NULL
1428 * Retreives a renderer's natural size when rendered to @widget.
1433 gtk_cell_renderer_get_preferred_height (GtkCellRenderer *cell,
1438 GtkCellRendererClass *klass;
1441 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1442 g_return_if_fail (GTK_IS_WIDGET (widget));
1443 g_return_if_fail (NULL != minimum_size || NULL != natural_size);
1445 gtk_cell_renderer_get_fixed_size (GTK_CELL_RENDERER (cell), NULL, &height);
1449 klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1450 klass->get_preferred_height (cell, widget, minimum_size, natural_size);
1455 *minimum_size = height;
1457 *natural_size = height;
1460 #if DEBUG_CELL_SIZE_REQUEST
1461 g_message ("%s returning minimum height: %d and natural height: %d",
1462 G_OBJECT_TYPE_NAME (cell),
1463 minimum_size ? *minimum_size : 20000,
1464 natural_size ? *natural_size : 20000);
1470 * gtk_cell_renderer_get_preferred_width_for_height:
1471 * @cell: a #GtkCellRenderer instance
1472 * @widget: the #GtkWidget this cell will be rendering to
1473 * @height: the size which is available for allocation
1474 * @minimum_width: location for storing the minimum size, or %NULL
1475 * @natural_width: location for storing the preferred size, or %NULL
1477 * Retreives a cell renderers's minimum and natural width if it were rendered to
1478 * @widget with the specified @height.
1483 gtk_cell_renderer_get_preferred_width_for_height (GtkCellRenderer *cell,
1486 gint *minimum_width,
1487 gint *natural_width)
1489 GtkCellRendererClass *klass;
1492 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1493 g_return_if_fail (GTK_IS_WIDGET (widget));
1494 g_return_if_fail (NULL != minimum_width || NULL != natural_width);
1496 gtk_cell_renderer_get_fixed_size (GTK_CELL_RENDERER (cell), &width, NULL);
1500 klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1501 klass->get_preferred_width_for_height (cell, widget, height, minimum_width, natural_width);
1506 *minimum_width = width;
1508 *natural_width = width;
1511 #if DEBUG_CELL_SIZE_REQUEST
1512 g_message ("%s width for height: %d is minimum %d and natural: %d",
1513 G_OBJECT_TYPE_NAME (cell), height,
1514 minimum_width ? *minimum_width : 20000,
1515 natural_width ? *natural_width : 20000);
1520 * gtk_cell_renderer_get_preferred_height_for_width:
1521 * @cell: a #GtkCellRenderer instance
1522 * @widget: the #GtkWidget this cell will be rendering to
1523 * @width: the size which is available for allocation
1524 * @minimum_height: location for storing the minimum size, or %NULL
1525 * @natural_height: location for storing the preferred size, or %NULL
1527 * Retreives a cell renderers's minimum and natural height if it were rendered to
1528 * @widget with the specified @width.
1533 gtk_cell_renderer_get_preferred_height_for_width (GtkCellRenderer *cell,
1536 gint *minimum_height,
1537 gint *natural_height)
1539 GtkCellRendererClass *klass;
1542 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1543 g_return_if_fail (GTK_IS_WIDGET (widget));
1544 g_return_if_fail (NULL != minimum_height || NULL != natural_height);
1546 gtk_cell_renderer_get_fixed_size (GTK_CELL_RENDERER (cell), NULL, &height);
1550 klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1551 klass->get_preferred_height_for_width (cell, widget, width, minimum_height, natural_height);
1556 *minimum_height = height;
1558 *natural_height = height;
1561 #if DEBUG_CELL_SIZE_REQUEST
1562 g_message ("%s height for width: %d is minimum %d and natural: %d",
1563 G_OBJECT_TYPE_NAME (cell), width,
1564 minimum_height ? *minimum_height : 20000,
1565 natural_height ? *natural_height : 20000);
1570 * gtk_cell_renderer_get_preferred_size:
1571 * @cell: a #GtkCellRenderer instance
1572 * @widget: the #GtkWidget this cell will be rendering to
1573 * @minimum_size: (out) (allow-none): location for storing the minimum size, or %NULL
1574 * @natural_size: (out) (allow-none): location for storing the natural size, or %NULL
1576 * Retrieves the minimum and natural size of a cell taking
1577 * into account the widget's preference for height-for-width management.
1582 gtk_cell_renderer_get_preferred_size (GtkCellRenderer *cell,
1584 GtkRequisition *minimum_size,
1585 GtkRequisition *natural_size)
1587 gint min_width, nat_width;
1588 gint min_height, nat_height;
1590 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1592 if (gtk_cell_renderer_get_request_mode (cell) == GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH)
1594 gtk_cell_renderer_get_preferred_width (cell, widget, &min_width, &nat_width);
1598 minimum_size->width = min_width;
1599 gtk_cell_renderer_get_preferred_height_for_width (cell, widget, min_width,
1600 &minimum_size->height, NULL);
1605 natural_size->width = nat_width;
1606 gtk_cell_renderer_get_preferred_height_for_width (cell, widget, nat_width,
1607 NULL, &natural_size->height);
1610 else /* GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT */
1612 gtk_cell_renderer_get_preferred_height (cell, widget, &min_height, &nat_height);
1616 minimum_size->height = min_height;
1617 gtk_cell_renderer_get_preferred_width_for_height (cell, widget, min_height,
1618 &minimum_size->width, NULL);
1623 natural_size->height = nat_height;
1624 gtk_cell_renderer_get_preferred_width_for_height (cell, widget, nat_height,
1625 NULL, &natural_size->width);
1631 * gtk_cell_renderer_get_aligned_area:
1632 * @cell: a #GtkCellRenderer instance
1633 * @widget: the #GtkWidget this cell will be rendering to
1634 * @flags: render flags
1635 * @cell_area: cell area which would be passed to gtk_cell_renderer_render()
1636 * @aligned_area: the return location for the space inside @cell_area that
1637 * would acually be used to render.
1639 * Gets the aligned area used by @cell inside @cell_area. Used for finding
1640 * the appropriate edit and focus rectangle.
1645 gtk_cell_renderer_get_aligned_area (GtkCellRenderer *cell,
1647 GtkCellRendererState flags,
1648 const GdkRectangle *cell_area,
1649 GdkRectangle *aligned_area)
1651 GtkCellRendererClass *klass;
1653 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1654 g_return_if_fail (GTK_IS_WIDGET (widget));
1655 g_return_if_fail (cell_area != NULL);
1656 g_return_if_fail (aligned_area != NULL);
1658 klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1659 klass->get_aligned_area (cell, widget, flags, cell_area, aligned_area);
1661 g_assert (aligned_area->x >= cell_area->x && aligned_area->x <= cell_area->x + cell_area->width);
1662 g_assert (aligned_area->y >= cell_area->y && aligned_area->y <= cell_area->y + cell_area->height);
1663 g_assert ((aligned_area->x - cell_area->x) + aligned_area->width <= cell_area->width);
1664 g_assert ((aligned_area->y - cell_area->y) + aligned_area->height <= cell_area->height);