GtkCellRenderer

GtkCellRenderer — An object for rendering a single cell

Properties

gchar * cell-background Write
GdkColor * cell-background-gdk Read / Write
GdkRGBA * cell-background-rgba 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

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── 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 cairo_t. 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 cairo_t. 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 foremost, 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 GtkCellRendererClass.activate or GtkCellRendererClass.start_editing virtual functions, respectively.

Many properties of GtkCellRenderer and its subclasses have a corresponding “set” property, e.g. “cell-background-set” corresponds to “cell-background”. These “set” properties reflect whether a property has been set or not. You should not set them independently.

Functions

gtk_cell_renderer_class_set_accessible_type ()

void
gtk_cell_renderer_class_set_accessible_type
                               (GtkCellRendererClass *renderer_class,
                                GType type);

Sets the type to be used for creating accessibles for cells rendered by cell renderers of renderer_class . Note that multiple accessibles will be created.

This function should only be called from class init functions of cell renderers.

Parameters

renderer_class

class to set the accessible type for

 

type

The object type that implements the accessible for widget_class . The type must be a subtype of GtkRendererCellAccessible

 

gtk_cell_renderer_get_aligned_area ()

void
gtk_cell_renderer_get_aligned_area (GtkCellRenderer *cell,
                                    GtkWidget *widget,
                                    GtkCellRendererState flags,
                                    const GdkRectangle *cell_area,
                                    GdkRectangle *aligned_area);

Gets the aligned area used by cell inside cell_area . Used for finding the appropriate edit and focus rectangle.

Parameters

cell

a GtkCellRenderer instance

 

widget

the GtkWidget this cell will be rendering to

 

flags

render flags

 

cell_area

cell area which would be passed to gtk_cell_renderer_render()

 

aligned_area

the return location for the space inside cell_area that would acually be used to render.

[out]

Since: 3.0


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);

gtk_cell_renderer_get_size has been deprecated since version 3.0 and should not be used in newly-written code.

Use gtk_cell_renderer_get_preferred_size() instead.

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,
                          cairo_t *cr,
                          GtkWidget *widget,
                          const GdkRectangle *background_area,
                          const GdkRectangle *cell_area,
                          GtkCellRendererState flags);

Invokes the virtual render function of the GtkCellRenderer. The three passed-in rectangles are areas in cr . 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 .

Parameters

cell

a GtkCellRenderer

 

cr

a cairo context 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

 

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.

[nullable][transfer none]


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


gtk_cell_renderer_get_state ()

GtkStateFlags
gtk_cell_renderer_get_state (GtkCellRenderer *cell,
                             GtkWidget *widget,
                             GtkCellRendererState cell_state);

Translates the cell renderer state to GtkStateFlags, based on the cell renderer and widget sensitivity, and the given GtkCellRendererState.

Parameters

cell

a GtkCellRenderer, or NULL

 

widget

a GtkWidget, or NULL

 

cell_state

cell renderer state

 

Returns

the widget state flags applying to cell

Since: 3.0


gtk_cell_renderer_is_activatable ()

gboolean
gtk_cell_renderer_is_activatable (GtkCellRenderer *cell);

Checks whether the cell renderer can do something when activated.

Parameters

cell

A GtkCellRenderer

 

Returns

TRUE if the cell renderer can do anything when activated

Since: 3.0


gtk_cell_renderer_get_preferred_height ()

void
gtk_cell_renderer_get_preferred_height
                               (GtkCellRenderer *cell,
                                GtkWidget *widget,
                                gint *minimum_size,
                                gint *natural_size);

Retreives a renderer’s natural size when rendered to widget .

Parameters

cell

a GtkCellRenderer instance

 

widget

the GtkWidget this cell will be rendering to

 

minimum_size

location to store the minimum size, or NULL.

[out][allow-none]

natural_size

location to store the natural size, or NULL.

[out][allow-none]

Since: 3.0


gtk_cell_renderer_get_preferred_height_for_width ()

void
gtk_cell_renderer_get_preferred_height_for_width
                               (GtkCellRenderer *cell,
                                GtkWidget *widget,
                                gint width,
                                gint *minimum_height,
                                gint *natural_height);

Retreives a cell renderers’s minimum and natural height if it were rendered to widget with the specified width .

Parameters

cell

a GtkCellRenderer instance

 

widget

the GtkWidget this cell will be rendering to

 

width

the size which is available for allocation

 

minimum_height

location for storing the minimum size, or NULL.

[out][allow-none]

natural_height

location for storing the preferred size, or NULL.

[out][allow-none]

Since: 3.0


gtk_cell_renderer_get_preferred_size ()

void
gtk_cell_renderer_get_preferred_size (GtkCellRenderer *cell,
                                      GtkWidget *widget,
                                      GtkRequisition *minimum_size,
                                      GtkRequisition *natural_size);

Retrieves the minimum and natural size of a cell taking into account the widget’s preference for height-for-width management.

Parameters

cell

a GtkCellRenderer instance

 

widget

the GtkWidget this cell will be rendering to

 

minimum_size

location for storing the minimum size, or NULL.

[out][allow-none]

natural_size

location for storing the natural size, or NULL.

[out][allow-none]

Since: 3.0


gtk_cell_renderer_get_preferred_width ()

void
gtk_cell_renderer_get_preferred_width (GtkCellRenderer *cell,
                                       GtkWidget *widget,
                                       gint *minimum_size,
                                       gint *natural_size);

Retreives a renderer’s natural size when rendered to widget .

Parameters

cell

a GtkCellRenderer instance

 

widget

the GtkWidget this cell will be rendering to

 

minimum_size

location to store the minimum size, or NULL.

[out][allow-none]

natural_size

location to store the natural size, or NULL.

[out][allow-none]

Since: 3.0


gtk_cell_renderer_get_preferred_width_for_height ()

void
gtk_cell_renderer_get_preferred_width_for_height
                               (GtkCellRenderer *cell,
                                GtkWidget *widget,
                                gint height,
                                gint *minimum_width,
                                gint *natural_width);

Retreives a cell renderers’s minimum and natural width if it were rendered to widget with the specified height .

Parameters

cell

a GtkCellRenderer instance

 

widget

the GtkWidget this cell will be rendering to

 

height

the size which is available for allocation

 

minimum_width

location for storing the minimum size, or NULL.

[out][allow-none]

natural_width

location for storing the preferred size, or NULL.

[out][allow-none]

Since: 3.0


gtk_cell_renderer_get_request_mode ()

GtkSizeRequestMode
gtk_cell_renderer_get_request_mode (GtkCellRenderer *cell);

Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout.

Parameters

cell

a GtkCellRenderer instance

 

Returns

The GtkSizeRequestMode preferred by this renderer.

Since: 3.0

Types and Values

enum GtkCellRendererState

Tells how a cell is to be rendered.

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.

 

GTK_CELL_RENDERER_EXPANDABLE

The cell is in a row that can be expanded. Since 3.4

 

GTK_CELL_RENDERER_EXPANDED

The cell is in a row that is expanded. Since 3.4

 

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 {
  /* vtable - not signals */
  GtkSizeRequestMode (* get_request_mode)                (GtkCellRenderer      *cell);
  void               (* get_preferred_width)             (GtkCellRenderer      *cell,
                                                          GtkWidget            *widget,
                                                          gint                 *minimum_size,
                                                          gint                 *natural_size);
  void               (* get_preferred_height_for_width)  (GtkCellRenderer      *cell,
                                                          GtkWidget            *widget,
                                                          gint                  width,
                                                          gint                 *minimum_height,
                                                          gint                 *natural_height);
  void               (* get_preferred_height)            (GtkCellRenderer      *cell,
                                                          GtkWidget            *widget,
                                                          gint                 *minimum_size,
                                                          gint                 *natural_size);
  void               (* get_preferred_width_for_height)  (GtkCellRenderer      *cell,
                                                          GtkWidget            *widget,
                                                          gint                  height,
                                                          gint                 *minimum_width,
                                                          gint                 *natural_width);
  void               (* get_aligned_area)                (GtkCellRenderer      *cell,
                                                          GtkWidget            *widget,
							  GtkCellRendererState  flags,
                                                          const GdkRectangle   *cell_area,
                                                          GdkRectangle         *aligned_area);
  void               (* get_size)                        (GtkCellRenderer      *cell,
                                                          GtkWidget            *widget,
                                                          const GdkRectangle   *cell_area,
                                                          gint                 *x_offset,
                                                          gint                 *y_offset,
                                                          gint                 *width,
                                                          gint                 *height);
  void               (* render)                          (GtkCellRenderer      *cell,
                                                          cairo_t              *cr,
                                                          GtkWidget            *widget,
                                                          const GdkRectangle   *background_area,
                                                          const GdkRectangle   *cell_area,
                                                          GtkCellRendererState  flags);
  gboolean           (* activate)                        (GtkCellRenderer      *cell,
                                                          GdkEvent             *event,
                                                          GtkWidget            *widget,
                                                          const gchar          *path,
                                                          const GdkRectangle   *background_area,
                                                          const GdkRectangle   *cell_area,
                                                          GtkCellRendererState  flags);
  GtkCellEditable *  (* start_editing)                   (GtkCellRenderer      *cell,
                                                          GdkEvent             *event,
                                                          GtkWidget            *widget,
                                                          const gchar          *path,
                                                          const GdkRectangle   *background_area,
                                                          const GdkRectangle   *cell_area,
                                                          GtkCellRendererState  flags);

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

Members

get_request_mode ()

Called to gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout.

 

get_preferred_width ()

Called to get a renderer’s natural width.

 

get_preferred_height_for_width ()

Called to get a renderer’s natural height for width.

 

get_preferred_height ()

Called to get a renderer’s natural height.

 

get_preferred_width_for_height ()

Called to get a renderer’s natural width for height.

 

get_aligned_area ()

Called to get the aligned area used by cell inside cell_area .

 

get_size ()

Called to get the width and height needed to render the cell. Deprecated: 3.0.

 

render ()

Called to render the content of the GtkCellRenderer.

 

activate ()

Called to activate the content of the GtkCellRenderer.

 

start_editing ()

Called to initiate editing the content of the GtkCellRenderer.

 

editing_canceled ()

Signal gets emitted when the user cancels the process of editing a cell.

 

editing_started ()

Signal gets emitted when a cell starts to be edited.

 

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 as a GdkColor

GtkCellRenderer:cell-background-gdk has been deprecated since version 3.4 and should not be used in newly-written code.

Use “cell-background-rgba” instead.

Flags: Read / Write


The “cell-background-rgba” property

  “cell-background-rgba”     GdkRGBA *

Cell background as a GdkRGBA

Flags: Read / Write

Since: 3.0


The “cell-background-set” property

  “cell-background-set”      gboolean

Whether the cell background color is set.

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