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

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

do_activate(self, event: Event, widget: Widget, path: str, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) → bool#
Parameters:

  • event

  • widget

  • path

  • background_area

  • cell_area

  • flags

do_editing_canceled(self) → None#
do_editing_started(self, editable: CellEditable, path: str) → None#
Parameters:

  • editable

  • path

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

  • widget

  • flags

  • cell_area

do_get_preferred_height(self, widget: Widget) → tuple[int, int]#
Parameters:

widget

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

  • widget

  • width

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

widget

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

  • widget

  • height

do_get_request_mode(self) → SizeRequestMode#
do_snapshot(self, snapshot: Snapshot, widget: Widget, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) → None#
Parameters:

  • snapshot

  • widget

  • background_area

  • cell_area

  • flags

do_start_editing(self, event: Event | None, widget: Widget, path: str, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) → CellEditable | None#
Parameters:

  • event

  • widget

  • path

  • background_area

  • cell_area

  • 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 GtkCellRendererState.

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

The type of the None singleton.

props.cell_background_rgba: RGBA#

The type of the None singleton.

props.cell_background_set: bool#

The type of the None singleton.

props.editing: bool#

The type of the None singleton.

props.height: int#

The type of the None singleton.

props.is_expanded: bool#

The type of the None singleton.

props.is_expander: bool#

The type of the None singleton.

props.mode: CellRendererMode#

The type of the None singleton.

props.sensitive: bool#

The type of the None singleton.

props.visible: bool#

The type of the None singleton.

props.width: int#

The type of the None singleton.

props.xalign: float#

The type of the None singleton.

props.xpad: int#

The type of the None singleton.

props.yalign: float#

The type of the None singleton.

props.ypad: int#

The type of the None singleton.

Signals#

class CellRenderer.signals
editing_canceled() → None#

The type of the None singleton.

editing_started(editable: CellEditable, path: str) → None#

The type of the None singleton.

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#

The type of the None singleton.

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

The type of the None singleton.

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 GtkCellRendererClass.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#
On this page

This Page