Gtk.CellRenderer - Classes - Gtk 3.0 (original) (raw)

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 aGtk.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 newGtk.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 theGtk.CellEditable interface, e.g. Gtk.Entry. To make a cell renderer activatable or editable, you have to implement the Gtk.CellRendererClass.activate orGtk.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.CellRendererToggletoggles when it gets a mouse click.

get_aligned_area(widget, flags, cell_area)[source]

Parameters:

Returns:

the return location for the space inside cell_areathat 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:

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 towidget 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:

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 towidget 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 toGtk.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 withincell_area; the xalign, yalign, xpad, and ypad fields of the Gtk.CellRenderershould 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 entirewindow.

set_alignment(xalign, yalign)[source]

Parameters:

Sets the renderer’s alignment within its available space.

New in version 2.18.

set_fixed_size(width, height)[source]

Parameters:

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

set_padding(xpad, ypad)[source]

Parameters:

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 thisself, or None if editing is not possible

Return type:

Gtk.CellEditable or None

Starts editing the contents of this self, through a new Gtk.CellEditablewidget 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 theGtk.CellRenderer ::editing-canceled signal.

This function should be called by cell renderer implementations in response to the Gtk.CellEditable ::editing-done signal ofGtk.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.CellRendererToggletoggles when it gets a mouse click.

do_editing_canceled() virtual

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

do_editing_started(editable, path) virtual

Parameters:

Signal gets emitted when a cell starts to be edited.

do_get_aligned_area(widget, flags, cell_area) virtual

Parameters:

Returns:

the return location for the space inside cell_areathat 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:

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 towidget 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:

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 towidget 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 toGtk.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 withincell_area; the xalign, yalign, xpad, and ypad fields of the Gtk.CellRenderershould 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 entirewindow.

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

Parameters:

Returns:

A new Gtk.CellEditable for editing thiscell, or None if editing is not possible

Return type:

Gtk.CellEditable or None

Starts editing the contents of this cell, through a new Gtk.CellEditablewidget 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 editablebefore 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