Gtk.CellRenderer¶

Subclasses:: Gtk.CellRendererPixbuf, Gtk.CellRendererProgress, Gtk.CellRendererSpinner, Gtk.CellRendererText, Gtk.CellRendererToggle

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

	`activate` (event, widget, path, background_area, cell_area, flags)
	`get_aligned_area` (widget, flags, cell_area)
	`get_alignment` ()
	`get_fixed_size` ()
	`get_is_expanded` ()
	`get_is_expander` ()
	`get_padding` ()
	`get_preferred_height` (widget)
	`get_preferred_height_for_width` (widget, width)
	`get_preferred_size` (widget)
	`get_preferred_width` (widget)
	`get_preferred_width_for_height` (widget, height)
	`get_request_mode` ()
	`get_sensitive` ()
	`get_state` (widget, cell_state)
	`get_visible` ()
	`is_activatable` ()
	`set_alignment` (xalign, yalign)
	`set_fixed_size` (width, height)
	`set_is_expanded` (is_expanded)
	`set_is_expander` (is_expander)
	`set_padding` (xpad, ypad)
	`set_sensitive` (sensitive)
	`set_visible` (visible)
	`snapshot` (snapshot, widget, background_area, cell_area, flags)
	`start_editing` (event, widget, path, background_area, cell_area, flags)
	`stop_editing` (canceled)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_activate` (event, widget, path, background_area, cell_area, flags)
	`do_editing_canceled` ()
	`do_editing_started` (editable, path)
	`do_get_aligned_area` (widget, flags, cell_area)
	`do_get_preferred_height` (widget)
	`do_get_preferred_height_for_width` (widget, width)
	`do_get_preferred_width` (widget)
	`do_get_preferred_width_for_height` (widget, height)
	`do_get_request_mode` ()
	`do_snapshot` (snapshot, widget, background_area, cell_area, flags)
	`do_start_editing` (event, widget, path, background_area, cell_area, flags)

Properties¶

Name	Type	Flags
`cell-background`	`str`	w
`cell-background-rgba`	`Gdk.RGBA`	r/w
`cell-background-set`	`bool`	r/w/en
`editing`	`bool`	r
`height`	`int`	r/w/en
`is-expanded`	`bool`	r/w/en
`is-expander`	`bool`	r/w/en
`mode`	`Gtk.CellRendererMode`	r/w/en
`sensitive`	`bool`	r/w/en
`visible`	`bool`	r/w/en
`width`	`int`	r/w/en
`xalign`	`float`	r/w/en
`xpad`	`int`	r/w/en
`yalign`	`float`	r/w/en
`ypad`	`int`	r/w/en

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`editing-canceled`	This signal gets emitted when the user cancels the process of editing a cell.
`editing-started`	This signal gets emitted when a cell starts to be edited.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.InitiallyUnowned`	r

Class Details¶

class Gtk.CellRenderer(**kwargs)¶

Bases:: GObject.InitiallyUnowned
Abstract:: Yes
Structure:: Gtk.CellRendererClass

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

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

activate(event, widget, path, background_area, cell_area, flags)[source]¶

Parameters:

event (Gdk.Event) – a GdkEvent
widget (Gtk.Widget) – widget that received the event
path (str) – widget-dependent string representation of the event location; e.g. for GtkTreeView, a string representation of GtkTreePath
background_area (Gdk.Rectangle) – background area as passed to gtk_cell_renderer_render()
cell_area (Gdk.Rectangle) – cell area as passed to gtk_cell_renderer_render()
flags (Gtk.CellRendererState) – render flags

Returns:

True if the event was consumed/handled

Return type:

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.

get_aligned_area(widget, flags, cell_area)[source]¶

Parameters:

widget (Gtk.Widget) – the GtkWidget this cell will be rendering to
flags (Gtk.CellRendererState) – render flags
cell_area (Gdk.Rectangle) – cell area which would be passed to gtk_cell_renderer_render()

Returns:

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

Return type:

aligned_area: Gdk.Rectangle

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

Deprecated since version 4.10.

get_alignment()[source]¶

Returns:

