Skip to content

Gtk.CellRenderer

class — extends GObject.InitiallyUnowned

:::warning Deprecated since 4.10 This API is deprecated. :::

An object for rendering a single cell

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 CellRenderer.get_preferred_size. Finally, the cell is rendered in the correct location using CellRenderer.snapshot.

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 style 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 widget implementing the GtkCellEditable interface, e.g. 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.

Methods

activate

def activate(self, event: Gdk.Event, widget: Widget, path: str, background_area: Gdk.Rectangle, cell_area: Gdk.Rectangle, flags: CellRendererState | int) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

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:

  • 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

get_aligned_area

def get_aligned_area(self, widget: Widget, flags: CellRendererState | int, cell_area: Gdk.Rectangle) -> Gdk.Rectangle

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • 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()

get_alignment

def get_alignment(self) -> tuple[float, float]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

get_fixed_size

def get_fixed_size(self) -> tuple[int, int]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

get_is_expanded

def get_is_expanded(self) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Checks whether the given GtkCellRenderer is expanded.

get_is_expander

def get_is_expander(self) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Checks whether the given GtkCellRenderer is an expander.

get_padding

def get_padding(self) -> tuple[int, int]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

get_preferred_height

def get_preferred_height(self, widget: Widget) -> tuple[int, int]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • widget — the GtkWidget this cell will be rendering to

get_preferred_height_for_width

def get_preferred_height_for_width(self, widget: Widget, width: int) -> tuple[int, int]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • widget — the GtkWidget this cell will be rendering to
  • width — the size which is available for allocation

get_preferred_size

def get_preferred_size(self, widget: Widget) -> tuple[Requisition, Requisition]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • widget — the GtkWidget this cell will be rendering to

get_preferred_width

def get_preferred_width(self, widget: Widget) -> tuple[int, int]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • widget — the GtkWidget this cell will be rendering to

get_preferred_width_for_height

def get_preferred_width_for_height(self, widget: Widget, height: int) -> tuple[int, int]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • widget — the GtkWidget this cell will be rendering to
  • height — the size which is available for allocation

get_request_mode

def get_request_mode(self) -> SizeRequestMode

:::warning Deprecated since 4.10 This API is deprecated. :::

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

get_sensitive

def get_sensitive(self) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the cell renderer’s sensitivity.

get_state

def get_state(self, widget: Widget | None, cell_state: CellRendererState | int) -> StateFlags

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • widget — a GtkWidget
  • cell_state — cell renderer state

get_visible

def get_visible(self) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the cell renderer’s visibility.

is_activatable

def is_activatable(self) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Checks whether the cell renderer can do something when activated.

set_alignment

def set_alignment(self, xalign: float, yalign: float) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the renderer’s alignment within its available space.

Parameters:

  • xalign — the x alignment of the cell renderer
  • yalign — the y alignment of the cell renderer

set_fixed_size

def set_fixed_size(self, width: int, height: int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • width — the width of the cell renderer, or -1
  • height — the height of the cell renderer, or -1

set_is_expanded

def set_is_expanded(self, is_expanded: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets whether the given GtkCellRenderer is expanded.

Parameters:

  • is_expanded — whether cell should be expanded

set_is_expander

def set_is_expander(self, is_expander: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets whether the given GtkCellRenderer is an expander.

Parameters:

  • is_expander — whether cell is an expander

set_padding

def set_padding(self, xpad: int, ypad: int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the renderer’s padding.

Parameters:

  • xpad — the x padding of the cell renderer
  • ypad — the y padding of the cell renderer

set_sensitive

def set_sensitive(self, sensitive: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the cell renderer’s sensitivity.

Parameters:

  • sensitive — the sensitivity of the cell

set_visible

def set_visible(self, visible: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the cell renderer’s visibility.

Parameters:

  • visible — the visibility of the cell

snapshot

def snapshot(self, snapshot: Snapshot, widget: Widget, background_area: Gdk.Rectangle, cell_area: Gdk.Rectangle, flags: CellRendererState | int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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:

  • snapshot — a GtkSnapshot 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

start_editing

def start_editing(self, event: Gdk.Event | None, widget: Widget, path: str, background_area: Gdk.Rectangle, cell_area: Gdk.Rectangle, flags: CellRendererState | int) -> CellEditable | None

:::warning Deprecated since 4.10 This API is deprecated. :::

Starts editing the contents of this cell, through a new GtkCellEditable widget created by the GtkCellRendererClass.start_editing virtual function.

Parameters:

  • 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

stop_editing

def stop_editing(self, canceled: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Informs the cell renderer that the editing is stopped. If canceled is True, the cell renderer will emit the GtkCellRenderer::editing-canceled signal.

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

Parameters:

  • canceled — True if the editing has been canceled

Virtual methods

do_activate

def do_activate(self, event: Gdk.Event, widget: Widget, path: str, background_area: Gdk.Rectangle, cell_area: Gdk.Rectangle, flags: CellRendererState | int) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

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:

  • 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

do_editing_canceled

def do_editing_canceled(self) -> None

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

do_editing_started

def do_editing_started(self, editable: CellEditable, path: str) -> None

Signal gets emitted when a cell starts to be edited.

do_get_aligned_area

def do_get_aligned_area(self, widget: Widget, flags: CellRendererState | int, cell_area: Gdk.Rectangle) -> Gdk.Rectangle

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • 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()

do_get_preferred_height

def do_get_preferred_height(self, widget: Widget) -> tuple[int, int]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • widget — the GtkWidget this cell will be rendering to

do_get_preferred_height_for_width

def do_get_preferred_height_for_width(self, widget: Widget, width: int) -> tuple[int, int]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • widget — the GtkWidget this cell will be rendering to
  • width — the size which is available for allocation

do_get_preferred_width

def do_get_preferred_width(self, widget: Widget) -> tuple[int, int]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • widget — the GtkWidget this cell will be rendering to

do_get_preferred_width_for_height

def do_get_preferred_width_for_height(self, widget: Widget, height: int) -> tuple[int, int]

:::warning Deprecated since 4.10 This API is deprecated. :::

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

Parameters:

  • widget — the GtkWidget this cell will be rendering to
  • height — the size which is available for allocation

do_get_request_mode

def do_get_request_mode(self) -> SizeRequestMode

:::warning Deprecated since 4.10 This API is deprecated. :::

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

do_snapshot

def do_snapshot(self, snapshot: Snapshot, widget: Widget, background_area: Gdk.Rectangle, cell_area: Gdk.Rectangle, flags: CellRendererState | int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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:

  • snapshot — a GtkSnapshot 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

do_start_editing

def do_start_editing(self, event: Gdk.Event | None, widget: Widget, path: str, background_area: Gdk.Rectangle, cell_area: Gdk.Rectangle, flags: CellRendererState | int) -> CellEditable | None

:::warning Deprecated since 4.10 This API is deprecated. :::

Starts editing the contents of this cell, through a new GtkCellEditable widget created by the GtkCellRendererClass.start_editing virtual function.

Parameters:

  • 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

Properties

cell_background

cell_background: str  # read/write

cell_background_rgba

cell_background_rgba: Gdk.RGBA  # read/write

Cell background as a GdkRGBA

cell_background_set

cell_background_set: bool  # read/write

editing

editing: bool  # read-only

height

height: int  # read/write

is_expanded

is_expanded: bool  # read/write

is_expander

is_expander: bool  # read/write

mode

mode: CellRendererMode | int  # read/write

sensitive

sensitive: bool  # read/write

visible

visible: bool  # read/write

width

width: int  # read/write

xalign

xalign: float  # read/write

xpad

xpad: int  # read/write

yalign

yalign: float  # read/write

ypad

ypad: int  # read/write

Signals

editing-canceled

def on_editing_canceled(self) -> None: ...

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: CellRenderer.stop_editing.

editing-started

def on_editing_started(self, editable: CellEditable, path: str) -> None: ...

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.

See CellEditable.start_editing for information on the lifecycle of the editable and a way to do setup that doesn’t depend on the renderer.

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:

static void
text_editing_started (GtkCellRenderer *cell,
                      GtkCellEditable *editable,
                      const char      *path,
                      gpointer         data)
{
  if (GTK_IS_ENTRY (editable))
    {
      GtkEntry *entry = GTK_ENTRY (editable);

      // ... create a GtkEntryCompletion

      gtk_entry_set_completion (entry, completion);
    }
}