Gtk.CellRenderer

g GObject.InitiallyUnowned GObject.InitiallyUnowned Gtk.CellRenderer Gtk.CellRenderer GObject.InitiallyUnowned->Gtk.CellRenderer GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned

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

Methods

Inherited:GObject.Object (37)
Structs:Gtk.CellRendererClass (1), GObject.ObjectClass (5)
class set_accessible_type (type)
  activate (event, widget, path, background_area, cell_area, flags)
  get_aligned_area (widget, flags, cell_area)
  get_alignment ()
  get_fixed_size ()
  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_size (widget, cell_area)
  get_state (widget, cell_state)
  get_visible ()
  is_activatable ()
  render (cr, widget, background_area, cell_area, flags)
  set_alignment (xalign, yalign)
  set_fixed_size (width, height)
  set_padding (xpad, ypad)
  set_sensitive (sensitive)
  set_visible (visible)
  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_get_size (widget, cell_area)
  do_render (cr, widget, background_area, cell_area, flags)
  do_start_editing (event, widget, path, background_area, cell_area, flags)

Properties

Name Type Flags Short Description
cell-background str w Cell background color as a string
cell-background-gdk Gdk.Color d/r/w Cell background color as a Gdk.Color deprecated
cell-background-rgba Gdk.RGBA r/w Cell background color as a Gdk.RGBA
cell-background-set bool r/w/en Whether the cell background color is set
editing bool r Whether the cell renderer is currently in editing mode
height int r/w/en The fixed height
is-expanded bool r/w/en Row is an expander row, and is expanded
is-expander bool r/w/en Row has children
mode Gtk.CellRendererMode r/w/en Editable mode of the CellRenderer
sensitive bool r/w/en xlib.Display the cell sensitive
visible bool r/w/en xlib.Display the cell
width int r/w/en The fixed width
xalign float r/w/en The x-align
xpad int r/w/en The xpad
yalign float r/w/en The y-align
ypad int r/w/en The ypad

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

The Gtk.CellRenderer is a base class of a set of objects used for rendering a cell to a cairo.Context. These objects are used primarily by the Gtk.TreeView widget, though they aren’t tied to them in any specific way. It is worth noting that Gtk.CellRenderer is not a Gtk.Widget and cannot be treated as such.

The primary use of a Gtk.CellRenderer is for drawing a certain graphical elements on a cairo.Context. 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.Objects property system. Then, the cell is measured using Gtk.CellRenderer.get_size(). Finally, the cell is rendered in the correct location using Gtk.CellRenderer.render().

There are a number of rules that must be followed when writing a new Gtk.CellRenderer. First and foremost, it’s important that a certain set of properties will always yield a cell renderer of the same size, barring a Gtk.Style change. The Gtk.CellRenderer 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 Gtk.CellRendererToggle, which toggles when it gets activated by a mouse click, or it can be “editable” like Gtk.CellRendererText, which allows the user to edit the text using a widget implementing the Gtk.CellEditable interface, e.g. Gtk.Entry. To make a cell renderer activatable or editable, you have to implement the Gtk.CellRendererClass.activate or Gtk.CellRendererClass.start_editing virtual functions, respectively.

Many properties of Gtk.CellRenderer 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.

classmethod set_accessible_type(type)
Parameters:type (GObject.GType) – The object type that implements the accessible for widget_class. The type must be a subtype of Gtk.RendererCellAccessible

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

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

activate(event, widget, path, background_area, cell_area, flags)[source]
Parameters:
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, Gtk.CellRendererToggle toggles when it gets a mouse click.

get_aligned_area(widget, flags, cell_area)[source]
Parameters:
Returns:

the return location for the space inside cell_area that would acually 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.

New in version 3.0.

get_alignment()[source]
Returns:
xalign:location to fill in with the x alignment of the cell, or None
yalign:location to fill in with the y alignment of the cell, or None
Return type:(xalign: float, yalign: float)

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

New in version 2.18.

get_fixed_size()[source]
Returns:
width:location to fill in with the fixed width of the cell, or None
height:location to fill in with the fixed height of the cell, or None
Return type:(width: int, height: int)

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

get_padding()[source]
Returns:
xpad:location to fill in with the x padding of the cell, or None
ypad:location to fill in with the y padding of the cell, or None
Return type:(xpad: int, ypad: int)

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

New in version 2.18.

get_preferred_height(widget)[source]
Parameters:widget (Gtk.Widget) – the Gtk.Widget this cell will be rendering to
Returns:
minimum_size:location to store the minimum size, or None
natural_size:location to store the natural size, or None
Return type:(minimum_size: int, natural_size: int)

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