xalign:: location to fill in with the x alignment of the cell
yalign:: location to fill in with the y alignment of the cell

Return type:

(xalign: float, yalign: float)

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

Deprecated since version 4.10.

get_fixed_size()[source]¶

Returns:

width:: location to fill in with the fixed width of the cell
height:: location to fill in with the fixed height of the cell

Return type:

(width: int, height: int)

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

Deprecated since version 4.10.

get_is_expanded()[source]¶

Returns:: True if the cell renderer is expanded
Return type:: bool

Checks whether the given GtkCellRenderer is expanded.

Deprecated since version 4.10.

get_is_expander()[source]¶

Returns:: True if self is an expander, and False otherwise
Return type:: bool

Checks whether the given GtkCellRenderer is an expander.

Deprecated since version 4.10.

get_padding()[source]¶

Returns:

xpad:: location to fill in with the x padding of the cell
ypad:: location to fill in with the y padding of the cell

Return type:

(xpad: int, ypad: int)

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

Deprecated since version 4.10.

get_preferred_height(widget)[source]¶

Parameters:

widget (Gtk.Widget) – the GtkWidget this cell will be rendering to

Returns:

minimum_size:: location to store the minimum size
natural_size:: location to store the natural size

Return type:

(minimum_size: int, natural_size: int)

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

Deprecated since version 4.10.

get_preferred_height_for_width(widget, width)[source]¶

Parameters:

widget (Gtk.Widget) – the GtkWidget this cell will be rendering to
width (int) – the size which is available for allocation

Returns:

minimum_height:: location for storing the minimum size
natural_height:: location for storing the preferred size

Return type:

