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, its 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 GtkSizeRequestMode gtk_cell_renderer_real_get_request_mode(GtkCellRenderer *cell);
84 static void gtk_cell_renderer_real_get_preferred_width (GtkCellRenderer *cell,
88 static void gtk_cell_renderer_real_get_preferred_height (GtkCellRenderer *cell,
92 static void gtk_cell_renderer_real_get_preferred_height_for_width(GtkCellRenderer *cell,
96 gint *natural_height);
97 static void gtk_cell_renderer_real_get_preferred_width_for_height(GtkCellRenderer *cell,
101 gint *natural_width);
102 static void gtk_cell_renderer_real_get_aligned_area (GtkCellRenderer *cell,
104 GtkCellRendererState flags,
105 const GdkRectangle *cell_area,
106 GdkRectangle *aligned_area);
109 struct _GtkCellRendererPrivate
122 guint is_expander : 1;
123 guint is_expanded : 1;
124 guint cell_background_set : 1;
128 GdkRGBA cell_background;
145 PROP_CELL_BACKGROUND,
146 PROP_CELL_BACKGROUND_GDK,
147 PROP_CELL_BACKGROUND_RGBA,
148 PROP_CELL_BACKGROUND_SET,
159 static guint cell_renderer_signals[LAST_SIGNAL] = { 0 };
161 G_DEFINE_ABSTRACT_TYPE(GtkCellRenderer, gtk_cell_renderer, G_TYPE_INITIALLY_UNOWNED)
164 gtk_cell_renderer_init (GtkCellRenderer *cell)
166 GtkCellRendererPrivate *priv;
168 cell->priv = G_TYPE_INSTANCE_GET_PRIVATE (cell,
169 GTK_TYPE_CELL_RENDERER,
170 GtkCellRendererPrivate);
173 priv->mode = GTK_CELL_RENDERER_MODE_INERT;
174 priv->visible = TRUE;
181 priv->sensitive = TRUE;
182 priv->is_expander = FALSE;
183 priv->is_expanded = FALSE;
184 priv->editing = FALSE;
188 gtk_cell_renderer_class_init (GtkCellRendererClass *class)
190 GObjectClass *object_class = G_OBJECT_CLASS (class);
192 object_class->get_property = gtk_cell_renderer_get_property;
193 object_class->set_property = gtk_cell_renderer_set_property;
195 class->render = NULL;
196 class->get_size = NULL;
197 class->get_request_mode = gtk_cell_renderer_real_get_request_mode;
198 class->get_preferred_width = gtk_cell_renderer_real_get_preferred_width;
199 class->get_preferred_height = gtk_cell_renderer_real_get_preferred_height;
200 class->get_preferred_width_for_height = gtk_cell_renderer_real_get_preferred_width_for_height;
201 class->get_preferred_height_for_width = gtk_cell_renderer_real_get_preferred_height_for_width;
202 class->get_aligned_area = gtk_cell_renderer_real_get_aligned_area;
205 * GtkCellRenderer::editing-canceled:
206 * @renderer: the object which received the signal
208 * This signal gets emitted when the user cancels the process of editing a
209 * cell. For example, an editable cell renderer could be written to cancel
210 * editing when the user presses Escape.
212 * See also: gtk_cell_renderer_stop_editing().
216 cell_renderer_signals[EDITING_CANCELED] =
217 g_signal_new (I_("editing-canceled"),
218 G_OBJECT_CLASS_TYPE (object_class),
220 G_STRUCT_OFFSET (GtkCellRendererClass, editing_canceled),
222 _gtk_marshal_VOID__VOID,
226 * GtkCellRenderer::editing-started:
227 * @renderer: the object which received the signal
228 * @editable: the #GtkCellEditable
229 * @path: the path identifying the edited cell
231 * This signal gets emitted when a cell starts to be edited.
232 * The intended use of this signal is to do special setup
233 * on @editable, e.g. adding a #GtkEntryCompletion or setting
234 * up additional columns in a #GtkComboBox.
236 * Note that GTK+ doesn't guarantee that cell renderers will
237 * continue to use the same kind of widget for editing in future
238 * releases, therefore you should check the type of @editable
239 * before doing any specific setup, as in the following example:
242 * text_editing_started (GtkCellRenderer *cell,
243 * GtkCellEditable *editable,
247 * if (GTK_IS_ENTRY (editable))
249 * GtkEntry *entry = GTK_ENTRY (editable);
251 * /* ... create a GtkEntryCompletion */
253 * gtk_entry_set_completion (entry, completion);
260 cell_renderer_signals[EDITING_STARTED] =
261 g_signal_new (I_("editing-started"),
262 G_OBJECT_CLASS_TYPE (object_class),
264 G_STRUCT_OFFSET (GtkCellRendererClass, editing_started),
266 _gtk_marshal_VOID__OBJECT_STRING,
268 GTK_TYPE_CELL_EDITABLE,
271 g_object_class_install_property (object_class,
273 g_param_spec_enum ("mode",
275 P_("Editable mode of the CellRenderer"),
276 GTK_TYPE_CELL_RENDERER_MODE,
277 GTK_CELL_RENDERER_MODE_INERT,
278 GTK_PARAM_READWRITE));
280 g_object_class_install_property (object_class,
282 g_param_spec_boolean ("visible",
284 P_("Display the cell"),
286 GTK_PARAM_READWRITE));
287 g_object_class_install_property (object_class,
289 g_param_spec_boolean ("sensitive",
291 P_("Display the cell sensitive"),
293 GTK_PARAM_READWRITE));
295 g_object_class_install_property (object_class,
297 g_param_spec_float ("xalign",
303 GTK_PARAM_READWRITE));
305 g_object_class_install_property (object_class,
307 g_param_spec_float ("yalign",
313 GTK_PARAM_READWRITE));
315 g_object_class_install_property (object_class,
317 g_param_spec_uint ("xpad",
323 GTK_PARAM_READWRITE));
325 g_object_class_install_property (object_class,
327 g_param_spec_uint ("ypad",
333 GTK_PARAM_READWRITE));
335 g_object_class_install_property (object_class,
337 g_param_spec_int ("width",
339 P_("The fixed width"),
343 GTK_PARAM_READWRITE));
345 g_object_class_install_property (object_class,
347 g_param_spec_int ("height",
349 P_("The fixed height"),
353 GTK_PARAM_READWRITE));
355 g_object_class_install_property (object_class,
357 g_param_spec_boolean ("is-expander",
359 P_("Row has children"),
361 GTK_PARAM_READWRITE));
364 g_object_class_install_property (object_class,
366 g_param_spec_boolean ("is-expanded",
368 P_("Row is an expander row, and is expanded"),
370 GTK_PARAM_READWRITE));
372 g_object_class_install_property (object_class,
373 PROP_CELL_BACKGROUND,
374 g_param_spec_string ("cell-background",
375 P_("Cell background color name"),
376 P_("Cell background color as a string"),
378 GTK_PARAM_WRITABLE));
380 g_object_class_install_property (object_class,
381 PROP_CELL_BACKGROUND_GDK,
382 g_param_spec_boxed ("cell-background-gdk",
383 P_("Cell background color"),
384 P_("Cell background color as a GdkColor"),
386 GTK_PARAM_READWRITE));
388 * GtkCellRenderer:cell-background-rgba:
390 * Cell background as a #GdkRGBA
394 g_object_class_install_property (object_class,
395 PROP_CELL_BACKGROUND_RGBA,
396 g_param_spec_boxed ("cell-background-rgba",
397 P_("Cell background RGBA color"),
398 P_("Cell background color as a GdkRGBA"),
400 GTK_PARAM_READWRITE));
402 g_object_class_install_property (object_class,
404 g_param_spec_boolean ("editing",
406 P_("Whether the cell renderer is currently in editing mode"),
408 GTK_PARAM_READABLE));
411 #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))
413 ADD_SET_PROP ("cell-background-set", PROP_CELL_BACKGROUND_SET,
414 P_("Cell background set"),
415 P_("Whether this tag affects the cell background color"));
417 g_type_class_add_private (class, sizeof (GtkCellRendererPrivate));
421 gtk_cell_renderer_get_property (GObject *object,
426 GtkCellRenderer *cell = GTK_CELL_RENDERER (object);
427 GtkCellRendererPrivate *priv = cell->priv;
432 g_value_set_enum (value, priv->mode);
435 g_value_set_boolean (value, priv->visible);
438 g_value_set_boolean (value, priv->sensitive);
441 g_value_set_boolean (value, priv->editing);
444 g_value_set_float (value, priv->xalign);
447 g_value_set_float (value, priv->yalign);
450 g_value_set_uint (value, priv->xpad);
453 g_value_set_uint (value, priv->ypad);
456 g_value_set_int (value, priv->width);
459 g_value_set_int (value, priv->height);
461 case PROP_IS_EXPANDER:
462 g_value_set_boolean (value, priv->is_expander);
464 case PROP_IS_EXPANDED:
465 g_value_set_boolean (value, priv->is_expanded);
467 case PROP_CELL_BACKGROUND_GDK:
471 color.red = (guint16) (priv->cell_background.red * 65535);
472 color.green = (guint16) (priv->cell_background.green * 65535);
473 color.blue = (guint16) (priv->cell_background.blue * 65535);
475 g_value_set_boxed (value, &color);
478 case PROP_CELL_BACKGROUND_RGBA:
479 g_value_set_boxed (value, &priv->cell_background);
481 case PROP_CELL_BACKGROUND_SET:
482 g_value_set_boolean (value, priv->cell_background_set);
484 case PROP_CELL_BACKGROUND:
486 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, param_id, pspec);
493 gtk_cell_renderer_set_property (GObject *object,
498 GtkCellRenderer *cell = GTK_CELL_RENDERER (object);
499 GtkCellRendererPrivate *priv = cell->priv;
504 priv->mode = g_value_get_enum (value);
507 priv->visible = g_value_get_boolean (value);
510 priv->sensitive = g_value_get_boolean (value);
513 priv->editing = g_value_get_boolean (value);
516 priv->xalign = g_value_get_float (value);
519 priv->yalign = g_value_get_float (value);
522 priv->xpad = g_value_get_uint (value);
525 priv->ypad = g_value_get_uint (value);
528 priv->width = g_value_get_int (value);
531 priv->height = g_value_get_int (value);
533 case PROP_IS_EXPANDER:
534 priv->is_expander = g_value_get_boolean (value);
536 case PROP_IS_EXPANDED:
537 priv->is_expanded = g_value_get_boolean (value);
539 case PROP_CELL_BACKGROUND:
543 if (!g_value_get_string (value))
544 set_cell_bg_color (cell, NULL);
545 else if (gdk_rgba_parse (&rgba, g_value_get_string (value)))
546 set_cell_bg_color (cell, &rgba);
548 g_warning ("Don't know color `%s'", g_value_get_string (value));
550 g_object_notify (object, "cell-background-gdk");
553 case PROP_CELL_BACKGROUND_GDK:
557 color = g_value_get_boxed (value);
562 rgba.red = color->red / 65535.;
563 rgba.green = color->green / 65535.;
564 rgba.blue = color->blue / 65535.;
567 set_cell_bg_color (cell, &rgba);
571 set_cell_bg_color (cell, NULL);
575 case PROP_CELL_BACKGROUND_RGBA:
576 set_cell_bg_color (cell, g_value_get_boxed (value));
578 case PROP_CELL_BACKGROUND_SET:
579 priv->cell_background_set = g_value_get_boolean (value);
582 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, param_id, pspec);
588 set_cell_bg_color (GtkCellRenderer *cell,
591 GtkCellRendererPrivate *priv = cell->priv;
595 if (!priv->cell_background_set)
597 priv->cell_background_set = TRUE;
598 g_object_notify (G_OBJECT (cell), "cell-background-set");
601 priv->cell_background = *rgba;
605 if (priv->cell_background_set)
607 priv->cell_background_set = FALSE;
608 g_object_notify (G_OBJECT (cell), "cell-background-set");
614 * gtk_cell_renderer_get_size:
615 * @cell: a #GtkCellRenderer
616 * @widget: the widget the renderer is rendering to
617 * @cell_area: (allow-none): The area a cell will be allocated, or %NULL
618 * @x_offset: (out) (allow-none): location to return x offset of cell relative to @cell_area, or %NULL
619 * @y_offset: (out) (allow-none): location to return y offset of cell relative to @cell_area, or %NULL
620 * @width: (out) (allow-none): location to return width needed to render a cell, or %NULL
621 * @height: (out) (allow-none): location to return height needed to render a cell, or %NULL
623 * Obtains the width and height needed to render the cell. Used by view
624 * widgets to determine the appropriate size for the cell_area passed to
625 * gtk_cell_renderer_render(). If @cell_area is not %NULL, fills in the
626 * x and y offsets (if set) of the cell relative to this location.
628 * Please note that the values set in @width and @height, as well as those
629 * in @x_offset and @y_offset are inclusive of the xpad and ypad properties.
632 * Deprecated: 3.0: Use gtk_cell_renderer_get_preferred_size() instead.
635 gtk_cell_renderer_get_size (GtkCellRenderer *cell,
637 const GdkRectangle *cell_area,
643 GtkRequisition request;
645 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
647 gtk_cell_renderer_get_preferred_size (cell, widget, &request, NULL);
650 *width = request.width;
653 *height = request.height;
656 _gtk_cell_renderer_calc_offset (cell, cell_area, gtk_widget_get_direction (widget),
657 request.width, request.height, x_offset, y_offset);
661 * gtk_cell_renderer_render:
662 * @cell: a #GtkCellRenderer
663 * @cr: a cairo context to draw to
664 * @widget: the widget owning @window
665 * @background_area: entire cell area (including tree expanders and maybe
666 * padding on the sides)
667 * @cell_area: area normally rendered by a cell renderer
668 * @flags: flags that affect rendering
670 * Invokes the virtual render function of the #GtkCellRenderer. The three
671 * passed-in rectangles are areas in @cr. Most renderers will draw within
672 * @cell_area; the xalign, yalign, xpad, and ypad fields of the #GtkCellRenderer
673 * should be honored with respect to @cell_area. @background_area includes the
674 * blank space around the cell, and also the area containing the tree expander;
675 * so the @background_area rectangles for all cells tile to cover the entire
679 gtk_cell_renderer_render (GtkCellRenderer *cell,
682 const GdkRectangle *background_area,
683 const GdkRectangle *cell_area,
684 GtkCellRendererState flags)
686 gboolean selected = FALSE;
687 GtkCellRendererPrivate *priv = cell->priv;
688 GtkStyleContext *context;
691 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
692 g_return_if_fail (GTK_CELL_RENDERER_GET_CLASS (cell)->render != NULL);
693 g_return_if_fail (cr != NULL);
695 selected = (flags & GTK_CELL_RENDERER_SELECTED) == GTK_CELL_RENDERER_SELECTED;
699 if (priv->cell_background_set && !selected)
701 gdk_cairo_rectangle (cr, background_area);
702 gdk_cairo_set_source_rgba (cr, &priv->cell_background);
706 gdk_cairo_rectangle (cr, background_area);
709 context = gtk_widget_get_style_context (widget);
711 gtk_style_context_save (context);
712 gtk_style_context_add_class (context, GTK_STYLE_CLASS_CELL);
714 state = gtk_cell_renderer_get_state (cell, widget, flags);
715 gtk_style_context_set_state (context, state);
717 GTK_CELL_RENDERER_GET_CLASS (cell)->render (cell,
723 gtk_style_context_restore (context);
728 * gtk_cell_renderer_activate:
729 * @cell: a #GtkCellRenderer
730 * @event: a #GdkEvent
731 * @widget: widget that received the event
732 * @path: widget-dependent string representation of the event location;
733 * e.g. for #GtkTreeView, a string representation of #GtkTreePath
734 * @background_area: background area as passed to gtk_cell_renderer_render()
735 * @cell_area: cell area as passed to gtk_cell_renderer_render()
736 * @flags: render flags
738 * Passes an activate event to the cell renderer for possible processing.
739 * Some cell renderers may use events; for example, #GtkCellRendererToggle
740 * toggles when it gets a mouse click.
742 * Return value: %TRUE if the event was consumed/handled
745 gtk_cell_renderer_activate (GtkCellRenderer *cell,
749 const GdkRectangle *background_area,
750 const GdkRectangle *cell_area,
751 GtkCellRendererState flags)
753 GtkCellRendererPrivate *priv;
755 g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
759 if (priv->mode != GTK_CELL_RENDERER_MODE_ACTIVATABLE)
762 if (GTK_CELL_RENDERER_GET_CLASS (cell)->activate == NULL)
765 return GTK_CELL_RENDERER_GET_CLASS (cell)->activate (cell,
769 (GdkRectangle *) background_area,
770 (GdkRectangle *) cell_area,
775 * gtk_cell_renderer_start_editing:
776 * @cell: a #GtkCellRenderer
777 * @event: a #GdkEvent
778 * @widget: widget that received the event
779 * @path: widget-dependent string representation of the event location;
780 * e.g. for #GtkTreeView, a string representation of #GtkTreePath
781 * @background_area: background area as passed to gtk_cell_renderer_render()
782 * @cell_area: cell area as passed to gtk_cell_renderer_render()
783 * @flags: render flags
785 * Passes an activate event to the cell renderer for possible processing.
787 * Return value: (transfer none): A new #GtkCellEditable, or %NULL
790 gtk_cell_renderer_start_editing (GtkCellRenderer *cell,
794 const GdkRectangle *background_area,
795 const GdkRectangle *cell_area,
796 GtkCellRendererState flags)
799 GtkCellRendererPrivate *priv;
800 GtkCellEditable *editable;
802 g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), NULL);
806 if (priv->mode != GTK_CELL_RENDERER_MODE_EDITABLE)
809 if (GTK_CELL_RENDERER_GET_CLASS (cell)->start_editing == NULL)
812 editable = GTK_CELL_RENDERER_GET_CLASS (cell)->start_editing (cell,
816 (GdkRectangle *) background_area,
817 (GdkRectangle *) cell_area,
821 cell_renderer_signals[EDITING_STARTED], 0,
824 priv->editing = TRUE;
830 * gtk_cell_renderer_set_fixed_size:
831 * @cell: A #GtkCellRenderer
832 * @width: the width of the cell renderer, or -1
833 * @height: the height of the cell renderer, or -1
835 * Sets the renderer size to be explicit, independent of the properties set.
838 gtk_cell_renderer_set_fixed_size (GtkCellRenderer *cell,
842 GtkCellRendererPrivate *priv;
844 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
845 g_return_if_fail (width >= -1 && height >= -1);
849 if ((width != priv->width) || (height != priv->height))
851 g_object_freeze_notify (G_OBJECT (cell));
853 if (width != priv->width)
856 g_object_notify (G_OBJECT (cell), "width");
859 if (height != priv->height)
861 priv->height = height;
862 g_object_notify (G_OBJECT (cell), "height");
865 g_object_thaw_notify (G_OBJECT (cell));
870 * gtk_cell_renderer_get_fixed_size:
871 * @cell: A #GtkCellRenderer
872 * @width: (out) (allow-none): location to fill in with the fixed width of the cell, or %NULL
873 * @height: (out) (allow-none): location to fill in with the fixed height of the cell, or %NULL
875 * Fills in @width and @height with the appropriate size of @cell.
878 gtk_cell_renderer_get_fixed_size (GtkCellRenderer *cell,
882 GtkCellRendererPrivate *priv;
884 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
889 *width = priv->width;
891 *height = priv->height;
895 * gtk_cell_renderer_set_alignment:
896 * @cell: A #GtkCellRenderer
897 * @xalign: the x alignment of the cell renderer
898 * @yalign: the y alignment of the cell renderer
900 * Sets the renderer's alignment within its available space.
905 gtk_cell_renderer_set_alignment (GtkCellRenderer *cell,
909 GtkCellRendererPrivate *priv;
911 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
912 g_return_if_fail (xalign >= 0.0 && xalign <= 1.0);
913 g_return_if_fail (yalign >= 0.0 && yalign <= 1.0);
917 if ((xalign != priv->xalign) || (yalign != priv->yalign))
919 g_object_freeze_notify (G_OBJECT (cell));
921 if (xalign != priv->xalign)
923 priv->xalign = xalign;
924 g_object_notify (G_OBJECT (cell), "xalign");
927 if (yalign != priv->yalign)
929 priv->yalign = yalign;
930 g_object_notify (G_OBJECT (cell), "yalign");
933 g_object_thaw_notify (G_OBJECT (cell));
938 * gtk_cell_renderer_get_alignment:
939 * @cell: A #GtkCellRenderer
940 * @xalign: (out) (allow-none): location to fill in with the x alignment of the cell, or %NULL
941 * @yalign: (out) (allow-none): location to fill in with the y alignment of the cell, or %NULL
943 * Fills in @xalign and @yalign with the appropriate values of @cell.
948 gtk_cell_renderer_get_alignment (GtkCellRenderer *cell,
952 GtkCellRendererPrivate *priv;
954 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
959 *xalign = priv->xalign;
961 *yalign = priv->yalign;
965 * gtk_cell_renderer_set_padding:
966 * @cell: A #GtkCellRenderer
967 * @xpad: the x padding of the cell renderer
968 * @ypad: the y padding of the cell renderer
970 * Sets the renderer's padding.
975 gtk_cell_renderer_set_padding (GtkCellRenderer *cell,
979 GtkCellRendererPrivate *priv;
981 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
982 g_return_if_fail (xpad >= 0 && xpad >= 0);
986 if ((xpad != priv->xpad) || (ypad != priv->ypad))
988 g_object_freeze_notify (G_OBJECT (cell));
990 if (xpad != priv->xpad)
993 g_object_notify (G_OBJECT (cell), "xpad");
996 if (ypad != priv->ypad)
999 g_object_notify (G_OBJECT (cell), "ypad");
1002 g_object_thaw_notify (G_OBJECT (cell));
1007 * gtk_cell_renderer_get_padding:
1008 * @cell: A #GtkCellRenderer
1009 * @xpad: (out) (allow-none): location to fill in with the x padding of the cell, or %NULL
1010 * @ypad: (out) (allow-none): location to fill in with the y padding of the cell, or %NULL
1012 * Fills in @xpad and @ypad with the appropriate values of @cell.
1017 gtk_cell_renderer_get_padding (GtkCellRenderer *cell,
1021 GtkCellRendererPrivate *priv;
1023 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1034 * gtk_cell_renderer_set_visible:
1035 * @cell: A #GtkCellRenderer
1036 * @visible: the visibility of the cell
1038 * Sets the cell renderer's visibility.
1043 gtk_cell_renderer_set_visible (GtkCellRenderer *cell,
1046 GtkCellRendererPrivate *priv;
1048 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1052 if (priv->visible != visible)
1054 priv->visible = visible ? TRUE : FALSE;
1055 g_object_notify (G_OBJECT (cell), "visible");
1060 * gtk_cell_renderer_get_visible:
1061 * @cell: A #GtkCellRenderer
1063 * Returns the cell renderer's visibility.
1065 * Returns: %TRUE if the cell renderer is visible
1070 gtk_cell_renderer_get_visible (GtkCellRenderer *cell)
1072 g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
1074 return cell->priv->visible;
1078 * gtk_cell_renderer_set_sensitive:
1079 * @cell: A #GtkCellRenderer
1080 * @sensitive: the sensitivity of the cell
1082 * Sets the cell renderer's sensitivity.
1087 gtk_cell_renderer_set_sensitive (GtkCellRenderer *cell,
1090 GtkCellRendererPrivate *priv;
1092 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1096 if (priv->sensitive != sensitive)
1098 priv->sensitive = sensitive ? TRUE : FALSE;
1099 g_object_notify (G_OBJECT (cell), "sensitive");
1104 * gtk_cell_renderer_get_sensitive:
1105 * @cell: A #GtkCellRenderer
1107 * Returns the cell renderer's sensitivity.
1109 * Returns: %TRUE if the cell renderer is sensitive
1114 gtk_cell_renderer_get_sensitive (GtkCellRenderer *cell)
1116 g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
1118 return cell->priv->sensitive;
1123 * gtk_cell_renderer_is_activatable:
1124 * @cell: A #GtkCellRenderer
1126 * Checks whether the cell renderer can do something when activated.
1128 * Returns: %TRUE if the cell renderer can do anything when activated
1133 gtk_cell_renderer_is_activatable (GtkCellRenderer *cell)
1135 GtkCellRendererPrivate *priv;
1137 g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
1141 return (priv->visible &&
1142 (priv->mode == GTK_CELL_RENDERER_MODE_EDITABLE ||
1143 priv->mode == GTK_CELL_RENDERER_MODE_ACTIVATABLE));
1148 * gtk_cell_renderer_stop_editing:
1149 * @cell: A #GtkCellRenderer
1150 * @canceled: %TRUE if the editing has been canceled
1152 * Informs the cell renderer that the editing is stopped.
1153 * If @canceled is %TRUE, the cell renderer will emit the
1154 * #GtkCellRenderer::editing-canceled signal.
1156 * This function should be called by cell renderer implementations
1157 * in response to the #GtkCellEditable::editing-done signal of
1163 gtk_cell_renderer_stop_editing (GtkCellRenderer *cell,
1166 GtkCellRendererPrivate *priv;
1168 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1174 priv->editing = FALSE;
1176 g_signal_emit (cell, cell_renderer_signals[EDITING_CANCELED], 0);
1181 gtk_cell_renderer_real_get_preferred_size (GtkCellRenderer *cell,
1183 GtkOrientation orientation,
1187 GtkRequisition min_req;
1189 /* Fallback on the old API to get the size. */
1190 if (GTK_CELL_RENDERER_GET_CLASS (cell)->get_size)
1191 GTK_CELL_RENDERER_GET_CLASS (cell)->get_size (GTK_CELL_RENDERER (cell), widget, NULL, NULL, NULL,
1192 &min_req.width, &min_req.height);
1199 if (orientation == GTK_ORIENTATION_HORIZONTAL)
1202 *minimum_size = min_req.width;
1205 *natural_size = min_req.width;
1210 *minimum_size = min_req.height;
1213 *natural_size = min_req.height;
1217 static GtkSizeRequestMode
1218 gtk_cell_renderer_real_get_request_mode (GtkCellRenderer *cell)
1220 /* By default cell renderers are height-for-width. */
1221 return GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH;
1225 gtk_cell_renderer_real_get_preferred_width (GtkCellRenderer *cell,
1230 gtk_cell_renderer_real_get_preferred_size (cell, widget, GTK_ORIENTATION_HORIZONTAL,
1231 minimum_size, natural_size);
1235 gtk_cell_renderer_real_get_preferred_height (GtkCellRenderer *cell,
1240 gtk_cell_renderer_real_get_preferred_size (cell, widget, GTK_ORIENTATION_VERTICAL,
1241 minimum_size, natural_size);
1246 gtk_cell_renderer_real_get_preferred_height_for_width (GtkCellRenderer *cell,
1249 gint *minimum_height,
1250 gint *natural_height)
1252 /* Fall back on the height reported from ->get_size() */
1253 gtk_cell_renderer_get_preferred_height (cell, widget, minimum_height, natural_height);
1257 gtk_cell_renderer_real_get_preferred_width_for_height (GtkCellRenderer *cell,
1260 gint *minimum_width,
1261 gint *natural_width)
1263 /* Fall back on the width reported from ->get_size() */
1264 gtk_cell_renderer_get_preferred_width (cell, widget, minimum_width, natural_width);
1268 /* Default implementation assumes that a cell renderer will never use more
1269 * space than its natural size (this is fine for toggles and pixbufs etc
1270 * but needs to be overridden from wrapping/ellipsizing text renderers) */
1272 gtk_cell_renderer_real_get_aligned_area (GtkCellRenderer *cell,
1274 GtkCellRendererState flags,
1275 const GdkRectangle *cell_area,
1276 GdkRectangle *aligned_area)
1278 gint opposite_size, x_offset, y_offset;
1281 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1282 g_return_if_fail (GTK_IS_WIDGET (widget));
1283 g_return_if_fail (cell_area != NULL);
1284 g_return_if_fail (aligned_area != NULL);
1286 *aligned_area = *cell_area;
1288 /* Trim up the aligned size */
1289 if (gtk_cell_renderer_get_request_mode (cell) == GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH)
1291 gtk_cell_renderer_get_preferred_width (cell, widget,
1292 NULL, &natural_size);
1294 aligned_area->width = MIN (aligned_area->width, natural_size);
1296 gtk_cell_renderer_get_preferred_height_for_width (cell, widget,
1297 aligned_area->width,
1298 NULL, &opposite_size);
1300 aligned_area->height = MIN (opposite_size, aligned_area->height);
1304 gtk_cell_renderer_get_preferred_height (cell, widget,
1305 NULL, &natural_size);
1307 aligned_area->height = MIN (aligned_area->width, natural_size);
1309 gtk_cell_renderer_get_preferred_width_for_height (cell, widget,
1310 aligned_area->height,
1311 NULL, &opposite_size);
1313 aligned_area->width = MIN (opposite_size, aligned_area->width);
1316 /* offset the cell position */
1317 _gtk_cell_renderer_calc_offset (cell, cell_area,
1318 gtk_widget_get_direction (widget),
1319 aligned_area->width,
1320 aligned_area->height,
1321 &x_offset, &y_offset);
1323 aligned_area->x += x_offset;
1324 aligned_area->y += y_offset;
1328 /* An internal convenience function for some containers to peek at the
1329 * cell alignment in a target allocation (used to draw focus and align
1330 * cells in the icon view).
1332 * Note this is only a trivial 'align * (allocation - request)' operation.
1335 _gtk_cell_renderer_calc_offset (GtkCellRenderer *cell,
1336 const GdkRectangle *cell_area,
1337 GtkTextDirection direction,
1343 GtkCellRendererPrivate *priv;
1345 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1346 g_return_if_fail (cell_area != NULL);
1347 g_return_if_fail (x_offset || y_offset);
1353 *x_offset = (((direction == GTK_TEXT_DIR_RTL) ?
1354 (1.0 - priv->xalign) : priv->xalign) *
1355 (cell_area->width - width));
1356 *x_offset = MAX (*x_offset, 0);
1360 *y_offset = (priv->yalign *
1361 (cell_area->height - height));
1362 *y_offset = MAX (*y_offset, 0);
1367 * gtk_cell_renderer_get_request_mode:
1368 * @cell: a #GtkCellRenderer instance
1370 * Gets whether the cell renderer prefers a height-for-width layout
1371 * or a width-for-height layout.
1373 * Returns: The #GtkSizeRequestMode preferred by this renderer.
1378 gtk_cell_renderer_get_request_mode (GtkCellRenderer *cell)
1380 g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
1382 return GTK_CELL_RENDERER_GET_CLASS (cell)->get_request_mode (cell);
1386 * gtk_cell_renderer_get_preferred_width:
1387 * @cell: a #GtkCellRenderer instance
1388 * @widget: the #GtkWidget this cell will be rendering to
1389 * @minimum_size: (out) (allow-none): location to store the minimum size, or %NULL
1390 * @natural_size: (out) (allow-none): location to store the natural size, or %NULL
1392 * Retreives a renderer's natural size when rendered to @widget.
1397 gtk_cell_renderer_get_preferred_width (GtkCellRenderer *cell,
1402 GtkCellRendererClass *klass;
1405 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1406 g_return_if_fail (GTK_IS_WIDGET (widget));
1407 g_return_if_fail (NULL != minimum_size || NULL != natural_size);
1409 gtk_cell_renderer_get_fixed_size (GTK_CELL_RENDERER (cell), &width, NULL);
1413 klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1414 klass->get_preferred_width (cell, widget, minimum_size, natural_size);
1419 *minimum_size = width;
1421 *natural_size = width;
1424 #if DEBUG_CELL_SIZE_REQUEST
1425 g_message ("%s returning minimum width: %d and natural width: %d",
1426 G_OBJECT_TYPE_NAME (cell),
1427 minimum_size ? *minimum_size : 20000,
1428 natural_size ? *natural_size : 20000);
1434 * gtk_cell_renderer_get_preferred_height:
1435 * @cell: a #GtkCellRenderer instance
1436 * @widget: the #GtkWidget this cell will be rendering to
1437 * @minimum_size: (out) (allow-none): location to store the minimum size, or %NULL
1438 * @natural_size: (out) (allow-none): location to store the natural size, or %NULL
1440 * Retreives a renderer's natural size when rendered to @widget.
1445 gtk_cell_renderer_get_preferred_height (GtkCellRenderer *cell,
1450 GtkCellRendererClass *klass;
1453 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1454 g_return_if_fail (GTK_IS_WIDGET (widget));
1455 g_return_if_fail (NULL != minimum_size || NULL != natural_size);
1457 gtk_cell_renderer_get_fixed_size (GTK_CELL_RENDERER (cell), NULL, &height);
1461 klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1462 klass->get_preferred_height (cell, widget, minimum_size, natural_size);
1467 *minimum_size = height;
1469 *natural_size = height;
1472 #if DEBUG_CELL_SIZE_REQUEST
1473 g_message ("%s returning minimum height: %d and natural height: %d",
1474 G_OBJECT_TYPE_NAME (cell),
1475 minimum_size ? *minimum_size : 20000,
1476 natural_size ? *natural_size : 20000);
1482 * gtk_cell_renderer_get_preferred_width_for_height:
1483 * @cell: a #GtkCellRenderer instance
1484 * @widget: the #GtkWidget this cell will be rendering to
1485 * @height: the size which is available for allocation
1486 * @minimum_width: (out) (allow-none): location for storing the minimum size, or %NULL
1487 * @natural_width: (out) (allow-none): location for storing the preferred size, or %NULL
1489 * Retreives a cell renderers's minimum and natural width if it were rendered to
1490 * @widget with the specified @height.
1495 gtk_cell_renderer_get_preferred_width_for_height (GtkCellRenderer *cell,
1498 gint *minimum_width,
1499 gint *natural_width)
1501 GtkCellRendererClass *klass;
1504 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1505 g_return_if_fail (GTK_IS_WIDGET (widget));
1506 g_return_if_fail (NULL != minimum_width || NULL != natural_width);
1508 gtk_cell_renderer_get_fixed_size (GTK_CELL_RENDERER (cell), &width, NULL);
1512 klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1513 klass->get_preferred_width_for_height (cell, widget, height, minimum_width, natural_width);
1518 *minimum_width = width;
1520 *natural_width = width;
1523 #if DEBUG_CELL_SIZE_REQUEST
1524 g_message ("%s width for height: %d is minimum %d and natural: %d",
1525 G_OBJECT_TYPE_NAME (cell), height,
1526 minimum_width ? *minimum_width : 20000,
1527 natural_width ? *natural_width : 20000);
1532 * gtk_cell_renderer_get_preferred_height_for_width:
1533 * @cell: a #GtkCellRenderer instance
1534 * @widget: the #GtkWidget this cell will be rendering to
1535 * @width: the size which is available for allocation
1536 * @minimum_height: (out) (allow-none): location for storing the minimum size, or %NULL
1537 * @natural_height: (out) (allow-none): location for storing the preferred size, or %NULL
1539 * Retreives a cell renderers's minimum and natural height if it were rendered to
1540 * @widget with the specified @width.
1545 gtk_cell_renderer_get_preferred_height_for_width (GtkCellRenderer *cell,
1548 gint *minimum_height,
1549 gint *natural_height)
1551 GtkCellRendererClass *klass;
1554 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1555 g_return_if_fail (GTK_IS_WIDGET (widget));
1556 g_return_if_fail (NULL != minimum_height || NULL != natural_height);
1558 gtk_cell_renderer_get_fixed_size (GTK_CELL_RENDERER (cell), NULL, &height);
1562 klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1563 klass->get_preferred_height_for_width (cell, widget, width, minimum_height, natural_height);
1568 *minimum_height = height;
1570 *natural_height = height;
1573 #if DEBUG_CELL_SIZE_REQUEST
1574 g_message ("%s height for width: %d is minimum %d and natural: %d",
1575 G_OBJECT_TYPE_NAME (cell), width,
1576 minimum_height ? *minimum_height : 20000,
1577 natural_height ? *natural_height : 20000);
1582 * gtk_cell_renderer_get_preferred_size:
1583 * @cell: a #GtkCellRenderer instance
1584 * @widget: the #GtkWidget this cell will be rendering to
1585 * @minimum_size: (out) (allow-none): location for storing the minimum size, or %NULL
1586 * @natural_size: (out) (allow-none): location for storing the natural size, or %NULL
1588 * Retrieves the minimum and natural size of a cell taking
1589 * into account the widget's preference for height-for-width management.
1594 gtk_cell_renderer_get_preferred_size (GtkCellRenderer *cell,
1596 GtkRequisition *minimum_size,
1597 GtkRequisition *natural_size)
1599 gint min_width, nat_width;
1600 gint min_height, nat_height;
1602 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1604 if (gtk_cell_renderer_get_request_mode (cell) == GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH)
1606 gtk_cell_renderer_get_preferred_width (cell, widget, &min_width, &nat_width);
1610 minimum_size->width = min_width;
1611 gtk_cell_renderer_get_preferred_height_for_width (cell, widget, min_width,
1612 &minimum_size->height, NULL);
1617 natural_size->width = nat_width;
1618 gtk_cell_renderer_get_preferred_height_for_width (cell, widget, nat_width,
1619 NULL, &natural_size->height);
1622 else /* GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT */
1624 gtk_cell_renderer_get_preferred_height (cell, widget, &min_height, &nat_height);
1628 minimum_size->height = min_height;
1629 gtk_cell_renderer_get_preferred_width_for_height (cell, widget, min_height,
1630 &minimum_size->width, NULL);
1635 natural_size->height = nat_height;
1636 gtk_cell_renderer_get_preferred_width_for_height (cell, widget, nat_height,
1637 NULL, &natural_size->width);
1643 * gtk_cell_renderer_get_aligned_area:
1644 * @cell: a #GtkCellRenderer instance
1645 * @widget: the #GtkWidget this cell will be rendering to
1646 * @flags: render flags
1647 * @cell_area: cell area which would be passed to gtk_cell_renderer_render()
1648 * @aligned_area: (out): the return location for the space inside @cell_area
1649 * that would acually be used to render.
1651 * Gets the aligned area used by @cell inside @cell_area. Used for finding
1652 * the appropriate edit and focus rectangle.
1657 gtk_cell_renderer_get_aligned_area (GtkCellRenderer *cell,
1659 GtkCellRendererState flags,
1660 const GdkRectangle *cell_area,
1661 GdkRectangle *aligned_area)
1663 GtkCellRendererClass *klass;
1665 g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1666 g_return_if_fail (GTK_IS_WIDGET (widget));
1667 g_return_if_fail (cell_area != NULL);
1668 g_return_if_fail (aligned_area != NULL);
1670 klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1671 klass->get_aligned_area (cell, widget, flags, cell_area, aligned_area);
1673 g_assert (aligned_area->x >= cell_area->x && aligned_area->x <= cell_area->x + cell_area->width);
1674 g_assert (aligned_area->y >= cell_area->y && aligned_area->y <= cell_area->y + cell_area->height);
1675 g_assert ((aligned_area->x - cell_area->x) + aligned_area->width <= cell_area->width);
1676 g_assert ((aligned_area->y - cell_area->y) + aligned_area->height <= cell_area->height);
1680 * gtk_cell_renderer_get_state:
1681 * @cell: a #GtkCellRenderer, or %NULL
1682 * @widget: a #GtkWidget, or %NULL
1683 * @cell_state: cell renderer state
1685 * Translates the cell renderer state to #GtkStateFlags,
1686 * based on the cell renderer and widget sensitivity, and
1687 * the given #GtkCellRendererState.
1689 * Returns: the widget state flags applying to @cell
1694 gtk_cell_renderer_get_state (GtkCellRenderer *cell,
1696 GtkCellRendererState cell_state)
1698 GtkStateFlags state = 0;
1700 g_return_val_if_fail (!cell || GTK_IS_CELL_RENDERER (cell), 0);
1701 g_return_val_if_fail (!widget || GTK_IS_WIDGET (widget), 0);
1703 if ((widget && !gtk_widget_is_sensitive (widget)) ||
1704 (cell && !gtk_cell_renderer_get_sensitive (cell)) ||
1705 (cell_state & GTK_CELL_RENDERER_INSENSITIVE) != 0)
1707 state |= GTK_STATE_FLAG_INSENSITIVE;
1711 if ((widget && gtk_widget_has_focus (widget)) &&
1712 (cell_state & GTK_CELL_RENDERER_FOCUSED) != 0)
1713 state |= GTK_STATE_FLAG_FOCUSED;
1715 if ((cell_state & GTK_CELL_RENDERER_PRELIT) != 0)
1716 state |= GTK_STATE_FLAG_PRELIGHT;
1719 if ((cell_state & GTK_CELL_RENDERER_SELECTED) != 0)
1720 state |= GTK_STATE_FLAG_SELECTED;