New in version 3.0.

get_preferred_height_for_width(widget, width)[source]
Parameters:
  • widget (Gtk.Widget) – the Gtk.Widget this cell will be rendering to
  • width (int) – the size which is available for allocation
Returns:

minimum_height:location for storing the minimum size, or None
natural_height:location for storing the preferred size, or None

Return type:

(minimum_height: int, natural_height: int)

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

New in version 3.0.

get_preferred_size(widget)[source]
Parameters:widget (Gtk.Widget) – the Gtk.Widget this cell will be rendering to
Returns:
minimum_size:location for storing the minimum size, or None
natural_size:location for storing the natural size, or None
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.

New in version 3.0.

get_preferred_width(widget)[source]
Parameters:widget (Gtk.Widget) – the Gtk.Widget this cell will be rendering to
Returns:
minimum_size:location to store the minimum size, or None
natural_size:location to store the natural size, or None
Return type:(minimum_size: int, natural_size: int)

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

New in version 3.0.

get_preferred_width_for_height(widget, height)[source]
Parameters:
  • widget (Gtk.Widget) – the Gtk.Widget this cell will be rendering to
  • height (int) – the size which is available for allocation
Returns:

minimum_width:location for storing the minimum size, or None
natural_width:location for storing the preferred size, or None

Return type:

(minimum_width: int, natural_width: int)

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

New in version 3.0.

get_request_mode()[source]
Returns:The Gtk.SizeRequestMode 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.

New in version 3.0.

get_sensitive()[source]
Returns:True if the cell renderer is sensitive
Return type:bool

Returns the cell renderer’s sensitivity.

New in version 2.18.

get_size(widget, cell_area)[source]
Parameters:
Returns:

x_offset:location to return x offset of cell relative to cell_area, or None
y_offset:location to return y offset of cell relative to cell_area, or None
width:location to return width needed to render a cell, or None
height:location to return height needed to render a cell, or None

Return type:

(x_offset: int, y_offset: int, width: int, height: int)

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.CellRenderer.render(). If cell_area is not None, 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.

Deprecated since version 3.0: Use Gtk.CellRenderer.get_preferred_size() instead.

get_state(widget, cell_state)[source]
Parameters:
Returns:

the widget state flags applying to self
Return type:

Gtk.StateFlags

Translates the cell renderer state to Gtk.StateFlags, based on the cell renderer and widget sensitivity, and the given Gtk.CellRendererState.

New in version 3.0.

get_visible()[source]
Returns:True if the cell renderer is visible
Return type:bool

Returns the cell renderer’s visibility.

New in version 2.18.

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.

New in version 3.0.

render(cr, widget, background_area, cell_area, flags)[source]
Parameters:

Invokes the virtual render function of the Gtk.CellRenderer. 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 Gtk.CellRenderer 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.

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.

New in version 2.18.

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.

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.

New in version 2.18.

set_sensitive(sensitive)[source]
Parameters:sensitive (bool) – the sensitivity of the cell

Sets the cell renderer’s sensitivity.

New in version 2.18.

set_visible(visible)[source]
Parameters:visible (bool) – the visibility of the cell

Sets the cell renderer’s visibility.

New in version 2.18.

start_editing(event, widget, path, background_area, cell_area, flags)[source]
Parameters:
Returns:

A new Gtk.CellEditable 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 Gtk.CellEditable widget created by the Gtk.CellRendererClass.start_editing virtual function.

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 Gtk.CellRenderer ::editing-canceled signal.

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

New in version 2.6.

do_activate(event, widget, path, background_area, cell_area, flags) virtual
Parameters:
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, Gtk.CellRendererToggle toggles when it gets a mouse click.

do_editing_canceled() virtual
do_editing_started(editable, path) virtual
Parameters:
do_get_aligned_area(widget, flags, cell_area) virtual
Parameters:
Returns:

the return location for the space inside cell_area that would acually 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.

New in version 3.0.

do_get_preferred_height(widget) virtual
Parameters:widget (Gtk.Widget) – the Gtk.Widget this cell will be rendering to
Returns:
minimum_size:location to store the minimum size, or None
natural_size:location to store the natural size, or None
Return type:(minimum_size: int, natural_size: int)

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

New in version 3.0.

do_get_preferred_height_for_width(widget, width) virtual
Parameters:
  • widget (Gtk.Widget) – the Gtk.Widget this cell will be rendering to
  • width (int) – the size which is available for allocation
Returns:

minimum_height:location for storing the minimum size, or None
natural_height:location for storing the preferred size, or None

Return type:

(minimum_height: int, natural_height: int)

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

New in version 3.0.

do_get_preferred_width(widget) virtual
Parameters:widget (Gtk.Widget) – the Gtk.Widget this cell will be rendering to
Returns:
minimum_size:location to store the minimum size, or None
natural_size:location to store the natural size, or None
Return type:(minimum_size: int, natural_size: int)

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

New in version 3.0.

do_get_preferred_width_for_height(widget, height) virtual
Parameters:
  • widget (Gtk.Widget) – the Gtk.Widget this cell will be rendering to
  • height (int) – the size which is available for allocation
Returns:

minimum_width:location for storing the minimum size, or None
natural_width:location for storing the preferred size, or None

Return type:

(minimum_width: int, natural_width: int)

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

New in version 3.0.

do_get_request_mode() virtual
Returns:The Gtk.SizeRequestMode 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.

New in version 3.0.

do_get_size(widget, cell_area) virtual
Parameters:
Returns:

x_offset:location to return x offset of cell relative to cell_area, or None
y_offset:location to return y offset of cell relative to cell_area, or None
width:location to return width needed to render a cell, or None
height:location to return height needed to render a cell, or None

Return type:

(x_offset: int, y_offset: int, width: int, height: int)

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.CellRenderer.render(). If cell_area is not None, 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.

Deprecated since version 3.0: Use Gtk.CellRenderer.get_preferred_size() instead.

do_render(cr, widget, background_area, cell_area, flags) virtual
Parameters:

Invokes the virtual render function of the Gtk.CellRenderer. 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 Gtk.CellRenderer 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.

do_start_editing(event, widget, path, background_area, cell_area, flags) virtual
Parameters:
Returns:

A new Gtk.CellEditable 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 Gtk.CellEditable widget created by the Gtk.CellRendererClass.start_editing virtual function.

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.

See also: Gtk.CellRenderer.stop_editing().

New in version 2.4.

Gtk.CellRenderer.signals.editing_started(cell_renderer, editable, path)
Signal Name:

editing-started
Flags:

RUN_FIRST
Parameters:

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 Gtk.EntryCompletion or setting up additional columns in a Gtk.ComboBox.

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 gchar     *path,
                      gpointer         data)
{
  if (GTK_IS_ENTRY (editable))
    {
      GtkEntry *entry = GTK_ENTRY (editable);

      // ... create a GtkEntryCompletion

      gtk_entry_set_completion (entry, completion);
    }
}

New in version 2.6.

Property Details

Gtk.CellRenderer.props.cell_background
Name:cell-background
Type:str
Default Value:None
Flags:WRITABLE

Cell background color as a string

Gtk.CellRenderer.props.cell_background_gdk
Name:cell-background-gdk
Type:Gdk.Color
Default Value:None
Flags:DEPRECATED, READABLE, WRITABLE

Cell background as a Gdk.Color

Deprecated since version 3.4: Use Gtk.CellRenderer :cell-background-rgba instead.

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

Cell background as a Gdk.RGBA

New in version 3.0.

Gtk.CellRenderer.props.cell_background_set
Name:cell-background-set
Type:bool
Default Value:False
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the cell background color is set

Gtk.CellRenderer.props.editing
Name:editing
Type:bool
Default Value:False
Flags:READABLE

Whether the cell renderer is currently in editing mode

Gtk.CellRenderer.props.height
Name:height
Type:int
Default Value:-1
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

The fixed height

Gtk.CellRenderer.props.is_expanded
Name:is-expanded
Type:bool
Default Value:False
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

Row is an expander row, and is expanded

Gtk.CellRenderer.props.is_expander
Name:is-expander
Type:bool
Default Value:False
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

Row has children

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

Editable mode of the CellRenderer

Gtk.CellRenderer.props.sensitive
Name:sensitive
Type:bool
Default Value:True
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

xlib.Display the cell sensitive

Gtk.CellRenderer.props.visible
Name:visible
Type:bool
Default Value:True
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

xlib.Display the cell

Gtk.CellRenderer.props.width
Name:width
Type:int
Default Value:-1
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

The fixed width

Gtk.CellRenderer.props.xalign
Name:xalign
Type:float
Default Value:0.5
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

The x-align

Gtk.CellRenderer.props.xpad
Name:xpad
Type:int
Default Value:0
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

The xpad

Gtk.CellRenderer.props.yalign
Name:yalign
Type:float
Default Value:0.5
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

The y-align

Gtk.CellRenderer.props.ypad
Name:ypad
Type:int
Default Value:0
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

The ypad