GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkCellRenderer

## Name

GtkCellRenderer --

## Synopsis

    #include <gtk/gtk.h>

    enum        GtkCellRendererState;
    enum        GtkCellRendererMode;
    struct      GtkCellRenderer;
    void        gtk_cell_renderer_get_size      (GtkCellRenderer *cell,
                                                 GtkWidget *widget,
                                                 GdkRectangle *cell_area,
                                                 gint *x_offset,
                                                 gint *y_offset,
                                                 gint *width,
                                                 gint *height);
    void        gtk_cell_renderer_render        (GtkCellRenderer *cell,
                                                 GdkWindow *window,
                                                 GtkWidget *widget,
                                                 GdkRectangle *background_area,
                                                 GdkRectangle *cell_area,
                                                 GdkRectangle *expose_area,
                                                 GtkCellRendererState flags);
    gboolean    gtk_cell_renderer_activate      (GtkCellRenderer *cell,
                                                 GdkEvent *event,
                                                 GtkWidget *widget,
                                                 const gchar *path,
                                                 GdkRectangle *background_area,
                                                 GdkRectangle *cell_area,
                                                 GtkCellRendererState flags);
    GtkCellEditable* gtk_cell_renderer_start_editing
                                                (GtkCellRenderer *cell,
                                                 GdkEvent *event,
                                                 GtkWidget *widget,
                                                 const gchar *path,
                                                 GdkRectangle *background_area,
                                                 GdkRectangle *cell_area,
                                                 GtkCellRendererState flags);
    void        gtk_cell_renderer_get_fixed_size
                                                (GtkCellRenderer *cell,
                                                 gint *width,
                                                 gint *height);
    void        gtk_cell_renderer_set_fixed_size
                                                (GtkCellRenderer *cell,
                                                 gint width,
                                                 gint height);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkCellRenderer

## Properties

      "mode"                 GtkCellRendererMode  : Read / Write
      "visible"              gboolean             : Read / Write
      "xalign"               gfloat               : Read / Write
      "yalign"               gfloat               : Read / Write
      "xpad"                 guint                : Read / Write
      "ypad"                 guint                : Read / Write
      "width"                gint                 : Read / Write
      "height"               gint                 : Read / Write
      "is-expander"          gboolean             : Read / Write
      "is-expanded"          gboolean             : Read / Write
      "cell-background"      gchararray           : Write
      "cell-background-gdk"  GdkColor             : Read / Write
      "cell-background-set"  gboolean             : Read / Write

## Description

## Details

### enum GtkCellRendererState

    typedef enum
    {
      GTK_CELL_RENDERER_SELECTED    = 1 << 0,
      GTK_CELL_RENDERER_PRELIT      = 1 << 1,
      GTK_CELL_RENDERER_INSENSITIVE = 1 << 2,
      /* this flag means the cell is in the sort column/row */
      GTK_CELL_RENDERER_SORTED      = 1 << 3
    } GtkCellRendererState;

### enum GtkCellRendererMode

    typedef enum
    {
      GTK_CELL_RENDERER_MODE_INERT,
      GTK_CELL_RENDERER_MODE_ACTIVATABLE,
      GTK_CELL_RENDERER_MODE_EDITABLE
    } GtkCellRendererMode;

### struct GtkCellRenderer

    struct GtkCellRenderer;

### gtk_cell_renderer_get_size ()

    void        gtk_cell_renderer_get_size      (GtkCellRenderer *cell,
                                                 GtkWidget *widget,
                                                 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.

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

### gtk_cell_renderer_render ()

    void        gtk_cell_renderer_render        (GtkCellRenderer *cell,
                                                 GdkWindow *window,
                                                 GtkWidget *widget,
                                                 GdkRectangle *background_area,
                                                 GdkRectangle *cell_area,
                                                 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.

`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,
                                                 GdkRectangle *background_area,
                                                 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.

`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,
                                                 GdkRectangle *background_area,
                                                 GdkRectangle *cell_area,
                                                 GtkCellRendererState flags);

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

`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`

### 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`.

`cell` : | A GtkCellRenderer
`width` : | location to fill in with the fixed width of the widget, or `NULL`
`height` : | location to fill in with the fixed height of the widget, or `NULL`

### 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.

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

## Properties

"`mode`" (GtkCellRendererMode : Read / Write)

  Editable mode of the CellRenderer

"`visible`" (gboolean : Read / Write)

  Display the cell

"`xalign`" (gfloat : Read / Write)

  The x-align.

"`yalign`" (gfloat : Read / Write)

  The y-align.

"`xpad`" (guint : Read / Write)

  The xpad.

"`ypad`" (guint : Read / Write)

  The ypad.

"`width`" (gint : Read / Write)

  The fixed width.

"`height`" (gint : Read / Write)

  The fixed height.

"`is-expander`" (gboolean : Read / Write)

  Row has children.

"`is-expanded`" (gboolean : Read / Write)

  Row is an expander row, and is expanded

"`cell-background`" (gchararray : Write)

  Cell background color as a string

"`cell-background-gdk`" (GdkColor : Read / Write)

  Cell background color as a GdkColor

"`cell-background-set`" (gboolean : Read / Write)

  Whether this tag affects the cell background color

<<< Previous Page | Home | Up | Next Page >>>
GtkTreeModelSort | GtkCellEditable