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