CellRenderer

Deprecated since version 4.10: List views use widgets for displaying their contents

class CellRenderer(**properties: Any)

Superclasses: InitiallyUnowned, Object

Subclasses: CellRendererPixbuf, CellRendererProgress, CellRendererSpinner, CellRendererText, CellRendererToggle

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 GObject’s property system. Then, the cell is measured using get_preferred_size(). Finally, the cell is rendered in the correct location using 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 GtkCellRenderer``Toggle, which toggles when it gets activated by a mouse click, or it can be “editable” like ``GtkCellRenderer``Text, 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 ``GtkCellRenderer``Class.activate or ``GtkCellRenderer``Class.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

class CellRenderer
activate(event: Event, widget: Widget, path: str, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) → bool

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.

Deprecated since version 4.10: Please do not use it in newly written code

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(widget: Widget, flags: CellRendererState, cell_area: Rectangle) → Rectangle

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

Deprecated since version 4.10: Please do not use it in newly written code

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() → tuple[float, float]

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

Deprecated since version 4.10: Please do not use it in newly written code

get_fixed_size() → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

get_is_expanded() → bool

Checks whether the given GtkCellRenderer is expanded.

Deprecated since version 4.10: Please do not use it in newly written code

get_is_expander() → bool

Checks whether the given GtkCellRenderer is an expander.

Deprecated since version 4.10: Please do not use it in newly written code

get_padding() → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

get_preferred_height(widget: Widget) → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

widget – the GtkWidget this cell will be rendering to

get_preferred_height_for_width(widget: Widget, width: int) → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

  • widget – the GtkWidget this cell will be rendering to

  • width – the size which is available for allocation

get_preferred_size(widget: Widget) → tuple[Requisition, Requisition]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

widget – the GtkWidget this cell will be rendering to

get_preferred_width(widget: Widget) → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

widget – the GtkWidget this cell will be rendering to

get_preferred_width_for_height(widget: Widget, height: int) → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

  • widget – the GtkWidget this cell will be rendering to

  • height – the size which is available for allocation

get_request_mode() → SizeRequestMode

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

Deprecated since version 4.10: Please do not use it in newly written code

get_sensitive() → bool

Returns the cell renderer’s sensitivity.

Deprecated since version 4.10: Please do not use it in newly written code

get_state(widget: Widget | None, cell_state: CellRendererState) → StateFlags

Translates the cell renderer state to GtkStateFlags, based on the cell renderer and widget sensitivity, and the given ``GtkCellRenderer``State.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

  • widget – a GtkWidget

  • cell_state – cell renderer state

get_visible() → bool

Returns the cell renderer’s visibility.

Deprecated since version 4.10: Please do not use it in newly written code

is_activatable() → bool

Checks whether the cell renderer can do something when activated.

Deprecated since version 4.10: Please do not use it in newly written code

set_alignment(xalign: float, yalign: float) → None

Sets the renderer’s alignment within its available space.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

  • xalign – the x alignment of the cell renderer

  • yalign – the y alignment of the cell renderer

set_fixed_size(width: int, height: int) → None

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

  • width – the width of the cell renderer, or -1

  • height – the height of the cell renderer, or -1

set_is_expanded(is_expanded: bool) → None

Sets whether the given GtkCellRenderer is expanded.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

is_expanded – whether cell should be expanded

set_is_expander(is_expander: bool) → None

Sets whether the given GtkCellRenderer is an expander.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

is_expander – whether cell is an expander

set_padding(xpad: int, ypad: int) → None

Sets the renderer’s padding.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

  • xpad – the x padding of the cell renderer

  • ypad – the y padding of the cell renderer

set_sensitive(sensitive: bool) → None

Sets the cell renderer’s sensitivity.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

sensitive – the sensitivity of the cell

set_visible(visible: bool) → None

Sets the cell renderer’s visibility.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

visible – the visibility of the cell

snapshot(snapshot: Snapshot, widget: Widget, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) → None

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.

Deprecated since version 4.10: Please do not use it in newly written code

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(event: Event | None, widget: Widget, path: str, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) → CellEditable | None

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

Deprecated since version 4.10: Please do not use it in newly written code

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(canceled: bool) → None

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.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

canceled – True if the editing has been canceled

Properties

class CellRenderer
props.cell_background: str
props.cell_background_rgba: RGBA

Cell background as a GdkRGBA

props.cell_background_set: bool
props.editing: bool
props.height: int
props.is_expanded: bool
props.is_expander: bool
props.mode: CellRendererMode
props.sensitive: bool
props.visible: bool
props.width: int
props.xalign: float
props.xpad: int
props.yalign: float
props.ypad: int

Signals

class CellRenderer.signals
editing_canceled() → 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: stop_editing().

editing_started(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 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);
    }
}
Parameters:

  • editable – the GtkCellEditable

  • path – the path identifying the edited cell

Virtual Methods

class CellRenderer
do_activate(event: Event, widget: Widget, path: str, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) → bool

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.

Deprecated since version 4.10: Please do not use it in newly written code

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() → None

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

do_editing_started(editable: CellEditable, path: str) → None

Signal gets emitted when a cell starts to be edited.

Parameters:

  • editable

  • path

do_get_aligned_area(widget: Widget, flags: CellRendererState, cell_area: Rectangle) → Rectangle

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

Deprecated since version 4.10: Please do not use it in newly written code

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(widget: Widget) → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

widget – the GtkWidget this cell will be rendering to

do_get_preferred_height_for_width(widget: Widget, width: int) → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

  • widget – the GtkWidget this cell will be rendering to

  • width – the size which is available for allocation

do_get_preferred_width(widget: Widget) → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

widget – the GtkWidget this cell will be rendering to

do_get_preferred_width_for_height(widget: Widget, height: int) → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

  • widget – the GtkWidget this cell will be rendering to

  • height – the size which is available for allocation

do_get_request_mode() → SizeRequestMode

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

Deprecated since version 4.10: Please do not use it in newly written code

do_snapshot(snapshot: Snapshot, widget: Widget, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) → None

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.

Deprecated since version 4.10: Please do not use it in newly written code

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(event: Event | None, widget: Widget, path: str, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) → CellEditable | None

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

Deprecated since version 4.10: Please do not use it in newly written code

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

Fields

class CellRenderer
parent_instance
priv