Pileus Git - ~andy/gtk/blob - gtk/gtkcellrenderer.c

   1 /* gtkcellrenderer.c
   2  * Copyright (C) 2000  Red Hat, Inc. Jonathan Blandford
   3  *
   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.
   8  *
   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.
  13  *
  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.
  18  */
  19
  20 #include "config.h"
  21 #include "gtkcellrenderer.h"
  22 #include "gtkintl.h"
  23 #include "gtkmarshalers.h"
  24 #include "gtkprivate.h"
  25 #include "gtktreeprivate.h"
  26
  27
  28 /**
  29  * SECTION:gtkcellrenderer
  30  * @Short_description: An object for rendering a single cell
  31  * @Title: GtkCellRenderer
  32  * @See_also: #GtkCellRendererText, #GtkCellRendererPixbuf, #GtkCellRendererToggle
  33  *
  34  * The #GtkCellRenderer is a base class of a set of objects used for
  35  * rendering a cell to a #cairo_t.  These objects are used primarily by
  36  * the #GtkTreeView widget, though they aren't tied to them in any
  37  * specific way.  It is worth noting that #GtkCellRenderer is not a
  38  * #GtkWidget and cannot be treated as such.
  39  *
  40  * The primary use of a #GtkCellRenderer is for drawing a certain graphical
  41  * elements on a #cairo_t. Typically, one cell renderer is used to
  42  * draw many cells on the screen.  To this extent, it isn't expected that a
  43  * CellRenderer keep any permanent state around.  Instead, any state is set
  44  * just prior to use using #GObject<!-- -->s property system.  Then, the
  45  * cell is measured using gtk_cell_renderer_get_size(). Finally, the cell
  46  * is rendered in the correct location using gtk_cell_renderer_render().
  47  *
  48  * There are a number of rules that must be followed when writing a new
  49  * #GtkCellRenderer.  First and formost, it's important that a certain set
  50  * of properties will always yield a cell renderer of the same size,
  51  * barring a #GtkStyle change.  The #GtkCellRenderer also has a number of
  52  * generic properties that are expected to be honored by all children.
  53  *
  54  * Beyond merely rendering a cell, cell renderers can optionally
  55  * provide active user interface elements. A cell renderer can be
  56  * <firstterm>activatable</firstterm> like #GtkCellRendererToggle,
  57  * which toggles when it gets activated by a mouse click, or it can be
  58  * <firstterm>editable</firstterm> like #GtkCellRendererText, which
  59  * allows the user to edit the text using a #GtkEntry.
  60  * To make a cell renderer activatable or editable, you have to
  61  * implement the #GtkCellRendererClass.activate or
  62  * #GtkCellRendererClass.start_editing virtual functions, respectively.
  63  */
  64
  65
  66 #define DEBUG_CELL_SIZE_REQUEST 0
  67
  68 static void gtk_cell_renderer_init          (GtkCellRenderer      *cell);
  69 static void gtk_cell_renderer_class_init    (GtkCellRendererClass *class);
  70 static void gtk_cell_renderer_get_property  (GObject              *object,
  71                                              guint                 param_id,
  72                                              GValue               *value,
  73                                              GParamSpec           *pspec);
  74 static void gtk_cell_renderer_set_property  (GObject              *object,
  75                                              guint                 param_id,
  76                                              const GValue         *value,
  77                                              GParamSpec           *pspec);
  78 static void set_cell_bg_color               (GtkCellRenderer      *cell,
  79                                              GdkRGBA              *rgba);
  80
  81 /* Fallback GtkCellRenderer    implementation to use remaining ->get_size() implementations */
  82 static void gtk_cell_renderer_real_get_preferred_width           (GtkCellRenderer         *cell,
  83                                                                   GtkWidget               *widget,
  84                                                                   gint                    *minimum_size,
  85                                                                   gint                    *natural_size);
  86 static void gtk_cell_renderer_real_get_preferred_height          (GtkCellRenderer         *cell,
  87                                                                   GtkWidget               *widget,
  88                                                                   gint                    *minimum_size,
  89                                                                   gint                    *natural_size);
  90 static void gtk_cell_renderer_real_get_preferred_height_for_width(GtkCellRenderer         *cell,
  91                                                                   GtkWidget               *widget,
  92                                                                   gint                     width,
  93                                                                   gint                    *minimum_height,
  94                                                                   gint                    *natural_height);
  95 static void gtk_cell_renderer_real_get_preferred_width_for_height(GtkCellRenderer         *cell,
  96                                                                   GtkWidget               *widget,
  97                                                                   gint                     height,
  98                                                                   gint                    *minimum_width,
  99                                                                   gint                    *natural_width);
 100 static void gtk_cell_renderer_real_get_aligned_area              (GtkCellRenderer         *cell,
 101                                                                   GtkWidget               *widget,
 102                                                                   GtkCellRendererState     flags,
 103                                                                   const GdkRectangle      *cell_area,
 104                                                                   GdkRectangle            *aligned_area);
 105
 106
 107 struct _GtkCellRendererPrivate
 108 {
 109   gfloat xalign;
 110   gfloat yalign;
 111
 112   gint width;
 113   gint height;
 114
 115   guint16 xpad;
 116   guint16 ypad;
 117
 118   guint mode                : 2;
 119   guint visible             : 1;
 120   guint is_expander         : 1;
 121   guint is_expanded         : 1;
 122   guint cell_background_set : 1;
 123   guint sensitive           : 1;
 124   guint editing             : 1;
 125
 126   GdkRGBA cell_background;
 127 };
 128
 129
 130 enum {
 131   PROP_0,
 132   PROP_MODE,
 133   PROP_VISIBLE,
 134   PROP_SENSITIVE,
 135   PROP_XALIGN,
 136   PROP_YALIGN,
 137   PROP_XPAD,
 138   PROP_YPAD,
 139   PROP_WIDTH,
 140   PROP_HEIGHT,
 141   PROP_IS_EXPANDER,
 142   PROP_IS_EXPANDED,
 143   PROP_CELL_BACKGROUND,
 144   PROP_CELL_BACKGROUND_GDK,
 145   PROP_CELL_BACKGROUND_RGBA,
 146   PROP_CELL_BACKGROUND_SET,
 147   PROP_EDITING
 148 };
 149
 150 /* Signal IDs */
 151 enum {
 152   EDITING_CANCELED,
 153   EDITING_STARTED,
 154   LAST_SIGNAL
 155 };
 156
 157 static guint  cell_renderer_signals[LAST_SIGNAL] = { 0 };
 158
 159 G_DEFINE_ABSTRACT_TYPE(GtkCellRenderer, gtk_cell_renderer, G_TYPE_INITIALLY_UNOWNED)
 160
 161 static void
 162 gtk_cell_renderer_init (GtkCellRenderer *cell)
 163 {
 164   GtkCellRendererPrivate *priv;
 165
 166   cell->priv = G_TYPE_INSTANCE_GET_PRIVATE (cell,
 167                                             GTK_TYPE_CELL_RENDERER,
 168                                             GtkCellRendererPrivate);
 169   priv = cell->priv;
 170
 171   priv->mode = GTK_CELL_RENDERER_MODE_INERT;
 172   priv->visible = TRUE;
 173   priv->width = -1;
 174   priv->height = -1;
 175   priv->xalign = 0.5;
 176   priv->yalign = 0.5;
 177   priv->xpad = 0;
 178   priv->ypad = 0;
 179   priv->sensitive = TRUE;
 180   priv->is_expander = FALSE;
 181   priv->is_expanded = FALSE;
 182   priv->editing = FALSE;
 183 }
 184
 185 static void
 186 gtk_cell_renderer_class_init (GtkCellRendererClass *class)
 187 {
 188   GObjectClass *object_class = G_OBJECT_CLASS (class);
 189
 190   object_class->get_property = gtk_cell_renderer_get_property;
 191   object_class->set_property = gtk_cell_renderer_set_property;
 192
 193   class->render = NULL;
 194   class->get_size = NULL;
 195   class->get_preferred_width            = gtk_cell_renderer_real_get_preferred_width;
 196   class->get_preferred_height           = gtk_cell_renderer_real_get_preferred_height;
 197   class->get_preferred_width_for_height = gtk_cell_renderer_real_get_preferred_width_for_height;
 198   class->get_preferred_height_for_width = gtk_cell_renderer_real_get_preferred_height_for_width;
 199   class->get_aligned_area               = gtk_cell_renderer_real_get_aligned_area;
 200
 201   /**
 202    * GtkCellRenderer::editing-canceled:
 203    * @renderer: the object which received the signal
 204    *
 205    * This signal gets emitted when the user cancels the process of editing a
 206    * cell.  For example, an editable cell renderer could be written to cancel
 207    * editing when the user presses Escape.
 208    *
 209    * See also: gtk_cell_renderer_stop_editing().
 210    *
 211    * Since: 2.4
 212    */
 213   cell_renderer_signals[EDITING_CANCELED] =
 214     g_signal_new (I_("editing-canceled"),
 215                   G_OBJECT_CLASS_TYPE (object_class),
 216                   G_SIGNAL_RUN_FIRST,
 217                   G_STRUCT_OFFSET (GtkCellRendererClass, editing_canceled),
 218                   NULL, NULL,
 219                   _gtk_marshal_VOID__VOID,
 220                   G_TYPE_NONE, 0);
 221
 222   /**
 223    * GtkCellRenderer::editing-started:
 224    * @renderer: the object which received the signal
 225    * @editable: the #GtkCellEditable
 226    * @path: the path identifying the edited cell
 227    *
 228    * This signal gets emitted when a cell starts to be edited.
 229    * The intended use of this signal is to do special setup
 230    * on @editable, e.g. adding a #GtkEntryCompletion or setting
 231    * up additional columns in a #GtkComboBox.
 232    *
 233    * Note that GTK+ doesn't guarantee that cell renderers will
 234    * continue to use the same kind of widget for editing in future
 235    * releases, therefore you should check the type of @editable
 236    * before doing any specific setup, as in the following example:
 237    * |[
 238    * static void
 239    * text_editing_started (GtkCellRenderer *cell,
 240    *                       GtkCellEditable *editable,
 241    *                       const gchar     *path,
 242    *                       gpointer         data)
 243    * {
 244    *   if (GTK_IS_ENTRY (editable))
 245    *     {
 246    *       GtkEntry *entry = GTK_ENTRY (editable);
 247    *
 248    *       /&ast; ... create a GtkEntryCompletion &ast;/
 249    *
 250    *       gtk_entry_set_completion (entry, completion);
 251    *     }
 252    * }
 253    * ]|
 254    *
 255    * Since: 2.6
 256    */
 257   cell_renderer_signals[EDITING_STARTED] =
 258     g_signal_new (I_("editing-started"),
 259                   G_OBJECT_CLASS_TYPE (object_class),
 260                   G_SIGNAL_RUN_FIRST,
 261                   G_STRUCT_OFFSET (GtkCellRendererClass, editing_started),
 262                   NULL, NULL,
 263                   _gtk_marshal_VOID__OBJECT_STRING,
 264                   G_TYPE_NONE, 2,
 265                   GTK_TYPE_CELL_EDITABLE,
 266                   G_TYPE_STRING);
 267
 268   g_object_class_install_property (object_class,
 269                                    PROP_MODE,
 270                                    g_param_spec_enum ("mode",
 271                                                       P_("mode"),
 272                                                       P_("Editable mode of the CellRenderer"),
 273                                                       GTK_TYPE_CELL_RENDERER_MODE,
 274                                                       GTK_CELL_RENDERER_MODE_INERT,
 275                                                       GTK_PARAM_READWRITE));
 276
 277   g_object_class_install_property (object_class,
 278                                    PROP_VISIBLE,
 279                                    g_param_spec_boolean ("visible",
 280                                                          P_("visible"),
 281                                                          P_("Display the cell"),
 282                                                          TRUE,
 283                                                          GTK_PARAM_READWRITE));
 284   g_object_class_install_property (object_class,
 285                                    PROP_SENSITIVE,
 286                                    g_param_spec_boolean ("sensitive",
 287                                                          P_("Sensitive"),
 288                                                          P_("Display the cell sensitive"),
 289                                                          TRUE,
 290                                                          GTK_PARAM_READWRITE));
 291
 292   g_object_class_install_property (object_class,
 293                                    PROP_XALIGN,
 294                                    g_param_spec_float ("xalign",
 295                                                        P_("xalign"),
 296                                                        P_("The x-align"),
 297                                                        0.0,
 298                                                        1.0,
 299                                                        0.5,
 300                                                        GTK_PARAM_READWRITE));
 301
 302   g_object_class_install_property (object_class,
 303                                    PROP_YALIGN,
 304                                    g_param_spec_float ("yalign",
 305                                                        P_("yalign"),
 306                                                        P_("The y-align"),
 307                                                        0.0,
 308                                                        1.0,
 309                                                        0.5,
 310                                                        GTK_PARAM_READWRITE));
 311
 312   g_object_class_install_property (object_class,
 313                                    PROP_XPAD,
 314                                    g_param_spec_uint ("xpad",
 315                                                       P_("xpad"),
 316                                                       P_("The xpad"),
 317                                                       0,
 318                                                       G_MAXUINT,
 319                                                       0,
 320                                                       GTK_PARAM_READWRITE));
 321
 322   g_object_class_install_property (object_class,
 323                                    PROP_YPAD,
 324                                    g_param_spec_uint ("ypad",
 325                                                       P_("ypad"),
 326                                                       P_("The ypad"),
 327                                                       0,
 328                                                       G_MAXUINT,
 329                                                       0,
 330                                                       GTK_PARAM_READWRITE));
 331
 332   g_object_class_install_property (object_class,
 333                                    PROP_WIDTH,
 334                                    g_param_spec_int ("width",
 335                                                      P_("width"),
 336                                                      P_("The fixed width"),
 337                                                      -1,
 338                                                      G_MAXINT,
 339                                                      -1,
 340                                                      GTK_PARAM_READWRITE));
 341
 342   g_object_class_install_property (object_class,
 343                                    PROP_HEIGHT,
 344                                    g_param_spec_int ("height",
 345                                                      P_("height"),
 346                                                      P_("The fixed height"),
 347                                                      -1,
 348                                                      G_MAXINT,
 349                                                      -1,
 350                                                      GTK_PARAM_READWRITE));
 351
 352   g_object_class_install_property (object_class,
 353                                    PROP_IS_EXPANDER,
 354                                    g_param_spec_boolean ("is-expander",
 355                                                          P_("Is Expander"),
 356                                                          P_("Row has children"),
 357                                                          FALSE,
 358                                                          GTK_PARAM_READWRITE));
 359
 360
 361   g_object_class_install_property (object_class,
 362                                    PROP_IS_EXPANDED,
 363                                    g_param_spec_boolean ("is-expanded",
 364                                                          P_("Is Expanded"),
 365                                                          P_("Row is an expander row, and is expanded"),
 366                                                          FALSE,
 367                                                          GTK_PARAM_READWRITE));
 368
 369   g_object_class_install_property (object_class,
 370                                    PROP_CELL_BACKGROUND,
 371                                    g_param_spec_string ("cell-background",
 372                                                         P_("Cell background color name"),
 373                                                         P_("Cell background color as a string"),
 374                                                         NULL,
 375                                                         GTK_PARAM_WRITABLE));
 376
 377   g_object_class_install_property (object_class,
 378                                    PROP_CELL_BACKGROUND_GDK,
 379                                    g_param_spec_boxed ("cell-background-gdk",
 380                                                        P_("Cell background color"),
 381                                                        P_("Cell background color as a GdkColor"),
 382                                                        GDK_TYPE_COLOR,
 383                                                        GTK_PARAM_READWRITE));
 384   /**
 385    * GtkCellRenderer:cell-background-rgba:
 386    *
 387    * Cell background as a #GdkRGBA
 388    *
 389    * Since: 3.0
 390    */
 391   g_object_class_install_property (object_class,
 392                                    PROP_CELL_BACKGROUND_RGBA,
 393                                    g_param_spec_boxed ("cell-background-rgba",
 394                                                        P_("Cell background RGBA color"),
 395                                                        P_("Cell background color as a GdkRGBA"),
 396                                                        GDK_TYPE_RGBA,
 397                                                        GTK_PARAM_READWRITE));
 398
 399   g_object_class_install_property (object_class,
 400                                    PROP_EDITING,
 401                                    g_param_spec_boolean ("editing",
 402                                                          P_("Editing"),
 403                                                          P_("Whether the cell renderer is currently in editing mode"),
 404                                                          FALSE,
 405                                                          GTK_PARAM_READABLE));
 406
 407
 408 #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))
 409
 410   ADD_SET_PROP ("cell-background-set", PROP_CELL_BACKGROUND_SET,
 411                 P_("Cell background set"),
 412                 P_("Whether this tag affects the cell background color"));
 413
 414   g_type_class_add_private (class, sizeof (GtkCellRendererPrivate));
 415 }
 416
 417 static void
 418 gtk_cell_renderer_get_property (GObject     *object,
 419                                 guint        param_id,
 420                                 GValue      *value,
 421                                 GParamSpec  *pspec)
 422 {
 423   GtkCellRenderer *cell = GTK_CELL_RENDERER (object);
 424   GtkCellRendererPrivate *priv = cell->priv;
 425
 426   switch (param_id)
 427     {
 428     case PROP_MODE:
 429       g_value_set_enum (value, priv->mode);
 430       break;
 431     case PROP_VISIBLE:
 432       g_value_set_boolean (value, priv->visible);
 433       break;
 434     case PROP_SENSITIVE:
 435       g_value_set_boolean (value, priv->sensitive);
 436       break;
 437     case PROP_EDITING:
 438       g_value_set_boolean (value, priv->editing);
 439       break;
 440     case PROP_XALIGN:
 441       g_value_set_float (value, priv->xalign);
 442       break;
 443     case PROP_YALIGN:
 444       g_value_set_float (value, priv->yalign);
 445       break;
 446     case PROP_XPAD:
 447       g_value_set_uint (value, priv->xpad);
 448       break;
 449     case PROP_YPAD:
 450       g_value_set_uint (value, priv->ypad);
 451       break;
 452     case PROP_WIDTH:
 453       g_value_set_int (value, priv->width);
 454       break;
 455     case PROP_HEIGHT:
 456       g_value_set_int (value, priv->height);
 457       break;
 458     case PROP_IS_EXPANDER:
 459       g_value_set_boolean (value, priv->is_expander);
 460       break;
 461     case PROP_IS_EXPANDED:
 462       g_value_set_boolean (value, priv->is_expanded);
 463       break;
 464     case PROP_CELL_BACKGROUND_GDK:
 465       {
 466         GdkColor color;
 467
 468         color.red = (guint16) (priv->cell_background.red * 65535);
 469         color.green = (guint16) (priv->cell_background.green * 65535);
 470         color.blue = (guint16) (priv->cell_background.blue * 65535);
 471
 472         g_value_set_boxed (value, &color);
 473       }
 474       break;
 475     case PROP_CELL_BACKGROUND_RGBA:
 476       g_value_set_boxed (value, &priv->cell_background);
 477       break;
 478     case PROP_CELL_BACKGROUND_SET:
 479       g_value_set_boolean (value, priv->cell_background_set);
 480       break;
 481     case PROP_CELL_BACKGROUND:
 482     default:
 483       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, param_id, pspec);
 484       break;
 485     }
 486
 487 }
 488
 489 static void
 490 gtk_cell_renderer_set_property (GObject      *object,
 491                                 guint         param_id,
 492                                 const GValue *value,
 493                                 GParamSpec   *pspec)
 494 {
 495   GtkCellRenderer *cell = GTK_CELL_RENDERER (object);
 496   GtkCellRendererPrivate *priv = cell->priv;
 497
 498   switch (param_id)
 499     {
 500     case PROP_MODE:
 501       priv->mode = g_value_get_enum (value);
 502       break;
 503     case PROP_VISIBLE:
 504       priv->visible = g_value_get_boolean (value);
 505       break;
 506     case PROP_SENSITIVE:
 507       priv->sensitive = g_value_get_boolean (value);
 508       break;
 509     case PROP_EDITING:
 510       priv->editing = g_value_get_boolean (value);
 511       break;
 512     case PROP_XALIGN:
 513       priv->xalign = g_value_get_float (value);
 514       break;
 515     case PROP_YALIGN:
 516       priv->yalign = g_value_get_float (value);
 517       break;
 518     case PROP_XPAD:
 519       priv->xpad = g_value_get_uint (value);
 520       break;
 521     case PROP_YPAD:
 522       priv->ypad = g_value_get_uint (value);
 523       break;
 524     case PROP_WIDTH:
 525       priv->width = g_value_get_int (value);
 526       break;
 527     case PROP_HEIGHT:
 528       priv->height = g_value_get_int (value);
 529       break;
 530     case PROP_IS_EXPANDER:
 531       priv->is_expander = g_value_get_boolean (value);
 532       break;
 533     case PROP_IS_EXPANDED:
 534       priv->is_expanded = g_value_get_boolean (value);
 535       break;
 536     case PROP_CELL_BACKGROUND:
 537       {
 538         GdkRGBA rgba;
 539
 540         if (!g_value_get_string (value))
 541           set_cell_bg_color (cell, NULL);
 542         else if (gdk_rgba_parse (&rgba, g_value_get_string (value)))
 543           set_cell_bg_color (cell, &rgba);
 544         else
 545           g_warning ("Don't know color `%s'", g_value_get_string (value));
 546
 547         g_object_notify (object, "cell-background-gdk");
 548       }
 549       break;
 550     case PROP_CELL_BACKGROUND_GDK:
 551       {
 552         GdkColor *color;
 553
 554         color = g_value_get_boxed (value);
 555         if (color)
 556           {
 557             GdkRGBA rgba;
 558
 559             rgba.red = color->red / 65535.;
 560             rgba.green = color->green / 65535.;
 561             rgba.blue = color->blue / 65535.;
 562             rgba.alpha = 1;
 563
 564             set_cell_bg_color (cell, &rgba);
 565           }
 566         else
 567           {
 568             set_cell_bg_color (cell, NULL);
 569           }
 570       }
 571       break;
 572     case PROP_CELL_BACKGROUND_RGBA:
 573       set_cell_bg_color (cell, g_value_get_boxed (value));
 574       break;
 575     case PROP_CELL_BACKGROUND_SET:
 576       priv->cell_background_set = g_value_get_boolean (value);
 577       break;
 578     default:
 579       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, param_id, pspec);
 580       break;
 581     }
 582 }
 583
 584 static void
 585 set_cell_bg_color (GtkCellRenderer *cell,
 586                    GdkRGBA         *rgba)
 587 {
 588   GtkCellRendererPrivate *priv = cell->priv;
 589
 590   if (rgba)
 591     {
 592       if (!priv->cell_background_set)
 593         {
 594           priv->cell_background_set = TRUE;
 595           g_object_notify (G_OBJECT (cell), "cell-background-set");
 596         }
 597
 598       priv->cell_background = *rgba;
 599     }
 600   else
 601     {
 602       if (priv->cell_background_set)
 603         {
 604           priv->cell_background_set = FALSE;
 605           g_object_notify (G_OBJECT (cell), "cell-background-set");
 606         }
 607     }
 608 }
 609
 610 /**
 611  * gtk_cell_renderer_get_size:
 612  * @cell: a #GtkCellRenderer
 613  * @widget: the widget the renderer is rendering to
 614  * @cell_area: (allow-none): The area a cell will be allocated, or %NULL
 615  * @x_offset: (allow-none): location to return x offset of cell relative to @cell_area, or %NULL
 616  * @y_offset: (allow-none): location to return y offset of cell relative to @cell_area, or %NULL
 617  * @width: (allow-none): location to return width needed to render a cell, or %NULL
 618  * @height: (allow-none): location to return height needed to render a cell, or %NULL
 619  *
 620  * Obtains the width and height needed to render the cell. Used by view
 621  * widgets to determine the appropriate size for the cell_area passed to
 622  * gtk_cell_renderer_render().  If @cell_area is not %NULL, fills in the
 623  * x and y offsets (if set) of the cell relative to this location.
 624  *
 625  * Please note that the values set in @width and @height, as well as those
 626  * in @x_offset and @y_offset are inclusive of the xpad and ypad properties.
 627  *
 628  *
 629  * Deprecated: 3.0: Use gtk_cell_renderer_get_preferred_size() instead.
 630  **/
 631 void
 632 gtk_cell_renderer_get_size (GtkCellRenderer    *cell,
 633                             GtkWidget          *widget,
 634                             const GdkRectangle *cell_area,
 635                             gint               *x_offset,
 636                             gint               *y_offset,
 637                             gint               *width,
 638                             gint               *height)
 639 {
 640   GtkRequisition request;
 641
 642   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
 643
 644   gtk_cell_renderer_get_preferred_size (cell, widget, &request, NULL);
 645
 646   if (width)
 647     *width = request.width;
 648
 649   if (height)
 650     *height = request.height;
 651
 652   if (cell_area)
 653     _gtk_cell_renderer_calc_offset (cell, cell_area, gtk_widget_get_direction (widget),
 654                                     request.width, request.height, x_offset, y_offset);
 655 }
 656
 657 /**
 658  * gtk_cell_renderer_render:
 659  * @cell: a #GtkCellRenderer
 660  * @cr: a cairo context to draw to
 661  * @widget: the widget owning @window
 662  * @background_area: entire cell area (including tree expanders and maybe
 663  *    padding on the sides)
 664  * @cell_area: area normally rendered by a cell renderer
 665  * @flags: flags that affect rendering
 666  *
 667  * Invokes the virtual render function of the #GtkCellRenderer. The three
 668  * passed-in rectangles are areas in @cr. Most renderers will draw within
 669  * @cell_area; the xalign, yalign, xpad, and ypad fields of the #GtkCellRenderer
 670  * should be honored with respect to @cell_area. @background_area includes the
 671  * blank space around the cell, and also the area containing the tree expander;
 672  * so the @background_area rectangles for all cells tile to cover the entire
 673  * @window.
 674  **/
 675 void
 676 gtk_cell_renderer_render (GtkCellRenderer      *cell,
 677                           cairo_t              *cr,
 678                           GtkWidget            *widget,
 679                           const GdkRectangle   *background_area,
 680                           const GdkRectangle   *cell_area,
 681                           GtkCellRendererState  flags)
 682 {
 683   gboolean selected = FALSE;
 684   GtkCellRendererPrivate *priv = cell->priv;
 685
 686   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
 687   g_return_if_fail (GTK_CELL_RENDERER_GET_CLASS (cell)->render != NULL);
 688   g_return_if_fail (cr != NULL);
 689
 690   selected = (flags & GTK_CELL_RENDERER_SELECTED) == GTK_CELL_RENDERER_SELECTED;
 691
 692   cairo_save (cr);
 693
 694   if (priv->cell_background_set && !selected)
 695     {
 696       gdk_cairo_rectangle (cr, background_area);
 697       gdk_cairo_set_source_rgba (cr, &priv->cell_background);
 698       cairo_fill (cr);
 699     }
 700
 701   GTK_CELL_RENDERER_GET_CLASS (cell)->render (cell,
 702                                               cr,
 703                                               widget,
 704                                               background_area,
 705                                               cell_area,
 706                                               flags);
 707
 708   cairo_restore (cr);
 709 }
 710
 711 /**
 712  * gtk_cell_renderer_activate:
 713  * @cell: a #GtkCellRenderer
 714  * @event: a #GdkEvent
 715  * @widget: widget that received the event
 716  * @path: widget-dependent string representation of the event location;
 717  *    e.g. for #GtkTreeView, a string representation of #GtkTreePath
 718  * @background_area: background area as passed to gtk_cell_renderer_render()
 719  * @cell_area: cell area as passed to gtk_cell_renderer_render()
 720  * @flags: render flags
 721  *
 722  * Passes an activate event to the cell renderer for possible processing.
 723  * Some cell renderers may use events; for example, #GtkCellRendererToggle
 724  * toggles when it gets a mouse click.
 725  *
 726  * Return value: %TRUE if the event was consumed/handled
 727  **/
 728 gboolean
 729 gtk_cell_renderer_activate (GtkCellRenderer      *cell,
 730                             GdkEvent             *event,
 731                             GtkWidget            *widget,
 732                             const gchar          *path,
 733                             const GdkRectangle   *background_area,
 734                             const GdkRectangle   *cell_area,
 735                             GtkCellRendererState  flags)
 736 {
 737   GtkCellRendererPrivate *priv;
 738
 739   g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
 740
 741   priv = cell->priv;
 742
 743   if (priv->mode != GTK_CELL_RENDERER_MODE_ACTIVATABLE)
 744     return FALSE;
 745
 746   if (GTK_CELL_RENDERER_GET_CLASS (cell)->activate == NULL)
 747     return FALSE;
 748
 749   return GTK_CELL_RENDERER_GET_CLASS (cell)->activate (cell,
 750                                                        event,
 751                                                        widget,
 752                                                        path,
 753                                                        (GdkRectangle *) background_area,
 754                                                        (GdkRectangle *) cell_area,
 755                                                        flags);
 756 }
 757
 758 /**
 759  * gtk_cell_renderer_start_editing:
 760  * @cell: a #GtkCellRenderer
 761  * @event: a #GdkEvent
 762  * @widget: widget that received the event
 763  * @path: widget-dependent string representation of the event location;
 764  *    e.g. for #GtkTreeView, a string representation of #GtkTreePath
 765  * @background_area: background area as passed to gtk_cell_renderer_render()
 766  * @cell_area: cell area as passed to gtk_cell_renderer_render()
 767  * @flags: render flags
 768  *
 769  * Passes an activate event to the cell renderer for possible processing.
 770  *
 771  * Return value: (transfer full): A new #GtkCellEditable, or %NULL
 772  **/
 773 GtkCellEditable *
 774 gtk_cell_renderer_start_editing (GtkCellRenderer      *cell,
 775                                  GdkEvent             *event,
 776                                  GtkWidget            *widget,
 777                                  const gchar          *path,
 778                                  const GdkRectangle   *background_area,
 779                                  const GdkRectangle   *cell_area,
 780                                  GtkCellRendererState  flags)
 781
 782 {
 783   GtkCellRendererPrivate *priv;
 784   GtkCellEditable *editable;
 785
 786   g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), NULL);
 787
 788   priv = cell->priv;
 789
 790   if (priv->mode != GTK_CELL_RENDERER_MODE_EDITABLE)
 791     return NULL;
 792
 793   if (GTK_CELL_RENDERER_GET_CLASS (cell)->start_editing == NULL)
 794     return NULL;
 795
 796   editable = GTK_CELL_RENDERER_GET_CLASS (cell)->start_editing (cell,
 797                                                                 event,
 798                                                                 widget,
 799                                                                 path,
 800                                                                 (GdkRectangle *) background_area,
 801                                                                 (GdkRectangle *) cell_area,
 802                                                                 flags);
 803
 804   g_signal_emit (cell,
 805                  cell_renderer_signals[EDITING_STARTED], 0,
 806                  editable, path);
 807
 808   priv->editing = TRUE;
 809
 810   return editable;
 811 }
 812
 813 /**
 814  * gtk_cell_renderer_set_fixed_size:
 815  * @cell: A #GtkCellRenderer
 816  * @width: the width of the cell renderer, or -1
 817  * @height: the height of the cell renderer, or -1
 818  *
 819  * Sets the renderer size to be explicit, independent of the properties set.
 820  **/
 821 void
 822 gtk_cell_renderer_set_fixed_size (GtkCellRenderer *cell,
 823                                   gint             width,
 824                                   gint             height)
 825 {
 826   GtkCellRendererPrivate *priv;
 827
 828   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
 829   g_return_if_fail (width >= -1 && height >= -1);
 830
 831   priv = cell->priv;
 832
 833   if ((width != priv->width) || (height != priv->height))
 834     {
 835       g_object_freeze_notify (G_OBJECT (cell));
 836
 837       if (width != priv->width)
 838         {
 839           priv->width = width;
 840           g_object_notify (G_OBJECT (cell), "width");
 841         }
 842
 843       if (height != priv->height)
 844         {
 845           priv->height = height;
 846           g_object_notify (G_OBJECT (cell), "height");
 847         }
 848
 849       g_object_thaw_notify (G_OBJECT (cell));
 850     }
 851 }
 852
 853 /**
 854  * gtk_cell_renderer_get_fixed_size:
 855  * @cell: A #GtkCellRenderer
 856  * @width: (allow-none): location to fill in with the fixed width of the cell, or %NULL
 857  * @height: (allow-none): location to fill in with the fixed height of the cell, or %NULL
 858  *
 859  * Fills in @width and @height with the appropriate size of @cell.
 860  **/
 861 void
 862 gtk_cell_renderer_get_fixed_size (GtkCellRenderer *cell,
 863                                   gint            *width,
 864                                   gint            *height)
 865 {
 866   GtkCellRendererPrivate *priv;
 867
 868   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
 869
 870   priv = cell->priv;
 871
 872   if (width)
 873     *width = priv->width;
 874   if (height)
 875     *height = priv->height;
 876 }
 877
 878 /**
 879  * gtk_cell_renderer_set_alignment:
 880  * @cell: A #GtkCellRenderer
 881  * @xalign: the x alignment of the cell renderer
 882  * @yalign: the y alignment of the cell renderer
 883  *
 884  * Sets the renderer's alignment within its available space.
 885  *
 886  * Since: 2.18
 887  **/
 888 void
 889 gtk_cell_renderer_set_alignment (GtkCellRenderer *cell,
 890                                  gfloat           xalign,
 891                                  gfloat           yalign)
 892 {
 893   GtkCellRendererPrivate *priv;
 894
 895   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
 896   g_return_if_fail (xalign >= 0.0 && xalign <= 1.0);
 897   g_return_if_fail (yalign >= 0.0 && yalign <= 1.0);
 898
 899   priv = cell->priv;
 900
 901   if ((xalign != priv->xalign) || (yalign != priv->yalign))
 902     {
 903       g_object_freeze_notify (G_OBJECT (cell));
 904
 905       if (xalign != priv->xalign)
 906         {
 907           priv->xalign = xalign;
 908           g_object_notify (G_OBJECT (cell), "xalign");
 909         }
 910
 911       if (yalign != priv->yalign)
 912         {
 913           priv->yalign = yalign;
 914           g_object_notify (G_OBJECT (cell), "yalign");
 915         }
 916
 917       g_object_thaw_notify (G_OBJECT (cell));
 918     }
 919 }
 920
 921 /**
 922  * gtk_cell_renderer_get_alignment:
 923  * @cell: A #GtkCellRenderer
 924  * @xalign: (allow-none): location to fill in with the x alignment of the cell, or %NULL
 925  * @yalign: (allow-none): location to fill in with the y alignment of the cell, or %NULL
 926  *
 927  * Fills in @xalign and @yalign with the appropriate values of @cell.
 928  *
 929  * Since: 2.18
 930  **/
 931 void
 932 gtk_cell_renderer_get_alignment (GtkCellRenderer *cell,
 933                                  gfloat          *xalign,
 934                                  gfloat          *yalign)
 935 {
 936   GtkCellRendererPrivate *priv;
 937
 938   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
 939
 940   priv = cell->priv;
 941
 942   if (xalign)
 943     *xalign = priv->xalign;
 944   if (yalign)
 945     *yalign = priv->yalign;
 946 }
 947
 948 /**
 949  * gtk_cell_renderer_set_padding:
 950  * @cell: A #GtkCellRenderer
 951  * @xpad: the x padding of the cell renderer
 952  * @ypad: the y padding of the cell renderer
 953  *
 954  * Sets the renderer's padding.
 955  *
 956  * Since: 2.18
 957  **/
 958 void
 959 gtk_cell_renderer_set_padding (GtkCellRenderer *cell,
 960                                gint             xpad,
 961                                gint             ypad)
 962 {
 963   GtkCellRendererPrivate *priv;
 964
 965   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
 966   g_return_if_fail (xpad >= 0 && xpad >= 0);
 967
 968   priv = cell->priv;
 969
 970   if ((xpad != priv->xpad) || (ypad != priv->ypad))
 971     {
 972       g_object_freeze_notify (G_OBJECT (cell));
 973
 974       if (xpad != priv->xpad)
 975         {
 976           priv->xpad = xpad;
 977           g_object_notify (G_OBJECT (cell), "xpad");
 978         }
 979
 980       if (ypad != priv->ypad)
 981         {
 982           priv->ypad = ypad;
 983           g_object_notify (G_OBJECT (cell), "ypad");
 984         }
 985
 986       g_object_thaw_notify (G_OBJECT (cell));
 987     }
 988 }
 989
 990 /**
 991  * gtk_cell_renderer_get_padding:
 992  * @cell: A #GtkCellRenderer
 993  * @xpad: (allow-none): location to fill in with the x padding of the cell, or %NULL
 994  * @ypad: (allow-none): location to fill in with the y padding of the cell, or %NULL
 995  *
 996  * Fills in @xpad and @ypad with the appropriate values of @cell.
 997  *
 998  * Since: 2.18
 999  **/
1000 void
1001 gtk_cell_renderer_get_padding (GtkCellRenderer *cell,
1002                                gint            *xpad,
1003                                gint            *ypad)
1004 {
1005   GtkCellRendererPrivate *priv;
1006
1007   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1008
1009   priv = cell->priv;
1010
1011   if (xpad)
1012     *xpad = priv->xpad;
1013   if (ypad)
1014     *ypad = priv->ypad;
1015 }
1016
1017 /**
1018  * gtk_cell_renderer_set_visible:
1019  * @cell: A #GtkCellRenderer
1020  * @visible: the visibility of the cell
1021  *
1022  * Sets the cell renderer's visibility.
1023  *
1024  * Since: 2.18
1025  **/
1026 void
1027 gtk_cell_renderer_set_visible (GtkCellRenderer *cell,
1028                                gboolean         visible)
1029 {
1030   GtkCellRendererPrivate *priv;
1031
1032   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1033
1034   priv = cell->priv;
1035
1036   if (priv->visible != visible)
1037     {
1038       priv->visible = visible ? TRUE : FALSE;
1039       g_object_notify (G_OBJECT (cell), "visible");
1040     }
1041 }
1042
1043 /**
1044  * gtk_cell_renderer_get_visible:
1045  * @cell: A #GtkCellRenderer
1046  *
1047  * Returns the cell renderer's visibility.
1048  *
1049  * Returns: %TRUE if the cell renderer is visible
1050  *
1051  * Since: 2.18
1052  */
1053 gboolean
1054 gtk_cell_renderer_get_visible (GtkCellRenderer *cell)
1055 {
1056   g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
1057
1058   return cell->priv->visible;
1059 }
1060
1061 /**
1062  * gtk_cell_renderer_set_sensitive:
1063  * @cell: A #GtkCellRenderer
1064  * @sensitive: the sensitivity of the cell
1065  *
1066  * Sets the cell renderer's sensitivity.
1067  *
1068  * Since: 2.18
1069  **/
1070 void
1071 gtk_cell_renderer_set_sensitive (GtkCellRenderer *cell,
1072                                  gboolean         sensitive)
1073 {
1074   GtkCellRendererPrivate *priv;
1075
1076   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1077
1078   priv = cell->priv;
1079
1080   if (priv->sensitive != sensitive)
1081     {
1082       priv->sensitive = sensitive ? TRUE : FALSE;
1083       g_object_notify (G_OBJECT (cell), "sensitive");
1084     }
1085 }
1086
1087 /**
1088  * gtk_cell_renderer_get_sensitive:
1089  * @cell: A #GtkCellRenderer
1090  *
1091  * Returns the cell renderer's sensitivity.
1092  *
1093  * Returns: %TRUE if the cell renderer is sensitive
1094  *
1095  * Since: 2.18
1096  */
1097 gboolean
1098 gtk_cell_renderer_get_sensitive (GtkCellRenderer *cell)
1099 {
1100   g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
1101
1102   return cell->priv->sensitive;
1103 }
1104
1105
1106 /**
1107  * gtk_cell_renderer_is_activatable:
1108  * @cell: A #GtkCellRenderer
1109  *
1110  * Checks whether the cell renderer can do something when activated.
1111  *
1112  * Returns: %TRUE if the cell renderer can do anything when activated.
1113  *
1114  * Since: 3.0
1115  */
1116 gboolean
1117 gtk_cell_renderer_is_activatable (GtkCellRenderer *cell)
1118 {
1119   GtkCellRendererPrivate *priv;
1120
1121   g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
1122
1123   priv = cell->priv;
1124
1125   return (cell->priv->visible &&
1126           (cell->priv->mode == GTK_CELL_RENDERER_MODE_EDITABLE ||
1127            cell->priv->mode == GTK_CELL_RENDERER_MODE_ACTIVATABLE));
1128 }
1129
1130
1131 /**
1132  * gtk_cell_renderer_stop_editing:
1133  * @cell: A #GtkCellRenderer
1134  * @canceled: %TRUE if the editing has been canceled
1135  *
1136  * Informs the cell renderer that the editing is stopped.
1137  * If @canceled is %TRUE, the cell renderer will emit the
1138  * #GtkCellRenderer::editing-canceled signal.
1139  *
1140  * This function should be called by cell renderer implementations
1141  * in response to the #GtkCellEditable::editing-done signal of
1142  * #GtkCellEditable.
1143  *
1144  * Since: 2.6
1145  **/
1146 void
1147 gtk_cell_renderer_stop_editing (GtkCellRenderer *cell,
1148                                 gboolean         canceled)
1149 {
1150   GtkCellRendererPrivate *priv;
1151
1152   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1153
1154   priv = cell->priv;
1155
1156   if (priv->editing)
1157     {
1158       priv->editing = FALSE;
1159       if (canceled)
1160         g_signal_emit (cell, cell_renderer_signals[EDITING_CANCELED], 0);
1161     }
1162 }
1163
1164 static void
1165 gtk_cell_renderer_real_get_preferred_size (GtkCellRenderer   *cell,
1166                                            GtkWidget         *widget,
1167                                            GtkOrientation     orientation,
1168                                            gint              *minimum_size,
1169                                            gint              *natural_size)
1170 {
1171   GtkRequisition min_req;
1172
1173   /* Fallback on the old API to get the size. */
1174   if (GTK_CELL_RENDERER_GET_CLASS (cell)->get_size)
1175     GTK_CELL_RENDERER_GET_CLASS (cell)->get_size (GTK_CELL_RENDERER (cell), widget, NULL, NULL, NULL,
1176                                                   &min_req.width, &min_req.height);
1177   else
1178     {
1179       min_req.width = 0;
1180       min_req.height = 0;
1181     }
1182
1183   if (orientation == GTK_ORIENTATION_HORIZONTAL)
1184     {
1185       if (minimum_size)
1186         *minimum_size = min_req.width;
1187
1188       if (natural_size)
1189         *natural_size = min_req.width;
1190     }
1191   else
1192     {
1193       if (minimum_size)
1194         *minimum_size = min_req.height;
1195
1196       if (natural_size)
1197         *natural_size = min_req.height;
1198     }
1199 }
1200
1201 static void
1202 gtk_cell_renderer_real_get_preferred_width (GtkCellRenderer *cell,
1203                                             GtkWidget       *widget,
1204                                             gint            *minimum_size,
1205                                             gint            *natural_size)
1206 {
1207   gtk_cell_renderer_real_get_preferred_size (cell, widget, GTK_ORIENTATION_HORIZONTAL,
1208                                              minimum_size, natural_size);
1209 }
1210
1211 static void
1212 gtk_cell_renderer_real_get_preferred_height (GtkCellRenderer *cell,
1213                                              GtkWidget       *widget,
1214                                              gint            *minimum_size,
1215                                              gint            *natural_size)
1216 {
1217   gtk_cell_renderer_real_get_preferred_size (cell, widget, GTK_ORIENTATION_VERTICAL,
1218                                              minimum_size, natural_size);
1219 }
1220
1221
1222 static void
1223 gtk_cell_renderer_real_get_preferred_height_for_width (GtkCellRenderer *cell,
1224                                                        GtkWidget       *widget,
1225                                                        gint             width,
1226                                                        gint            *minimum_height,
1227                                                        gint            *natural_height)
1228 {
1229   /* Fall back on the height reported from ->get_size() */
1230   gtk_cell_renderer_get_preferred_height (cell, widget, minimum_height, natural_height);
1231 }
1232
1233 static void
1234 gtk_cell_renderer_real_get_preferred_width_for_height (GtkCellRenderer *cell,
1235                                                        GtkWidget       *widget,
1236                                                        gint             height,
1237                                                        gint            *minimum_width,
1238                                                        gint            *natural_width)
1239 {
1240   /* Fall back on the width reported from ->get_size() */
1241   gtk_cell_renderer_get_preferred_width (cell, widget, minimum_width, natural_width);
1242 }
1243
1244
1245 /* Default implementation assumes that a cell renderer will never use more
1246  * space than it's natural size (this is fine for toggles and pixbufs etc
1247  * but needs to be overridden from wrapping/ellipsizing text renderers) */
1248 static void
1249 gtk_cell_renderer_real_get_aligned_area (GtkCellRenderer         *cell,
1250                                          GtkWidget               *widget,
1251                                          GtkCellRendererState     flags,
1252                                          const GdkRectangle      *cell_area,
1253                                          GdkRectangle            *aligned_area)
1254 {
1255   gint opposite_size, x_offset, y_offset;
1256   gint natural_size;
1257
1258   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1259   g_return_if_fail (GTK_IS_WIDGET (widget));
1260   g_return_if_fail (cell_area != NULL);
1261   g_return_if_fail (aligned_area != NULL);
1262
1263   *aligned_area = *cell_area;
1264
1265   /* Trim up the aligned size */
1266   if (gtk_cell_renderer_get_request_mode (cell) == GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH)
1267     {
1268       gtk_cell_renderer_get_preferred_width (cell, widget,
1269                                              NULL, &natural_size);
1270
1271       aligned_area->width = MIN (aligned_area->width, natural_size);
1272
1273       gtk_cell_renderer_get_preferred_height_for_width (cell, widget,
1274                                                         aligned_area->width,
1275                                                         NULL, &opposite_size);
1276
1277       aligned_area->height = MIN (opposite_size, aligned_area->height);
1278     }
1279   else
1280     {
1281       gtk_cell_renderer_get_preferred_height (cell, widget,
1282                                               NULL, &natural_size);
1283
1284       aligned_area->height = MIN (aligned_area->width, natural_size);
1285
1286       gtk_cell_renderer_get_preferred_width_for_height (cell, widget,
1287                                                         aligned_area->height,
1288                                                         NULL, &opposite_size);
1289
1290       aligned_area->width = MIN (opposite_size, aligned_area->width);
1291     }
1292
1293   /* offset the cell position */
1294   _gtk_cell_renderer_calc_offset (cell, cell_area,
1295                                   gtk_widget_get_direction (widget),
1296                                   aligned_area->width,
1297                                   aligned_area->height,
1298                                   &x_offset, &y_offset);
1299
1300   aligned_area->x += x_offset;
1301   aligned_area->y += y_offset;
1302 }
1303
1304
1305 /* An internal convenience function for some containers to peek at the
1306  * cell alignment in a target allocation (used to draw focus and align
1307  * cells in the icon view).
1308  *
1309  * Note this is only a trivial 'align * (allocation - request)' operation.
1310  */
1311 void
1312 _gtk_cell_renderer_calc_offset    (GtkCellRenderer      *cell,
1313                                    const GdkRectangle   *cell_area,
1314                                    GtkTextDirection      direction,
1315                                    gint                  width,
1316                                    gint                  height,
1317                                    gint                 *x_offset,
1318                                    gint                 *y_offset)
1319 {
1320   GtkCellRendererPrivate *priv;
1321
1322   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1323   g_return_if_fail (cell_area != NULL);
1324   g_return_if_fail (x_offset || y_offset);
1325
1326   priv = cell->priv;
1327
1328   if (x_offset)
1329     {
1330       *x_offset = (((direction == GTK_TEXT_DIR_RTL) ?
1331                     (1.0 - priv->xalign) : priv->xalign) *
1332                    (cell_area->width - width));
1333       *x_offset = MAX (*x_offset, 0);
1334     }
1335   if (y_offset)
1336     {
1337       *y_offset = (priv->yalign *
1338                    (cell_area->height - height));
1339       *y_offset = MAX (*y_offset, 0);
1340     }
1341 }
1342
1343 /**
1344  * gtk_cell_renderer_get_request_mode:
1345  * @cell: a #GtkCellRenderer    instance
1346  *
1347  * Gets whether the cell renderer prefers a height-for-width layout
1348  * or a width-for-height layout.
1349  *
1350  * Returns: The #GtkSizeRequestMode preferred by this renderer.
1351  *
1352  * Since: 3.0
1353  */
1354 GtkSizeRequestMode
1355 gtk_cell_renderer_get_request_mode (GtkCellRenderer *cell)
1356 {
1357   GtkCellRendererClass *klass;
1358
1359   g_return_val_if_fail (GTK_IS_CELL_RENDERER (cell), FALSE);
1360
1361   klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1362   if (klass->get_request_mode)
1363     return klass->get_request_mode (cell);
1364
1365   /* By default cell renderers are height-for-width. */
1366   return GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH;
1367 }
1368
1369 /**
1370  * gtk_cell_renderer_get_preferred_width:
1371  * @cell: a #GtkCellRenderer instance
1372  * @widget: the #GtkWidget this cell will be rendering to
1373  * @minimum_size: location to store the minimum size, or %NULL
1374  * @natural_size: location to store the natural size, or %NULL
1375  *
1376  * Retreives a renderer's natural size when rendered to @widget.
1377  *
1378  * Since: 3.0
1379  */
1380 void
1381 gtk_cell_renderer_get_preferred_width (GtkCellRenderer *cell,
1382                                        GtkWidget       *widget,
1383                                        gint            *minimum_size,
1384                                        gint            *natural_size)
1385 {
1386   GtkCellRendererClass *klass;
1387   gint width;
1388
1389   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1390   g_return_if_fail (GTK_IS_WIDGET (widget));
1391   g_return_if_fail (NULL != minimum_size || NULL != natural_size);
1392
1393   gtk_cell_renderer_get_fixed_size (GTK_CELL_RENDERER (cell), &width, NULL);
1394
1395   if (width < 0)
1396     {
1397       klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1398       klass->get_preferred_width (cell, widget, minimum_size, natural_size);
1399     }
1400   else
1401     {
1402       if (minimum_size)
1403         *minimum_size = width;
1404       if (natural_size)
1405         *natural_size = width;
1406     }
1407
1408 #if DEBUG_CELL_SIZE_REQUEST
1409   g_message ("%s returning minimum width: %d and natural width: %d",
1410              G_OBJECT_TYPE_NAME (cell),
1411              minimum_size ? *minimum_size : 20000,
1412              natural_size ? *natural_size : 20000);
1413 #endif
1414 }
1415
1416
1417 /**
1418  * gtk_cell_renderer_get_preferred_height:
1419  * @cell: a #GtkCellRenderer instance
1420  * @widget: the #GtkWidget this cell will be rendering to
1421  * @minimum_size: location to store the minimum size, or %NULL
1422  * @natural_size: location to store the natural size, or %NULL
1423  *
1424  * Retreives a renderer's natural size when rendered to @widget.
1425  *
1426  * Since: 3.0
1427  */
1428 void
1429 gtk_cell_renderer_get_preferred_height (GtkCellRenderer *cell,
1430                                         GtkWidget       *widget,
1431                                         gint            *minimum_size,
1432                                         gint            *natural_size)
1433 {
1434   GtkCellRendererClass *klass;
1435   gint height;
1436
1437   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1438   g_return_if_fail (GTK_IS_WIDGET (widget));
1439   g_return_if_fail (NULL != minimum_size || NULL != natural_size);
1440
1441   gtk_cell_renderer_get_fixed_size (GTK_CELL_RENDERER (cell), NULL, &height);
1442
1443   if (height < 0)
1444     {
1445       klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1446       klass->get_preferred_height (cell, widget, minimum_size, natural_size);
1447     }
1448   else
1449     {
1450       if (minimum_size)
1451         *minimum_size = height;
1452       if (natural_size)
1453         *natural_size = height;
1454     }
1455
1456 #if DEBUG_CELL_SIZE_REQUEST
1457   g_message ("%s returning minimum height: %d and natural height: %d",
1458              G_OBJECT_TYPE_NAME (cell),
1459              minimum_size ? *minimum_size : 20000,
1460              natural_size ? *natural_size : 20000);
1461 #endif
1462 }
1463
1464
1465 /**
1466  * gtk_cell_renderer_get_preferred_width_for_height:
1467  * @cell: a #GtkCellRenderer instance
1468  * @widget: the #GtkWidget this cell will be rendering to
1469  * @height: the size which is available for allocation
1470  * @minimum_width: location for storing the minimum size, or %NULL
1471  * @natural_width: location for storing the preferred size, or %NULL
1472  *
1473  * Retreives a cell renderers's minimum and natural width if it were rendered to
1474  * @widget with the specified @height.
1475  *
1476  * Since: 3.0
1477  */
1478 void
1479 gtk_cell_renderer_get_preferred_width_for_height (GtkCellRenderer *cell,
1480                                                   GtkWidget       *widget,
1481                                                   gint             height,
1482                                                   gint            *minimum_width,
1483                                                   gint            *natural_width)
1484 {
1485   GtkCellRendererClass *klass;
1486   gint width;
1487
1488   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1489   g_return_if_fail (GTK_IS_WIDGET (widget));
1490   g_return_if_fail (NULL != minimum_width || NULL != natural_width);
1491
1492   gtk_cell_renderer_get_fixed_size (GTK_CELL_RENDERER (cell), &width, NULL);
1493
1494   if (width < 0)
1495     {
1496       klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1497       klass->get_preferred_width_for_height (cell, widget, height, minimum_width, natural_width);
1498     }
1499   else
1500     {
1501       if (minimum_width)
1502         *minimum_width = width;
1503       if (natural_width)
1504         *natural_width = width;
1505     }
1506
1507 #if DEBUG_CELL_SIZE_REQUEST
1508   g_message ("%s width for height: %d is minimum %d and natural: %d",
1509              G_OBJECT_TYPE_NAME (cell), height,
1510              minimum_width ? *minimum_width : 20000,
1511              natural_width ? *natural_width : 20000);
1512 #endif
1513 }
1514
1515 /**
1516  * gtk_cell_renderer_get_preferred_height_for_width:
1517  * @cell: a #GtkCellRenderer instance
1518  * @widget: the #GtkWidget this cell will be rendering to
1519  * @width: the size which is available for allocation
1520  * @minimum_height: location for storing the minimum size, or %NULL
1521  * @natural_height: location for storing the preferred size, or %NULL
1522  *
1523  * Retreives a cell renderers's minimum and natural height if it were rendered to
1524  * @widget with the specified @width.
1525  *
1526  * Since: 3.0
1527  */
1528 void
1529 gtk_cell_renderer_get_preferred_height_for_width (GtkCellRenderer *cell,
1530                                                   GtkWidget       *widget,
1531                                                   gint             width,
1532                                                   gint            *minimum_height,
1533                                                   gint            *natural_height)
1534 {
1535   GtkCellRendererClass *klass;
1536   gint height;
1537
1538   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1539   g_return_if_fail (GTK_IS_WIDGET (widget));
1540   g_return_if_fail (NULL != minimum_height || NULL != natural_height);
1541
1542   gtk_cell_renderer_get_fixed_size (GTK_CELL_RENDERER (cell), NULL, &height);
1543
1544   if (height < 0)
1545     {
1546       klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1547       klass->get_preferred_height_for_width (cell, widget, width, minimum_height, natural_height);
1548     }
1549   else
1550     {
1551       if (minimum_height)
1552         *minimum_height = height;
1553       if (natural_height)
1554         *natural_height = height;
1555     }
1556
1557 #if DEBUG_CELL_SIZE_REQUEST
1558   g_message ("%s height for width: %d is minimum %d and natural: %d",
1559              G_OBJECT_TYPE_NAME (cell), width,
1560              minimum_height ? *minimum_height : 20000,
1561              natural_height ? *natural_height : 20000);
1562 #endif
1563 }
1564
1565 /**
1566  * gtk_cell_renderer_get_preferred_size:
1567  * @cell: a #GtkCellRenderer instance
1568  * @widget: the #GtkWidget this cell will be rendering to
1569  * @request_natural: Whether to base the contextual request off of the
1570  *     base natural or the base minimum
1571  * @minimum_size: (out) (allow-none): location for storing the minimum size, or %NULL
1572  * @natural_size: (out) (allow-none): location for storing the natural size, or %NULL
1573  *
1574  * Retrieves the minimum and natural size of a cell taking
1575  * into account the widget's preference for height-for-width management.
1576  *
1577  * If request_natural is specified, the non-contextual natural value will
1578  * be used to make the contextual request; otherwise the minimum will be used.
1579  *
1580  * Since: 3.0
1581  */
1582 void
1583 gtk_cell_renderer_get_preferred_size (GtkCellRenderer *cell,
1584                                       GtkWidget       *widget,
1585                                       GtkRequisition  *minimum_size,
1586                                       GtkRequisition  *natural_size)
1587 {
1588   gint min_width, nat_width;
1589   gint min_height, nat_height;
1590
1591   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1592
1593   if (gtk_cell_renderer_get_request_mode (cell) == GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH)
1594     {
1595       gtk_cell_renderer_get_preferred_width (cell, widget, &min_width, &nat_width);
1596
1597       if (minimum_size)
1598         {
1599           minimum_size->width = min_width;
1600           gtk_cell_renderer_get_preferred_height_for_width (cell, widget, min_width,
1601                                                             &minimum_size->height, NULL);
1602         }
1603
1604       if (natural_size)
1605         {
1606           natural_size->width = nat_width;
1607           gtk_cell_renderer_get_preferred_height_for_width (cell, widget, nat_width,
1608                                                             NULL, &natural_size->height);
1609         }
1610     }
1611   else /* GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT */
1612     {
1613       gtk_cell_renderer_get_preferred_height (cell, widget, &min_height, &nat_height);
1614
1615       if (minimum_size)
1616         {
1617           minimum_size->height = min_height;
1618           gtk_cell_renderer_get_preferred_width_for_height (cell, widget, min_height,
1619                                                             &minimum_size->width, NULL);
1620         }
1621
1622       if (natural_size)
1623         {
1624           natural_size->height = nat_height;
1625           gtk_cell_renderer_get_preferred_width_for_height (cell, widget, nat_height,
1626                                                             NULL, &natural_size->width);
1627         }
1628     }
1629 }
1630
1631 /**
1632  * gtk_cell_renderer_get_aligned_area:
1633  * @cell: a #GtkCellRenderer instance
1634  * @widget: the #GtkWidget this cell will be rendering to
1635  * @flags: render flags
1636  * @cell_area: cell area which would be passed to gtk_cell_renderer_render()
1637  * @aligned_area: the return location for the space inside @cell_area that
1638  *                would acually be used to render.
1639  *
1640  * Gets the aligned area used by @cell inside @cell_area. Used for finding
1641  * the appropriate edit and focus rectangle.
1642  *
1643  * Since: 3.0
1644  */
1645 void
1646 gtk_cell_renderer_get_aligned_area (GtkCellRenderer      *cell,
1647                                     GtkWidget            *widget,
1648                                     GtkCellRendererState  flags,
1649                                     const GdkRectangle   *cell_area,
1650                                     GdkRectangle         *aligned_area)
1651 {
1652   GtkCellRendererClass *klass;
1653
1654   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
1655   g_return_if_fail (GTK_IS_WIDGET (widget));
1656   g_return_if_fail (cell_area != NULL);
1657   g_return_if_fail (aligned_area != NULL);
1658
1659   klass = GTK_CELL_RENDERER_GET_CLASS (cell);
1660   klass->get_aligned_area (cell, widget, flags, cell_area, aligned_area);
1661 }