(minimum_height: int, natural_height: 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.

get_preferred_size(widget)[source]¶

Parameters:

widget (Gtk.Widget) – the GtkWidget this cell will be rendering to

Returns:

minimum_size:: location for storing the minimum size
natural_size:: location for storing the natural size

Return type:

(minimum_size: Gtk.Requisition, natural_size: Gtk.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.

get_preferred_width(widget)[source]¶

Parameters:

widget (Gtk.Widget) – the GtkWidget this cell will be rendering to

Returns:

minimum_size:: location to store the minimum size
natural_size:: location to store the natural size

Return type:

(minimum_size: int, natural_size: int)

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

Deprecated since version 4.10.

get_preferred_width_for_height(widget, height)[source]¶

Parameters:

widget (Gtk.Widget) – the GtkWidget this cell will be rendering to
height (int) – the size which is available for allocation

Returns:

minimum_width:: location for storing the minimum size
natural_width:: location for storing the preferred size

Return type:

(minimum_width: int, natural_width: 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.

get_request_mode()[source]¶

Returns:: The GtkSizeRequestMode preferred by this renderer.
Return type:: Gtk.SizeRequestMode

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

Deprecated since version 4.10.

get_sensitive()[source]¶

Returns:: True if the cell renderer is sensitive
Return type:: bool

Returns the cell renderer’s sensitivity.

Deprecated since version 4.10.

get_state(widget, cell_state)[source]¶

Parameters:

widget (Gtk.Widget or None) – a GtkWidget
cell_state (Gtk.CellRendererState) – cell renderer state

Returns:

the widget state flags applying to self

Return type:

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

get_visible()[source]¶

Returns:: True if the cell renderer is visible
Return type:: bool

Returns the cell renderer’s visibility.

Deprecated since version 4.10.

is_activatable()[source]¶

Returns:: True if the cell renderer can do anything when activated
Return type:: bool

Checks whether the cell renderer can do something when activated.

Deprecated since version 4.10.

set_alignment(xalign, yalign)[source]¶

Parameters:

xalign (float) – the x alignment of the cell renderer
yalign (float) – the y alignment of the cell renderer

Sets the renderer’s alignment within its available space.

Deprecated since version 4.10.

set_fixed_size(width, height)[source]¶

Parameters:

width (int) – the width of the cell renderer, or -1
height (int) – the height of the cell renderer, or -1

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

Deprecated since version 4.10.

set_is_expanded(is_expanded)[source]¶

Parameters:: is_expanded (bool) – whether self should be expanded

Sets whether the given GtkCellRenderer is expanded.

Deprecated since version 4.10.

set_is_expander(is_expander)[source]¶

Parameters:: is_expander (bool) – whether self is an expander

Sets whether the given GtkCellRenderer is an expander.

Deprecated since version 4.10.

set_padding(xpad, ypad)[source]¶

Parameters:

xpad (int) – the x padding of the cell renderer
ypad (int) – the y padding of the cell renderer

Sets the renderer’s padding.

Deprecated since version 4.10.

set_sensitive(sensitive)[source]¶

Parameters:: sensitive (bool) – the sensitivity of the cell

Sets the cell renderer’s sensitivity.

Deprecated since version 4.10.

set_visible(visible)[source]¶

Parameters:: visible (bool) – the visibility of the cell

Sets the cell renderer’s visibility.

Deprecated since version 4.10.

snapshot(snapshot, widget, background_area, cell_area, flags)[source]¶

Parameters:

snapshot (Gtk.Snapshot) – a GtkSnapshot to draw to
widget (Gtk.Widget) – the widget owning window
background_area (Gdk.Rectangle) – entire cell area (including tree expanders and maybe padding on the sides)
cell_area (Gdk.Rectangle) – area normally rendered by a cell renderer
flags (Gtk.CellRendererState) – flags that affect rendering

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.

start_editing(event, widget, path, background_area, cell_area, flags)[source]¶

Parameters:

event (Gdk.Event or None) – a GdkEvent
widget (Gtk.Widget) – widget that received the event
path (str) – widget-dependent string representation of the event location; e.g. for GtkTreeView, a string representation of GtkTreePath
background_area (Gdk.Rectangle) – background area as passed to gtk_cell_renderer_render()
cell_area (Gdk.Rectangle) – cell area as passed to gtk_cell_renderer_render()
flags (Gtk.CellRendererState) – render flags

Returns:

A new GtkCellEditable for editing this self, or None if editing is not possible

Return type:

Gtk.CellEditable or None

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

Deprecated since version 4.10.

stop_editing(canceled)[source]¶

Parameters:: canceled (bool) – True if the editing has been canceled

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.

do_activate(event, widget, path, background_area, cell_area, flags) virtual¶

Parameters:

event (Gdk.Event) – a GdkEvent
widget (Gtk.Widget) – widget that received the event
path (str) – widget-dependent string representation of the event location; e.g. for GtkTreeView, a string representation of GtkTreePath
background_area (Gdk.Rectangle) – background area as passed to gtk_cell_renderer_render()
cell_area (Gdk.Rectangle) – cell area as passed to gtk_cell_renderer_render()
flags (Gtk.CellRendererState) – render flags

Returns:

True if the event was consumed/handled

Return type:

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.

do_editing_canceled() virtual¶: Signal gets emitted when the user cancels the process of editing a cell.

do_editing_started(editable, path) virtual¶

Parameters:

editable (Gtk.CellEditable) –
path (str) –

Signal gets emitted when a cell starts to be edited.

do_get_aligned_area(widget, flags, cell_area) virtual¶

Parameters:

widget (Gtk.Widget) – the GtkWidget this cell will be rendering to
flags (Gtk.CellRendererState) – render flags
cell_area (Gdk.Rectangle) – cell area which would be passed to gtk_cell_renderer_render()

Returns:

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

Return type:

aligned_area: Gdk.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.

do_get_preferred_height(widget) virtual¶

Parameters:

widget (Gtk.Widget) – the GtkWidget this cell will be rendering to

Returns:

minimum_size:: location to store the minimum size
natural_size:: location to store the natural size

Return type:

(minimum_size: int, natural_size: int)

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

Deprecated since version 4.10.

do_get_preferred_height_for_width(widget, width) virtual¶

Parameters:

widget (Gtk.Widget) – the GtkWidget this cell will be rendering to
width (int) – the size which is available for allocation

Returns:

minimum_height:: location for storing the minimum size
natural_height:: location for storing the preferred size

Return type:

(minimum_height: int, natural_height: 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.

do_get_preferred_width(widget) virtual¶

Parameters:

widget (Gtk.Widget) – the GtkWidget this cell will be rendering to

Returns:

minimum_size:: location to store the minimum size
natural_size:: location to store the natural size

Return type:

(minimum_size: int, natural_size: int)

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

Deprecated since version 4.10.

do_get_preferred_width_for_height(widget, height) virtual¶

Parameters:

widget (Gtk.Widget) – the GtkWidget this cell will be rendering to
height (int) – the size which is available for allocation

Returns:

minimum_width:: location for storing the minimum size
natural_width:: location for storing the preferred size

Return type:

(minimum_width: int, natural_width: 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.

do_get_request_mode() virtual¶

Returns:: The GtkSizeRequestMode preferred by this renderer.
Return type:: Gtk.SizeRequestMode

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

Deprecated since version 4.10.

do_snapshot(snapshot, widget, background_area, cell_area, flags) virtual¶

Parameters:

snapshot (Gtk.Snapshot) – a GtkSnapshot to draw to
widget (Gtk.Widget) – the widget owning window
background_area (Gdk.Rectangle) – entire cell area (including tree expanders and maybe padding on the sides)
cell_area (Gdk.Rectangle) – area normally rendered by a cell renderer
flags (Gtk.CellRendererState) – flags that affect rendering

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.

do_start_editing(event, widget, path, background_area, cell_area, flags) virtual¶

Parameters:

event (Gdk.Event or None) – a GdkEvent
widget (Gtk.Widget) – widget that received the event
path (str) – widget-dependent string representation of the event location; e.g. for GtkTreeView, a string representation of GtkTreePath
background_area (Gdk.Rectangle) – background area as passed to gtk_cell_renderer_render()
cell_area (Gdk.Rectangle) – cell area as passed to gtk_cell_renderer_render()
flags (Gtk.CellRendererState) – render flags

Returns:

A new GtkCellEditable for editing this cell, or None if editing is not possible

Return type:

Gtk.CellEditable or 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.

Signal Details¶

Gtk.CellRenderer.signals.editing_canceled(cell_renderer)¶

Signal Name:: editing-canceled
Flags:: RUN_FIRST
Parameters:: cell_renderer (Gtk.CellRenderer) – The object which received the signal

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.

Gtk.CellRenderer.signals.editing_started(cell_renderer, editable, path)¶

Signal Name:

editing-started

Flags:

RUN_FIRST

Parameters:

cell_renderer (Gtk.CellRenderer) – The object which received the signal
editable (Gtk.CellEditable) – the GtkCellEditable
path (str) – the path identifying the edited cell

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 Gtk.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);
    }
}

Property Details¶

Gtk.CellRenderer.props.cell_background¶

Name:: cell-background
Type:: str
Default Value:: None
Flags:: WRITABLE

Gtk.CellRenderer.props.cell_background_rgba¶

Name:: cell-background-rgba
Type:: Gdk.RGBA
Default Value:: None
Flags:: READABLE, WRITABLE

Cell background as a GdkRGBA

Gtk.CellRenderer.props.cell_background_set¶

Name:: cell-background-set
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Gtk.CellRenderer.props.editing¶

Name:: editing
Type:: bool
Default Value:: False
Flags:: READABLE

Gtk.CellRenderer.props.height¶

Name:: height
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Gtk.CellRenderer.props.is_expanded¶

Name:: is-expanded
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Gtk.CellRenderer.props.is_expander¶

Name:: is-expander
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Gtk.CellRenderer.props.mode¶

Name:: mode
Type:: Gtk.CellRendererMode
Default Value:: Gtk.CellRendererMode.INERT
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Gtk.CellRenderer.props.sensitive¶

Name:: sensitive
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Gtk.CellRenderer.props.visible¶

Name:: visible
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Gtk.CellRenderer.props.width¶

Name:: width
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Gtk.CellRenderer.props.xalign¶

Name:: xalign
Type:: float
Default Value:: 0.5
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Gtk.CellRenderer.props.xpad¶

Name:: xpad
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Gtk.CellRenderer.props.yalign¶

Name:: yalign
Type:: float
Default Value:: 0.5
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Gtk.CellRenderer.props.ypad¶

Name:: ypad
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY