GtkCellRenderer: GTK+ 2 Reference Manual

## GtkCellRenderer GtkCellRenderer — An object for rendering a single cell on a GdkDrawable |

## Functions

void | gtk_cell_renderer_get_size ()
void | gtk_cell_renderer_render ()
gboolean | gtk_cell_renderer_activate ()
GtkCellEditable * | gtk_cell_renderer_start_editing ()
void | gtk_cell_renderer_editing_canceled ()
void | gtk_cell_renderer_stop_editing ()
void | gtk_cell_renderer_get_fixed_size ()
void | gtk_cell_renderer_set_fixed_size ()
gboolean | gtk_cell_renderer_get_visible ()
void | gtk_cell_renderer_set_visible ()
gboolean | gtk_cell_renderer_get_sensitive ()
void | gtk_cell_renderer_set_sensitive ()
void | gtk_cell_renderer_get_alignment ()
void | gtk_cell_renderer_set_alignment ()
void | gtk_cell_renderer_get_padding ()
void | gtk_cell_renderer_set_padding ()

## Properties

gchar * | cell-background | Write
GdkColor * | cell-background-gdk | Read / Write
gboolean | cell-background-set | Read / Write
gboolean | editing | Read
gint | height | Read / Write
gboolean | is-expanded | Read / Write
gboolean | is-expander | Read / Write
GtkCellRendererMode | mode | Read / Write
gboolean | sensitive | Read / Write
gboolean | visible | Read / Write
gint | width | Read / Write
gfloat | xalign | Read / Write
guint | xpad | Read / Write
gfloat | yalign | Read / Write
guint | ypad | Read / Write

## Signals

void | editing-canceled | Run First
void | editing-started | Run First

## Types and Values

enum | GtkCellRendererState
enum | GtkCellRendererMode
struct | GtkCellRenderer
struct | GtkCellRendererClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkObject
                ╰── GtkCellRenderer
                    ├── GtkCellRendererText
                    ├── GtkCellRendererPixbuf
                    ├── GtkCellRendererProgress
                    ├── GtkCellRendererSpinner
                    ╰── GtkCellRendererToggle

## Includes

    #include <gtk/gtk.h>

## Description

The GtkCellRenderer is a base class of a set of objects used for rendering a cell to a GdkDrawable. These objects are used primarily by the GtkTreeView widget, though they aren't tied to them in any specific way. It is worth noting that GtkCellRenderer is not a GtkWidget and cannot be treated as such.

The primary use of a GtkCellRenderer is for drawing a certain graphical elements on a GdkDrawable. Typically, one cell renderer is used to draw many cells on the screen. To this extent, it isn't expected that a CellRenderer keep any permanent state around. Instead, any state is set just prior to use using GObjects property system. Then, the cell is measured using `gtk_cell_renderer_get_size()`. Finally, the cell is rendered in the correct location using `gtk_cell_renderer_render()`.

There are a number of rules that must be followed when writing a new GtkCellRenderer. First and formost, it's important that a certain set of properties will always yield a cell renderer of the same size, barring a GtkStyle change. The GtkCellRenderer also has a number of generic properties that are expected to be honored by all children.

Beyond merely rendering a cell, cell renderers can optionally provide active user interface elements. A cell renderer can be activatable like GtkCellRendererToggle, which toggles when it gets activated by a mouse click, or it can be editable like GtkCellRendererText, which allows the user to edit the text using a GtkEntry. To make a cell renderer activatable or editable, you have to implement the `activate` or `start_editing` virtual functions, respectively.

## Functions

### gtk_cell_renderer_get_size ()

    void
    gtk_cell_renderer_get_size (GtkCellRenderer *cell,
                                GtkWidget *widget,
                                const GdkRectangle *cell_area,
                                gint *x_offset,
                                gint *y_offset,
                                gint *width,
                                gint *height);

Obtains the width and height needed to render the cell. Used by view widgets to determine the appropriate size for the cell_area passed to `gtk_cell_renderer_render()`. If `cell_area` is not `NULL`, fills in the x and y offsets (if set) of the cell relative to this location.

Please note that the values set in `width` and `height` , as well as those in `x_offset` and `y_offset` are inclusive of the xpad and ypad properties.

#### Parameters

cell | a GtkCellRenderer |
widget | the widget the renderer is rendering to |
cell_area | The area a cell will be allocated, or `NULL`. | [allow-none]
x_offset | location to return x offset of cell relative to `cell_area` , or `NULL`. | [out][allow-none]
y_offset | location to return y offset of cell relative to `cell_area` , or `NULL`. | [out][allow-none]
width | location to return width needed to render a cell, or `NULL`. | [out][allow-none]
height | location to return height needed to render a cell, or `NULL`. | [out][allow-none]

### gtk_cell_renderer_render ()

    void
    gtk_cell_renderer_render (GtkCellRenderer *cell,
                              GdkWindow *window,
                              GtkWidget *widget,
                              const GdkRectangle *background_area,
                              const GdkRectangle *cell_area,
                              const GdkRectangle *expose_area,
                              GtkCellRendererState flags);

Invokes the virtual render function of the GtkCellRenderer. The three passed-in rectangles are areas of `window` . Most renderers will draw within `cell_area` ; the xalign, yalign, xpad, and ypad fields of the GtkCellRenderer should be honored with respect to `cell_area` . `background_area` includes the blank space around the cell, and also the area containing the tree expander; so the `background_area` rectangles for all cells tile to cover the entire `window` . `expose_area` is a clip rectangle.

#### Parameters

cell | a GtkCellRenderer |
window | a GdkDrawable to draw to |
widget | the widget owning `window` |
background_area | entire cell area (including tree expanders and maybe padding on the sides) |
cell_area | area normally rendered by a cell renderer |
expose_area | area that actually needs updating |
flags | flags that affect rendering |

### gtk_cell_renderer_activate ()

    gboolean
    gtk_cell_renderer_activate (GtkCellRenderer *cell,
                                GdkEvent *event,
                                GtkWidget *widget,
                                const gchar *path,
                                const GdkRectangle *background_area,
                                const GdkRectangle *cell_area,
                                GtkCellRendererState flags);

Passes an activate event to the cell renderer for possible processing. Some cell renderers may use events; for example, GtkCellRendererToggle toggles when it gets a mouse click.

#### Parameters

cell | a GtkCellRenderer |
event | a GdkEvent |
widget | widget that received the event |
path | widget-dependent string representation of the event location; e.g. for GtkTreeView, a string representation of GtkTreePath |
background_area | background area as passed to `gtk_cell_renderer_render()` |
cell_area | cell area as passed to `gtk_cell_renderer_render()` |
flags | render flags |

#### Returns

`TRUE` if the event was consumed/handled

### gtk_cell_renderer_start_editing ()

    GtkCellEditable *
    gtk_cell_renderer_start_editing (GtkCellRenderer *cell,
                                     GdkEvent *event,
                                     GtkWidget *widget,
                                     const gchar *path,
                                     const GdkRectangle *background_area,
                                     const GdkRectangle *cell_area,
                                     GtkCellRendererState flags);

Passes an activate event to the cell renderer for possible processing.

#### Parameters

cell | a GtkCellRenderer |
event | a GdkEvent |
widget | widget that received the event |
path | widget-dependent string representation of the event location; e.g. for GtkTreeView, a string representation of GtkTreePath |
background_area | background area as passed to `gtk_cell_renderer_render()` |
cell_area | cell area as passed to `gtk_cell_renderer_render()` |
flags | render flags |

#### Returns

A new GtkCellEditable, or `NULL`.

[transfer none]

### gtk_cell_renderer_editing_canceled ()

    void
    gtk_cell_renderer_editing_canceled (GtkCellRenderer *cell);

`gtk_cell_renderer_editing_canceled` has been deprecated since version 2.6 and should not be used in newly-written code.

Use `gtk_cell_renderer_stop_editing()` instead

Causes the cell renderer to emit the “editing-canceled” signal.

This function is for use only by implementations of cell renderers that need to notify the client program that an editing process was canceled and the changes were not committed.

#### Parameters

cell | A GtkCellRenderer |

Since: 2.4

### gtk_cell_renderer_stop_editing ()

    void
    gtk_cell_renderer_stop_editing (GtkCellRenderer *cell,
                                    gboolean canceled);

Informs the cell renderer that the editing is stopped. If `canceled` is `TRUE`, the cell renderer will emit the “editing-canceled” signal.

This function should be called by cell renderer implementations in response to the “editing-done” signal of GtkCellEditable.

#### Parameters

cell | A GtkCellRenderer |
canceled | `TRUE` if the editing has been canceled |

Since: 2.6

### gtk_cell_renderer_get_fixed_size ()

    void
    gtk_cell_renderer_get_fixed_size (GtkCellRenderer *cell,
                                      gint *width,
                                      gint *height);

Fills in `width` and `height` with the appropriate size of `cell` .

#### Parameters

cell | A GtkCellRenderer |
width | location to fill in with the fixed width of the cell, or `NULL`. | [out][allow-none]
height | location to fill in with the fixed height of the cell, or `NULL`. | [out][allow-none]

### gtk_cell_renderer_set_fixed_size ()

    void
    gtk_cell_renderer_set_fixed_size (GtkCellRenderer *cell,
                                      gint width,
                                      gint height);

Sets the renderer size to be explicit, independent of the properties set.

#### Parameters

cell | A GtkCellRenderer |
width | the width of the cell renderer, or -1 |
height | the height of the cell renderer, or -1 |

### gtk_cell_renderer_get_visible ()

    gboolean
    gtk_cell_renderer_get_visible (GtkCellRenderer *cell);

Returns the cell renderer's visibility.

#### Parameters

cell | A GtkCellRenderer |

#### Returns

`TRUE` if the cell renderer is visible

Since: 2.18

### gtk_cell_renderer_set_visible ()

    void
    gtk_cell_renderer_set_visible (GtkCellRenderer *cell,
                                   gboolean visible);

Sets the cell renderer's visibility.

#### Parameters

cell | A GtkCellRenderer |
visible | the visibility of the cell |

Since: 2.18

### gtk_cell_renderer_get_sensitive ()

    gboolean
    gtk_cell_renderer_get_sensitive (GtkCellRenderer *cell);

Returns the cell renderer's sensitivity.

#### Parameters

cell | A GtkCellRenderer |

#### Returns

`TRUE` if the cell renderer is sensitive

Since: 2.18

### gtk_cell_renderer_set_sensitive ()

    void
    gtk_cell_renderer_set_sensitive (GtkCellRenderer *cell,
                                     gboolean sensitive);

Sets the cell renderer's sensitivity.

#### Parameters

cell | A GtkCellRenderer |
sensitive | the sensitivity of the cell |

Since: 2.18

### gtk_cell_renderer_get_alignment ()

    void
    gtk_cell_renderer_get_alignment (GtkCellRenderer *cell,
                                     gfloat *xalign,
                                     gfloat *yalign);

Fills in `xalign` and `yalign` with the appropriate values of `cell` .

#### Parameters

cell | A GtkCellRenderer |
xalign | location to fill in with the x alignment of the cell, or `NULL`. | [out][allow-none]
yalign | location to fill in with the y alignment of the cell, or `NULL`. | [out][allow-none]

Since: 2.18

### gtk_cell_renderer_set_alignment ()

    void
    gtk_cell_renderer_set_alignment (GtkCellRenderer *cell,
                                     gfloat xalign,
                                     gfloat yalign);

Sets the renderer's alignment within its available space.

#### Parameters

cell | A GtkCellRenderer |
xalign | the x alignment of the cell renderer |
yalign | the y alignment of the cell renderer |

Since: 2.18

### gtk_cell_renderer_get_padding ()

    void
    gtk_cell_renderer_get_padding (GtkCellRenderer *cell,
                                   gint *xpad,
                                   gint *ypad);

Fills in `xpad` and `ypad` with the appropriate values of `cell` .

#### Parameters

cell | A GtkCellRenderer |
xpad | location to fill in with the x padding of the cell, or `NULL`. | [out][allow-none]
ypad | location to fill in with the y padding of the cell, or `NULL`. | [out][allow-none]

Since: 2.18

### gtk_cell_renderer_set_padding ()

    void
    gtk_cell_renderer_set_padding (GtkCellRenderer *cell,
                                   gint xpad,
                                   gint ypad);

Sets the renderer's padding.

#### Parameters

cell | A GtkCellRenderer |
xpad | the x padding of the cell renderer |
ypad | the y padding of the cell renderer |

Since: 2.18

## Types and Values

### enum GtkCellRendererState

Tells how a cell is to be rendererd.

#### Members

GTK_CELL_RENDERER_SELECTED | The cell is currently selected, and probably has a selection colored background to render to. |
GTK_CELL_RENDERER_PRELIT | The mouse is hovering over the cell. |
GTK_CELL_RENDERER_INSENSITIVE | The cell is drawn in an insensitive manner |
GTK_CELL_RENDERER_SORTED | The cell is in a sorted row |
GTK_CELL_RENDERER_FOCUSED | The cell is in the focus row. |

### enum GtkCellRendererMode

Identifies how the user can interact with a particular cell.

#### Members

GTK_CELL_RENDERER_MODE_INERT | The cell is just for display and cannot be interacted with. Note that this doesn't mean that eg. the row being drawn can't be selected -- just that a particular element of it cannot be individually modified. |
GTK_CELL_RENDERER_MODE_ACTIVATABLE | The cell can be clicked. |
GTK_CELL_RENDERER_MODE_EDITABLE | The cell can be edited or otherwise modified. |

### struct GtkCellRenderer

    struct GtkCellRenderer;

### struct GtkCellRendererClass

    struct GtkCellRendererClass {
      GtkObjectClass parent_class;

      /* vtable - not signals */
      void             (* get_size)      (GtkCellRenderer      *cell,
    				      GtkWidget            *widget,
    				      GdkRectangle         *cell_area,
    				      gint                 *x_offset,
    				      gint                 *y_offset,
    				      gint                 *width,
    				      gint                 *height);
      void             (* render)        (GtkCellRenderer      *cell,
    				      GdkDrawable          *window,
    				      GtkWidget            *widget,
    				      GdkRectangle         *background_area,
    				      GdkRectangle         *cell_area,
    				      GdkRectangle         *expose_area,
    				      GtkCellRendererState  flags);
      gboolean         (* activate)      (GtkCellRenderer      *cell,
    				      GdkEvent             *event,
    				      GtkWidget            *widget,
    				      const gchar          *path,
    				      GdkRectangle         *background_area,
    				      GdkRectangle         *cell_area,
    				      GtkCellRendererState  flags);
      GtkCellEditable *(* start_editing) (GtkCellRenderer      *cell,
    				      GdkEvent             *event,
    				      GtkWidget            *widget,
    				      const gchar          *path,
    				      GdkRectangle         *background_area,
    				      GdkRectangle         *cell_area,
    				      GtkCellRendererState  flags);

      /* Signals */
      void (* editing_canceled) (GtkCellRenderer *cell);
      void (* editing_started)  (GtkCellRenderer *cell,
    			     GtkCellEditable *editable,
    			     const gchar     *path);

      /* Padding for future expansion */
      void (*_gtk_reserved1) (void);
      void (*_gtk_reserved2) (void);
    };

## Property Details

### The `“cell-background”` property

      “cell-background”          gchar *

Cell background color as a string.

Flags: Write

Default value: NULL

### The `“cell-background-gdk”` property

      “cell-background-gdk”      GdkColor *

Cell background color as a GdkColor.

Flags: Read / Write

### The `“cell-background-set”` property

      “cell-background-set”      gboolean

Whether this tag affects the cell background color.

Flags: Read / Write

Default value: FALSE

### The `“editing”` property

      “editing”                  gboolean

Whether the cell renderer is currently in editing mode.

Flags: Read

Default value: FALSE

### The `“height”` property

      “height”                   gint

The fixed height.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

### The `“is-expanded”` property

      “is-expanded”              gboolean

Row is an expander row, and is expanded.

Flags: Read / Write

Default value: FALSE

### The `“is-expander”` property

      “is-expander”              gboolean

Row has children.

Flags: Read / Write

Default value: FALSE

### The `“mode”` property

      “mode”                     GtkCellRendererMode

Editable mode of the CellRenderer.

Flags: Read / Write

Default value: GTK_CELL_RENDERER_MODE_INERT

### The `“sensitive”` property

      “sensitive”                gboolean

Display the cell sensitive.

Flags: Read / Write

Default value: TRUE

### The `“visible”` property

      “visible”                  gboolean

Display the cell.

Flags: Read / Write

Default value: TRUE

### The `“width”` property

      “width”                    gint

The fixed width.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

### The `“xalign”` property

      “xalign”                   gfloat

The x-align.

Flags: Read / Write

Allowed values: [0,1]

Default value: 0.5

### The `“xpad”` property

      “xpad”                     guint

The xpad.

Flags: Read / Write

Default value: 0

### The `“yalign”` property

      “yalign”                   gfloat

The y-align.

Flags: Read / Write

Allowed values: [0,1]

Default value: 0.5

### The `“ypad”` property

      “ypad”                     guint

The ypad.

Flags: Read / Write

Default value: 0

## Signal Details

### The `“editing-canceled”` signal

    void
    user_function (GtkCellRenderer *renderer,
                   gpointer         user_data)

This signal gets emitted when the user cancels the process of editing a cell. For example, an editable cell renderer could be written to cancel editing when the user presses Escape.

See also: `gtk_cell_renderer_stop_editing()`.

#### Parameters

renderer | the object which received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 2.4

### The `“editing-started”` signal

    void
    user_function (GtkCellRenderer *renderer,
                   GtkCellEditable *editable,
                   gchar           *path,
                   gpointer         user_data)

This signal gets emitted when a cell starts to be edited. The intended use of this signal is to do special setup on `editable` , e.g. adding a GtkEntryCompletion or setting up additional columns in a GtkComboBox.

Note that GTK+ doesn't guarantee that cell renderers will continue to use the same kind of widget for editing in future releases, therefore you should check the type of `editable` before doing any specific setup, as in the following example:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    static void
    text_editing_started (GtkCellRenderer *cell,
                          GtkCellEditable *editable,
                          const gchar     *path,
                          gpointer         data)
    {
      if (GTK_IS_ENTRY (editable))

        {
          GtkEntry *entry = GTK_ENTRY (editable);

          /* ... create a GtkEntryCompletion */

          gtk_entry_set_completion (entry, completion);
        }
    }

#### Parameters

renderer | the object which received the signal |
editable | the GtkCellEditable |
path | the path identifying the edited cell |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 2.6

## See Also

GtkCellRendererText,GtkCellRendererPixbuf,GtkCellRendererToggle