Gtk.CellArea¶

Subclasses:: Gtk.CellAreaBox

Methods¶

Inherited:: GObject.Object (37), Gtk.Buildable (1), Gtk.CellLayout (9)
Structs:: Gtk.CellAreaClass (3), GObject.ObjectClass (5)

class	`find_cell_property` (property_name)
class	`install_cell_property` (property_id, pspec)
class	`list_cell_properties` ()
	`activate` (context, widget, cell_area, flags, edit_only)
	`activate_cell` (widget, renderer, event, cell_area, flags)
	`add` (renderer)
	`add_focus_sibling` (renderer, sibling)
	`apply_attributes` (tree_model, iter, is_expander, is_expanded)
	`attribute_connect` (renderer, attribute, column)
	`attribute_disconnect` (renderer, attribute)
	`attribute_get_column` (renderer, attribute)
	`cell_get_property` (renderer, property_name, value)
	`cell_set_property` (renderer, property_name, value)
	`copy_context` (context)
	`create_context` ()
	`event` (context, widget, event, cell_area, flags)
	`focus` (direction)
	`foreach` (callback, *callback_data)
	`foreach_alloc` (context, widget, cell_area, background_area, callback, *callback_data)
	`get_cell_allocation` (context, widget, renderer, cell_area)
	`get_cell_at_position` (context, widget, cell_area, x, y)
	`get_current_path_string` ()
	`get_edit_widget` ()
	`get_edited_cell` ()
	`get_focus_cell` ()
	`get_focus_from_sibling` (renderer)
	`get_focus_siblings` (renderer)
	`get_preferred_height` (context, widget)
	`get_preferred_height_for_width` (context, widget, width)
	`get_preferred_width` (context, widget)
	`get_preferred_width_for_height` (context, widget, height)
	`get_request_mode` ()
	`has_renderer` (renderer)
	`inner_cell_area` (widget, cell_area)
	`is_activatable` ()
	`is_focus_sibling` (renderer, sibling)
	`remove` (renderer)
	`remove_focus_sibling` (renderer, sibling)
	`request_renderer` (renderer, orientation, widget, for_size)
	`set_focus_cell` (renderer)
	`snapshot` (context, widget, snapshot, background_area, cell_area, flags, paint_focus)
	`stop_editing` (canceled)

Virtual Methods¶

Inherited:: GObject.Object (7), Gtk.Buildable (9), Gtk.CellLayout (9)

	`do_activate` (context, widget, cell_area, flags, edit_only)
	`do_add` (renderer)
	`do_apply_attributes` (tree_model, iter, is_expander, is_expanded)
	`do_copy_context` (context)
	`do_create_context` ()
	`do_event` (context, widget, event, cell_area, flags)
	`do_focus` (direction)
	`do_foreach` (callback, callback_data)
	`do_foreach_alloc` (context, widget, cell_area, background_area, callback, callback_data)
	`do_get_cell_property` (renderer, property_id, value, pspec)
	`do_get_preferred_height` (context, widget)
	`do_get_preferred_height_for_width` (context, widget, width)
	`do_get_preferred_width` (context, widget)
	`do_get_preferred_width_for_height` (context, widget, height)
	`do_get_request_mode` ()
	`do_is_activatable` ()
	`do_remove` (renderer)
	`do_set_cell_property` (renderer, property_id, value, pspec)
	`do_snapshot` (context, widget, snapshot, background_area, cell_area, flags, paint_focus)

Properties¶

Name	Type	Flags
`edit-widget`	`Gtk.CellEditable`	r
`edited-cell`	`Gtk.CellRenderer`	r
`focus-cell`	`Gtk.CellRenderer`	r/w

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`add-editable`	Indicates that editing has started on renderer and that editable should be added to the owning cell-layouting widget at cell_area.
`apply-attributes`	This signal is emitted whenever applying attributes to area from model
`focus-changed`	Indicates that focus changed on this area.
`remove-editable`	Indicates that editing finished on renderer and that editable should be removed from the owning cell-layouting widget.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.InitiallyUnowned`	r

Class Details¶

class Gtk.CellArea(**kwargs)¶

Bases:: GObject.InitiallyUnowned, Gtk.Buildable, Gtk.CellLayout
Abstract:: Yes
Structure:: Gtk.CellAreaClass

An abstract class for laying out ``GtkCellRenderer``s

The GtkCellArea is an abstract class for [iface`Gtk`.CellLayout] widgets (also referred to as “layouting widgets”) to interface with an arbitrary number of [class`Gtk`.CellRenderer]s and interact with the user for a given [iface`Gtk`.TreeModel] row.

The cell area handles events, focus navigation, drawing and size requests and allocations for a given row of data.

Usually users dont have to interact with the GtkCellArea directly unless they are implementing a cell-layouting widget themselves.

Requesting area sizes

As outlined in GtkWidget’s geometry management section, GTK uses a height-for-width geometry management system to compute the sizes of widgets and user interfaces. GtkCellArea uses the same semantics to calculate the size of an area for an arbitrary number of GtkTreeModel rows.

When requesting the size of a cell area one needs to calculate the size for a handful of rows, and this will be done differently by different layouting widgets. For instance a [class`Gtk`.TreeViewColumn] always lines up the areas from top to bottom while a [class`Gtk`.IconView] on the other hand might enforce that all areas received the same width and wrap the areas around, requesting height for more cell areas when allocated less width.

It’s also important for areas to maintain some cell alignments with areas rendered for adjacent rows (cells can appear “columnized” inside an area even when the size of cells are different in each row). For this reason the GtkCellArea uses a [class`Gtk`.CellAreaContext] object to store the alignments and sizes along the way (as well as the overall largest minimum and natural size for all the rows which have been calculated with the said context).

The [class`Gtk`.CellAreaContext] is an opaque object specific to the GtkCellArea which created it (see [method`Gtk`.CellArea.create_context]).

The owning cell-layouting widget can create as many contexts as it wishes to calculate sizes of rows which should receive the same size in at least one orientation (horizontally or vertically), However, it’s important that the same [class`Gtk`.CellAreaContext] which was used to request the sizes for a given GtkTreeModel row be used when rendering or processing events for that row.

In order to request the width of all the rows at the root level of a GtkTreeModel one would do the following:

```c Gtk.TreeIter iter; int minimum_width; int natural_width;

valid = Gtk.TreeModel.get_iter_first (model, &iter); while (valid) { Gtk.CellArea.apply_attributes (area, model, &iter, False, False); Gtk.CellArea.get_preferred_width (area, context, widget, None, None);

valid = Gtk.TreeModel.iter_next (model, &iter); }

Gtk.CellAreaContext.get_preferred_width (context, &minimum_width, &natural_width); ```

Note that in this example it’s not important to observe the returned minimum and natural width of the area for each row unless the cell-layouting object is actually interested in the widths of individual rows. The overall width is however stored in the accompanying GtkCellAreaContext object and can be consulted at any time.

This can be useful since GtkCellLayout widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The GtkCellLayout widget in that case would calculate the required width of the rows in an idle or timeout source (see [func`GLib`.timeout_add]) and when the widget is requested its actual width in [vfunc`Gtk`.Widget.measure] it can simply consult the width accumulated so far in the GtkCellAreaContext object.

A simple example where rows are rendered from top to bottom and take up the full width of the layouting widget would look like:

```c static void foo_get_preferred_width (Gtk.Widget *widget, int *minimum_size, int *natural_size) { Foo *self = FOO (widget); FooPrivate *priv = foo_get_instance_private (self);

foo_ensure_at_least_one_handfull_of_rows_have_been_requested (self);

Gtk.CellAreaContext.get_preferred_width (priv->context, minimum_size, natural_size); } ```

In the above example the Foo widget has to make sure that some row sizes have been calculated (the amount of rows that Foo judged was appropriate to request space for in a single timeout iteration) before simply returning the amount of space required by the area via the GtkCellAreaContext.

Requesting the height for width (or width for height) of an area is a similar task except in this case the GtkCellAreaContext does not store the data (actually, it does not know how much space the layouting widget plans to allocate it for every row. It’s up to the layouting widget to render each row of data with the appropriate height and width which was requested by the GtkCellArea).

In order to request the height for width of all the rows at the root level of a GtkTreeModel one would do the following:

```c Gtk.TreeIter iter; int minimum_height; int natural_height; int full_minimum_height = 0; int full_natural_height = 0;

valid = Gtk.TreeModel.get_iter_first (model, &iter); while (valid) { Gtk.CellArea.apply_attributes (area, model, &iter, False, False); Gtk.CellArea.get_preferred_height_for_width (area, context, widget, width, &minimum_height, &natural_height);

if (width_is_for_allocation) cache_row_height (&iter, minimum_height, natural_height);

full_minimum_height += minimum_height; full_natural_height += natural_height;

valid = Gtk.TreeModel.iter_next (model, &iter); } ```

Note that in the above example we would need to cache the heights returned for each row so that we would know what sizes to render the areas for each row. However we would only want to really cache the heights if the request is intended for the layouting widgets real allocation.

In some cases the layouting widget is requested the height for an arbitrary for_width, this is a special case for layouting widgets who need to request size for tens of thousands of rows. For this case it’s only important that the layouting widget calculate one reasonably sized chunk of rows and return that height synchronously. The reasoning here is that any layouting widget is at least capable of synchronously calculating enough height to fill the screen height (or scrolled window height) in response to a single call to [vfunc`Gtk`.Widget.measure]. Returning a perfect height for width that is larger than the screen area is inconsequential since after the layouting receives an allocation from a scrolled window it simply continues to drive the scrollbar values while more and more height is required for the row heights that are calculated in the background.

Rendering Areas

Once area sizes have been acquired at least for the rows in the visible area of the layouting widget they can be rendered at [vfunc`Gtk`.Widget.snapshot] time.

A crude example of how to render all the rows at the root level runs as follows:

```c GtkAllocation allocation; Gdk.Rectangle cell_area = { 0, }; Gtk.TreeIter iter; int minimum_width; int natural_width;

Gtk.Widget.get_allocation (widget, &allocation); cell_area.width = allocation.width;

valid = Gtk.TreeModel.get_iter_first (model, &iter); while (valid) { cell_area.height = get_cached_height_for_row (&iter);

Gtk.CellArea.apply_attributes (area, model, &iter, False, False); gtk_cell_area_render (area, context, widget, cr, &cell_area, &cell_area, state_flags, False);

cell_area.y += cell_area.height;

valid = Gtk.TreeModel.iter_next (model, &iter); } ```

Note that the cached height in this example really depends on how the layouting widget works. The layouting widget might decide to give every row its minimum or natural height or, if the model content is expected to fit inside the layouting widget without scrolling, it would make sense to calculate the allocation for each row at the time the widget is allocated using [func`Gtk`.distribute_natural_allocation].

Handling Events and Driving Keyboard Focus

Passing events to the area is as simple as handling events on any normal widget and then passing them to the [method`Gtk`.CellArea.event] API as they come in. Usually GtkCellArea is only interested in button events, however some customized derived areas can be implemented who are interested in handling other events. Handling an event can trigger the [signal@Gtk.CellArea::focus-changed] signal to fire; as well as [signal@Gtk.CellArea::add-editable] in the case that an editable cell was clicked and needs to start editing. You can call [method`Gtk`.CellArea.stop_editing] at any time to cancel any cell editing that is currently in progress.

The GtkCellArea drives keyboard focus from cell to cell in a way similar to GtkWidget. For layouting widgets that support giving focus to cells it’s important to remember to pass GTK_CELL_RENDERER_FOCUSED to the area functions for the row that has focus and to tell the area to paint the focus at render time.

Layouting widgets that accept focus on cells should implement the [vfunc`Gtk`.Widget.focus] virtual method. The layouting widget is always responsible for knowing where GtkTreeModel rows are rendered inside the widget, so at [vfunc`Gtk`.Widget.focus] time the layouting widget should use the GtkCellArea methods to navigate focus inside the area and then observe the [enum`Gtk`.DirectionType] to pass the focus to adjacent rows and areas.

A basic example of how the [vfunc`Gtk`.Widget.focus] virtual method should be implemented:

``` static bool foo_focus (Gtk.Widget *widget, Gtk.DirectionType direction) { Foo *self = FOO (widget); FooPrivate *priv = foo_get_instance_private (self); int focus_row = priv->focus_row; bool have_focus = False;

if (!:obj:Gtk.Widget.has_focus (widget)) Gtk.Widget.grab_focus (widget);

valid = Gtk.TreeModel.iter_nth_child (priv->model, &iter, None, priv->focus_row); while (valid) { Gtk.CellArea.apply_attributes (priv->area, priv->model, &iter, False, False);

if (Gtk.CellArea.focus (priv->area, direction)) { priv->focus_row = focus_row; have_focus = True; break; } else { if (direction == Gtk.DirectionType.RIGHT || direction == Gtk.DirectionType.LEFT) break; else if (direction == Gtk.DirectionType.UP || direction == Gtk.DirectionType.TAB_BACKWARD) { if (focus_row == 0) break; else { focus_row–; valid = Gtk.TreeModel.iter_nth_child (priv->model, &iter, None, focus_row); } } else { if (focus_row == last_row) break; else { focus_row++; valid = Gtk.TreeModel.iter_next (priv->model, &iter); } } } } return have_focus; } ```

Note that the layouting widget is responsible for matching the GtkDirectionType values to the way it lays out its cells.

Cell Properties

The GtkCellArea introduces cell properties for GtkCellRenderer``s. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a [class`Gtk`.CellAreaBox] a cell might “expand” and receive extra space when the area is allocated more than its full natural request, or a cell might be configured to “align” with adjacent rows which were requested and rendered with the same ``GtkCellAreaContext.

Use [method`Gtk`.CellAreaClass.install_cell_property] to install cell properties for a cell area class and [method`Gtk`.CellAreaClass.find_cell_property] or [method`Gtk`.CellAreaClass.list_cell_properties] to get information about existing cell properties.

To set the value of a cell property, use [method`Gtk`.CellArea.cell_set_property], [method`Gtk`.CellArea.cell_set] or [method`Gtk`.CellArea.cell_set_valist]. To obtain the value of a cell property, use ‘method@Gtk.CellArea.cell_get_property [method@Gtk.CellArea.cell_get]’ or [method`Gtk`.CellArea.cell_get_valist].

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

classmethod find_cell_property(property_name)¶

Parameters:: property_name (str) – the name of the child property to find
Returns:: the GParamSpec of the child property
Return type:: GObject.ParamSpec

Finds a cell property of a cell area class by name.

Deprecated since version 4.10.

classmethod install_cell_property(property_id, pspec)¶

Parameters:

property_id (int) – the id for the property
pspec (GObject.ParamSpec) – the GParamSpec for the property

Installs a cell property on a cell area class.

Deprecated since version 4.10.

classmethod list_cell_properties()¶

Returns:: a newly allocated None-terminated array of GParamSpec *. The array must be freed with GLib.free().
Return type:: [GObject.ParamSpec]

Returns all cell properties of a cell area class.

Deprecated since version 4.10.

activate(context, widget, cell_area, flags, edit_only)[source]¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context in context with the current row data
widget (Gtk.Widget) – the GtkWidget that self is rendering on
cell_area (Gdk.Rectangle) – the size and location of self relative to widget’s allocation
flags (Gtk.CellRendererState) – the ``GtkCellRenderer``State flags for self for this row of data.
edit_only (bool) – if True then only cell renderers that are Gtk.CellRendererMode.EDITABLE will be activated.

Returns:

Whether self was successfully activated.

Return type:

bool

Activates self, usually by activating the currently focused cell, however some subclasses which embed widgets in the area can also activate a widget if it currently has the focus.

Deprecated since version 4.10.

activate_cell(widget, renderer, event, cell_area, flags)[source]¶

Parameters:

widget (Gtk.Widget) – the GtkWidget that self is rendering onto
renderer (Gtk.CellRenderer) – the GtkCellRenderer in self to activate
event (Gdk.Event) – the GdkEvent for which cell activation should occur
cell_area (Gdk.Rectangle) – the GdkRectangle in widget relative coordinates of renderer for the current row.
flags (Gtk.CellRendererState) – the ``GtkCellRenderer``State for renderer

Returns:

whether cell activation was successful

Return type:

bool

This is used by GtkCellArea subclasses when handling events to activate cells, the base GtkCellArea class activates cells for keyboard events for free in its own Gtk.CellArea->activate() implementation.

Deprecated since version 4.10.

add(renderer)[source]¶

Parameters:: renderer (Gtk.CellRenderer) – the GtkCellRenderer to add to self

Adds renderer to self with the default child cell properties.

Deprecated since version 4.10.

add_focus_sibling(renderer, sibling)[source]¶

Parameters:

renderer (Gtk.CellRenderer) – the GtkCellRenderer expected to have focus
sibling (Gtk.CellRenderer) – the GtkCellRenderer to add to renderer’s focus area

Adds sibling to renderer’s focusable area, focus will be drawn around renderer and all of its siblings if renderer can focus for a given row.

Events handled by focus siblings can also activate the given focusable renderer.

Deprecated since version 4.10.

apply_attributes(tree_model, iter, is_expander, is_expanded)[source]¶

Parameters:

tree_model (Gtk.TreeModel) – the GtkTreeModel to pull values from
iter (Gtk.TreeIter) – the GtkTreeIter in tree_model to apply values for
is_expander (bool) – whether iter has children
is_expanded (bool) – whether iter is expanded in the view and children are visible

Applies any connected attributes to the renderers in self by pulling the values from tree_model.

Deprecated since version 4.10.

attribute_connect(renderer, attribute, column)[source]¶

Parameters:

renderer (Gtk.CellRenderer) – the GtkCellRenderer to connect an attribute for
attribute (str) – the attribute name
column (int) – the GtkTreeModel column to fetch attribute values from

Connects an attribute to apply values from column for the GtkTreeModel in use.

Deprecated since version 4.10.

attribute_disconnect(renderer, attribute)[source]¶

Parameters:

renderer (Gtk.CellRenderer) – the GtkCellRenderer to disconnect an attribute for
attribute (str) – the attribute name

Disconnects attribute for the renderer in self so that attribute will no longer be updated with values from the model.

Deprecated since version 4.10.

attribute_get_column(renderer, attribute)[source]¶

Parameters:

renderer (Gtk.CellRenderer) – a GtkCellRenderer
attribute (str) – an attribute on the renderer

Returns:

the model column, or -1

Return type:

int

Returns the model column that an attribute has been mapped to, or -1 if the attribute is not mapped.

Deprecated since version 4.10.

cell_get_property(renderer, property_name, value)[source]¶

Parameters:

renderer (Gtk.CellRenderer) – a GtkCellRenderer inside self
property_name (str) – the name of the property to get
value (GObject.Value) – a location to return the value

Gets the value of a cell property for renderer in self.

Deprecated since version 4.10.

cell_set_property(renderer, property_name, value)[source]¶

Parameters:

renderer (Gtk.CellRenderer) – a GtkCellRenderer inside self
property_name (str) – the name of the cell property to set
value (GObject.Value) – the value to set the cell property to

Sets a cell property for renderer in self.

Deprecated since version 4.10.

copy_context(context)[source]¶

Parameters:: context (Gtk.CellAreaContext) – the ``GtkCellArea``Context to copy
Returns:: a newly created ``GtkCellArea``Context copy of context.
Return type:: Gtk.CellAreaContext

This is sometimes needed for cases where rows need to share alignments in one orientation but may be separately grouped in the opposing orientation.

For instance, GtkIconView creates all icons (rows) to have the same width and the cells theirin to have the same horizontal alignments. However each row of icons may have a separate collective height. GtkIconView uses this to request the heights of each row based on a context which was already used to request all the row widths that are to be displayed.

Deprecated since version 4.10.

create_context()[source]¶

Returns:: a newly created ``GtkCellArea``Context which can be used with self.
Return type:: Gtk.CellAreaContext

Creates a ``GtkCellArea``Context to be used with self for all purposes. ``GtkCellArea``Context stores geometry information for rows for which it was operated on, it is important to use the same context for the same row of data at all times (i.e. one should render and handle events with the same ``GtkCellArea``Context which was used to request the size of those rows of data).

Deprecated since version 4.10.

event(context, widget, event, cell_area, flags)[source]¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context for this row of data.
widget (Gtk.Widget) – the GtkWidget that self is rendering to
event (Gdk.Event) – the GdkEvent to handle
cell_area (Gdk.Rectangle) – the widget relative coordinates for self
flags (Gtk.CellRendererState) – the ``GtkCellRenderer``State for self in this row.

Returns:

True if the event was handled by self.

Return type:

int

Delegates event handling to a GtkCellArea.

Deprecated since version 4.10.

focus(direction)[source]¶

Parameters:: direction (Gtk.DirectionType) – the GtkDirectionType
Returns:: True if focus remains inside self as a result of this call.
Return type:: bool

This should be called by the self’s owning layout widget when focus is to be passed to self, or moved within self for a given direction and row data.

Implementing GtkCellArea classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells.

Deprecated since version 4.10.

foreach(callback, *callback_data)[source]¶

Parameters:

callback (Gtk.CellCallback) – the GtkCellCallback to call
callback_data (object or None) – user provided data pointer

Calls callback for every GtkCellRenderer in self.

Deprecated since version 4.10.

foreach_alloc(context, widget, cell_area, background_area, callback, *callback_data)[source]¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context for this row of data.
widget (Gtk.Widget) – the GtkWidget that self is rendering to
cell_area (Gdk.Rectangle) – the widget relative coordinates and size for self
background_area (Gdk.Rectangle) – the widget relative coordinates of the background area
callback (Gtk.CellAllocCallback) – the GtkCellAllocCallback to call
callback_data (object or None) – user provided data pointer

Calls callback for every GtkCellRenderer in self with the allocated rectangle inside cell_area.

get_cell_allocation(context, widget, renderer, cell_area)[source]¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context used to hold sizes for self.
widget (Gtk.Widget) – the GtkWidget that self is rendering on
renderer (Gtk.CellRenderer) – the GtkCellRenderer to get the allocation for
cell_area (Gdk.Rectangle) – the whole allocated area for self in widget for this row

Returns:

where to store the allocation for renderer

Return type:

allocation: Gdk.Rectangle

Derives the allocation of renderer inside self if self were to be rendered in cell_area.

Deprecated since version 4.10.

get_cell_at_position(context, widget, cell_area, x, y)[source]¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context used to hold sizes for self.
widget (Gtk.Widget) – the GtkWidget that self is rendering on
cell_area (Gdk.Rectangle) – the whole allocated area for self in widget for this row
x (int) – the x position
y (int) – the y position

Returns:

the GtkCellRenderer at x and y.

alloc_area:: where to store the inner allocated area of the returned cell renderer

Return type:

(Gtk.CellRenderer, alloc_area: Gdk.Rectangle)

Gets the GtkCellRenderer at x and y coordinates inside self and optionally returns the full cell allocation for it inside cell_area.

Deprecated since version 4.10.

get_current_path_string()[source]¶

Returns:: The current GtkTreePath string for the current attributes applied to self. This string belongs to the area and should not be freed.
Return type:: str

Gets the current GtkTreePath string for the currently applied GtkTreeIter, this is implicitly updated when Gtk.CellArea.apply_attributes() is called and can be used to interact with renderers from GtkCellArea subclasses.

get_edit_widget()[source]¶

Returns:: The currently active GtkCellEditable widget
Return type:: Gtk.CellEditable or None

Gets the GtkCellEditable widget currently used to edit the currently edited cell.

Deprecated since version 4.10.

get_edited_cell()[source]¶

Returns:: The currently edited GtkCellRenderer
Return type:: Gtk.CellRenderer or None

Gets the GtkCellRenderer in self that is currently being edited.

Deprecated since version 4.10.

get_focus_cell()[source]¶

Returns:: the currently focused cell in self.
Return type:: Gtk.CellRenderer or None

Retrieves the currently focused cell for self

Deprecated since version 4.10.

get_focus_from_sibling(renderer)[source]¶

Parameters:: renderer (Gtk.CellRenderer) – the GtkCellRenderer
Returns:: the GtkCellRenderer for which renderer is a sibling
Return type:: Gtk.CellRenderer or None

Gets the GtkCellRenderer which is expected to be focusable for which renderer is, or may be a sibling.

This is handy for GtkCellArea subclasses when handling events, after determining the renderer at the event location it can then chose to activate the focus cell for which the event cell may have been a sibling.

Deprecated since version 4.10.

get_focus_siblings(renderer)[source]¶

Parameters:: renderer (Gtk.CellRenderer) – the GtkCellRenderer expected to have focus
Returns:: A GList of ``GtkCellRenderer``s. The returned list is internal and should not be freed.
Return type:: [Gtk.CellRenderer]

Gets the focus sibling cell renderers for renderer.

Deprecated since version 4.10.

get_preferred_height(context, widget)[source]¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context to perform this request with
widget (Gtk.Widget) – the GtkWidget where self will be rendering

Returns:

minimum_height:: location to store the minimum height
natural_height:: location to store the natural height

Return type:

(minimum_height: int, natural_height: int)

Retrieves a cell area’s initial minimum and natural height.

self will store some geometrical information in context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the minimum_height and natural_height of this call but rather to consult Gtk.CellAreaContext.get_preferred_height() after a series of requests.

Deprecated since version 4.10.

get_preferred_height_for_width(context, widget, width)[source]¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context which has already been requested for widths.
widget (Gtk.Widget) – the GtkWidget where self will be rendering
width (int) – the width for which to check the height of this area

Returns:

minimum_height:: location to store the minimum height
natural_height:: location to store the natural height

Return type:

(minimum_height: int, natural_height: int)

Retrieves a cell area’s minimum and natural height if it would be given the specified width.

self stores some geometrical information in context along the way while calling Gtk.CellArea.get_preferred_width(). It’s important to perform a series of Gtk.CellArea.get_preferred_width() requests with context first and then call Gtk.CellArea.get_preferred_height_for_width() on each cell area individually to get the height for width of each fully requested row.

If at some point, the width of a single row changes, it should be requested with Gtk.CellArea.get_preferred_width() again and then the full width of the requested rows checked again with Gtk.CellAreaContext.get_preferred_width().

Deprecated since version 4.10.

get_preferred_width(context, widget)[source]¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context to perform this request with
widget (Gtk.Widget) – the GtkWidget where self will be rendering

Returns:

minimum_width:: location to store the minimum width
natural_width:: location to store the natural width

Return type:

(minimum_width: int, natural_width: int)

Retrieves a cell area’s initial minimum and natural width.

self will store some geometrical information in context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the minimum_width and natural_width of this call but rather to consult Gtk.CellAreaContext.get_preferred_width() after a series of requests.

Deprecated since version 4.10.

get_preferred_width_for_height(context, widget, height)[source]¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context which has already been requested for widths.
widget (Gtk.Widget) – the GtkWidget where self will be rendering
height (int) – the height for which to check the width of this area

Returns:

minimum_width:: location to store the minimum width
natural_width:: location to store the natural width

Return type:

(minimum_width: int, natural_width: int)

Retrieves a cell area’s minimum and natural width if it would be given the specified height.

self stores some geometrical information in context along the way while calling Gtk.CellArea.get_preferred_height(). It’s important to perform a series of Gtk.CellArea.get_preferred_height() requests with context first and then call Gtk.CellArea.get_preferred_width_for_height() on each cell area individually to get the height for width of each fully requested row.

If at some point, the height of a single row changes, it should be requested with Gtk.CellArea.get_preferred_height() again and then the full height of the requested rows checked again with Gtk.CellAreaContext.get_preferred_height().

Deprecated since version 4.10.

get_request_mode()[source]¶

Returns:: The GtkSizeRequestMode preferred by self.
Return type:: Gtk.SizeRequestMode

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

has_renderer(renderer)[source]¶

Parameters:: renderer (Gtk.CellRenderer) – the GtkCellRenderer to check
Returns:: True if renderer is in the self.
Return type:: bool

Checks if self contains renderer.

Deprecated since version 4.10.

inner_cell_area(widget, cell_area)[source]¶

Parameters:

widget (Gtk.Widget) – the GtkWidget that self is rendering onto
cell_area (Gdk.Rectangle) – the widget relative coordinates where one of self’s cells is to be placed

Returns:

the return location for the inner cell area

Return type:

inner_area: Gdk.Rectangle

This is a convenience function for GtkCellArea implementations to get the inner area where a given GtkCellRenderer will be rendered. It removes any padding previously added by Gtk.CellArea.request_renderer().

Deprecated since version 4.10.

is_activatable()[source]¶

Returns:: whether self can do anything when activated.
Return type:: bool

Returns whether the area can do anything when activated, after applying new attributes to self.

Deprecated since version 4.10.

is_focus_sibling(renderer, sibling)[source]¶

Parameters:

renderer (Gtk.CellRenderer) – the GtkCellRenderer expected to have focus
sibling (Gtk.CellRenderer) – the GtkCellRenderer to check against renderer’s sibling list

Returns:

True if sibling is a focus sibling of renderer

Return type:

bool

Returns whether sibling is one of renderer’s focus siblings (see Gtk.CellArea.add_focus_sibling()).

Deprecated since version 4.10.

remove(renderer)[source]¶

Parameters:: renderer (Gtk.CellRenderer) – the GtkCellRenderer to remove from self

Removes renderer from self.

Deprecated since version 4.10.

remove_focus_sibling(renderer, sibling)[source]¶

Parameters:

renderer (Gtk.CellRenderer) – the GtkCellRenderer expected to have focus
sibling (Gtk.CellRenderer) – the GtkCellRenderer to remove from renderer’s focus area

Removes sibling from renderer’s focus sibling list (see Gtk.CellArea.add_focus_sibling()).

Deprecated since version 4.10.

request_renderer(renderer, orientation, widget, for_size)[source]¶

Parameters:

renderer (Gtk.CellRenderer) – the GtkCellRenderer to request size for
orientation (Gtk.Orientation) – the GtkOrientation in which to request size
widget (Gtk.Widget) – the GtkWidget that self is rendering onto
for_size (int) – the allocation contextual size to request for, or -1 if the base request for the orientation is to be returned.

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)

This is a convenience function for GtkCellArea implementations to request size for cell renderers. It’s important to use this function to request size and then use Gtk.CellArea.inner_cell_area() at render and event time since this function will add padding around the cell for focus painting.

Deprecated since version 4.10.

set_focus_cell(renderer)[source]¶

Parameters:: renderer (Gtk.CellRenderer or None) – the GtkCellRenderer to give focus to

Explicitly sets the currently focused cell to renderer.

This is generally called by implementations of GtkCellAreaClass.focus() or GtkCellAreaClass.event(), however it can also be used to implement functions such as Gtk.TreeView.set_cursor_on_cell().

Deprecated since version 4.10.

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

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context for this row of data.
widget (Gtk.Widget) – the GtkWidget that self is rendering to
snapshot (Gtk.Snapshot) – the GtkSnapshot to draw to
background_area (Gdk.Rectangle) – the widget relative coordinates for self’s background
cell_area (Gdk.Rectangle) – the widget relative coordinates for self
flags (Gtk.CellRendererState) – the ``GtkCellRenderer``State for self in this row.
paint_focus (bool) – whether self should paint focus on focused cells for focused rows or not.

Snapshots self’s cells according to self’s layout onto at the given coordinates.

Deprecated since version 4.10.

stop_editing(canceled)[source]¶

Parameters:: canceled (bool) – whether editing was canceled.

Explicitly stops the editing of the currently edited cell.

If canceled is True, the currently edited cell renderer will emit the ::editing-canceled signal, otherwise the the ::editing-done signal will be emitted on the current edit widget.

See Gtk.CellArea.get_edited_cell() and Gtk.CellArea.get_edit_widget().

Deprecated since version 4.10.

do_activate(context, widget, cell_area, flags, edit_only) virtual¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context in context with the current row data
widget (Gtk.Widget) – the GtkWidget that area is rendering on
cell_area (Gdk.Rectangle) – the size and location of area relative to widget’s allocation
flags (Gtk.CellRendererState) – the ``GtkCellRenderer``State flags for area for this row of data.
edit_only (bool) – if True then only cell renderers that are Gtk.CellRendererMode.EDITABLE will be activated.

Returns:

Whether area was successfully activated.

Return type:

bool

Activates area, usually by activating the currently focused cell, however some subclasses which embed widgets in the area can also activate a widget if it currently has the focus.

Deprecated since version 4.10.

do_add(renderer) virtual¶

Parameters:: renderer (Gtk.CellRenderer) – the GtkCellRenderer to add to area

Adds renderer to area with the default child cell properties.

Deprecated since version 4.10.

do_apply_attributes(tree_model, iter, is_expander, is_expanded) virtual¶

Parameters:

tree_model (Gtk.TreeModel) – the GtkTreeModel to pull values from
iter (Gtk.TreeIter) – the GtkTreeIter in tree_model to apply values for
is_expander (bool) – whether iter has children
is_expanded (bool) – whether iter is expanded in the view and children are visible

Applies any connected attributes to the renderers in area by pulling the values from tree_model.

Deprecated since version 4.10.

do_copy_context(context) virtual¶

Parameters:: context (Gtk.CellAreaContext) – the ``GtkCellArea``Context to copy
Returns:: a newly created ``GtkCellArea``Context copy of context.
Return type:: Gtk.CellAreaContext

This is sometimes needed for cases where rows need to share alignments in one orientation but may be separately grouped in the opposing orientation.

For instance, GtkIconView creates all icons (rows) to have the same width and the cells theirin to have the same horizontal alignments. However each row of icons may have a separate collective height. GtkIconView uses this to request the heights of each row based on a context which was already used to request all the row widths that are to be displayed.

Deprecated since version 4.10.

do_create_context() virtual¶

Returns:: a newly created ``GtkCellArea``Context which can be used with area.
Return type:: Gtk.CellAreaContext

Creates a ``GtkCellArea``Context to be used with area for all purposes. ``GtkCellArea``Context stores geometry information for rows for which it was operated on, it is important to use the same context for the same row of data at all times (i.e. one should render and handle events with the same ``GtkCellArea``Context which was used to request the size of those rows of data).

Deprecated since version 4.10.

do_event(context, widget, event, cell_area, flags) virtual¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context for this row of data.
widget (Gtk.Widget) – the GtkWidget that area is rendering to
event (Gdk.Event) – the GdkEvent to handle
cell_area (Gdk.Rectangle) – the widget relative coordinates for area
flags (Gtk.CellRendererState) – the ``GtkCellRenderer``State for area in this row.

Returns:

True if the event was handled by area.

Return type:

int

Delegates event handling to a GtkCellArea.

Deprecated since version 4.10.

do_focus(direction) virtual¶

Parameters:: direction (Gtk.DirectionType) – the GtkDirectionType
Returns:: True if focus remains inside area as a result of this call.
Return type:: bool

This should be called by the area’s owning layout widget when focus is to be passed to area, or moved within area for a given direction and row data.

Implementing GtkCellArea classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells.

Deprecated since version 4.10.

do_foreach(callback, callback_data) virtual¶

Parameters:

callback (Gtk.CellCallback) – the GtkCellCallback to call
callback_data (object or None) – user provided data pointer

Calls callback for every GtkCellRenderer in area.

Deprecated since version 4.10.

do_foreach_alloc(context, widget, cell_area, background_area, callback, callback_data) virtual¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context for this row of data.
widget (Gtk.Widget) – the GtkWidget that area is rendering to
cell_area (Gdk.Rectangle) – the widget relative coordinates and size for area
background_area (Gdk.Rectangle) – the widget relative coordinates of the background area
callback (Gtk.CellAllocCallback) – the GtkCellAllocCallback to call
callback_data (object or None) – user provided data pointer

Calls callback for every GtkCellRenderer in area with the allocated rectangle inside cell_area.

do_get_cell_property(renderer, property_id, value, pspec) virtual¶

Parameters:

renderer (Gtk.CellRenderer) –
property_id (int) –
value (GObject.Value) –
pspec (GObject.ParamSpec) –

This should be implemented to report the values of child cell properties for a given child GtkCellRenderer.

do_get_preferred_height(context, widget) virtual¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context to perform this request with
widget (Gtk.Widget) – the GtkWidget where area will be rendering

Returns:

minimum_height:: location to store the minimum height
natural_height:: location to store the natural height

Return type:

(minimum_height: int, natural_height: int)

Retrieves a cell area’s initial minimum and natural height.

area will store some geometrical information in context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the minimum_height and natural_height of this call but rather to consult Gtk.CellAreaContext.get_preferred_height() after a series of requests.

Deprecated since version 4.10.

do_get_preferred_height_for_width(context, widget, width) virtual¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context which has already been requested for widths.
widget (Gtk.Widget) – the GtkWidget where area will be rendering
width (int) – the width for which to check the height of this area

Returns:

minimum_height:: location to store the minimum height
natural_height:: location to store the natural height

Return type:

(minimum_height: int, natural_height: int)

Retrieves a cell area’s minimum and natural height if it would be given the specified width.

area stores some geometrical information in context along the way while calling Gtk.CellArea.get_preferred_width(). It’s important to perform a series of Gtk.CellArea.get_preferred_width() requests with context first and then call Gtk.CellArea.get_preferred_height_for_width() on each cell area individually to get the height for width of each fully requested row.

If at some point, the width of a single row changes, it should be requested with Gtk.CellArea.get_preferred_width() again and then the full width of the requested rows checked again with Gtk.CellAreaContext.get_preferred_width().

Deprecated since version 4.10.

do_get_preferred_width(context, widget) virtual¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context to perform this request with
widget (Gtk.Widget) – the GtkWidget where area will be rendering

Returns:

minimum_width:: location to store the minimum width
natural_width:: location to store the natural width

Return type:

(minimum_width: int, natural_width: int)

Retrieves a cell area’s initial minimum and natural width.

area will store some geometrical information in context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the minimum_width and natural_width of this call but rather to consult Gtk.CellAreaContext.get_preferred_width() after a series of requests.

Deprecated since version 4.10.

do_get_preferred_width_for_height(context, widget, height) virtual¶

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context which has already been requested for widths.
widget (Gtk.Widget) – the GtkWidget where area will be rendering
height (int) – the height for which to check the width of this area

Returns:

minimum_width:: location to store the minimum width
natural_width:: location to store the natural width

Return type:

(minimum_width: int, natural_width: int)

Retrieves a cell area’s minimum and natural width if it would be given the specified height.

area stores some geometrical information in context along the way while calling Gtk.CellArea.get_preferred_height(). It’s important to perform a series of Gtk.CellArea.get_preferred_height() requests with context first and then call Gtk.CellArea.get_preferred_width_for_height() on each cell area individually to get the height for width of each fully requested row.

If at some point, the height of a single row changes, it should be requested with Gtk.CellArea.get_preferred_height() again and then the full height of the requested rows checked again with Gtk.CellAreaContext.get_preferred_height().

Deprecated since version 4.10.

do_get_request_mode() virtual¶

Returns:: The GtkSizeRequestMode preferred by area.
Return type:: Gtk.SizeRequestMode

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

do_is_activatable() virtual¶

Returns:: whether area can do anything when activated.
Return type:: bool

Returns whether the area can do anything when activated, after applying new attributes to area.

Deprecated since version 4.10.

do_remove(renderer) virtual¶

Parameters:: renderer (Gtk.CellRenderer) – the GtkCellRenderer to remove from area

Removes renderer from area.

Deprecated since version 4.10.

do_set_cell_property(renderer, property_id, value, pspec) virtual¶

Parameters:

renderer (Gtk.CellRenderer) –
property_id (int) –
value (GObject.Value) –
pspec (GObject.ParamSpec) –

This should be implemented to handle changes in child cell properties for a given GtkCellRenderer that were previously installed on the GtkCellAreaClass with Gtk.CellAreaClass.install_cell_property().

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

Parameters:

context (Gtk.CellAreaContext) – the ``GtkCellArea``Context for this row of data.
widget (Gtk.Widget) – the GtkWidget that area is rendering to
snapshot (Gtk.Snapshot) – the GtkSnapshot to draw to
background_area (Gdk.Rectangle) – the widget relative coordinates for area’s background
cell_area (Gdk.Rectangle) – the widget relative coordinates for area
flags (Gtk.CellRendererState) – the ``GtkCellRenderer``State for area in this row.
paint_focus (bool) – whether area should paint focus on focused cells for focused rows or not.

Snapshots area’s cells according to area’s layout onto at the given coordinates.

Deprecated since version 4.10.

Signal Details¶

Gtk.CellArea.signals.add_editable(cell_area, renderer, editable, cell_area, path)

Signal Name:

add-editable

Flags:

RUN_FIRST

Parameters:

cell_area (Gdk.Rectangle) – The object which received the signal
renderer (Gtk.CellRenderer) – the GtkCellRenderer that started the edited
editable (Gtk.CellEditable) – the GtkCellEditable widget to add
cell_area – the GtkWidget relative GdkRectangle coordinates where editable should be added
path (str) – the GtkTreePath string this edit was initiated for

Indicates that editing has started on renderer and that editable should be added to the owning cell-layouting widget at cell_area.

Gtk.CellArea.signals.apply_attributes(cell_area, model, iter, is_expander, is_expanded)¶

Signal Name:

apply-attributes

Flags:

RUN_FIRST

Parameters:

cell_area (Gtk.CellArea) – The object which received the signal
model (Gtk.TreeModel) – the GtkTreeModel to apply the attributes from
iter (Gtk.TreeIter) – the GtkTreeIter indicating which row to apply the attributes of
is_expander (bool) – whether the view shows children for this row
is_expanded (bool) – whether the view is currently showing the children of this row

This signal is emitted whenever applying attributes to area from model

Gtk.CellArea.signals.focus_changed(cell_area, renderer, path)¶

Signal Name:

focus-changed

Flags:

RUN_FIRST

Parameters:

cell_area (Gtk.CellArea) – The object which received the signal
renderer (Gtk.CellRenderer) – the GtkCellRenderer that has focus
path (str) – the current GtkTreePath string set for area

Indicates that focus changed on this area. This signal is emitted either as a result of focus handling or event handling.

It’s possible that the signal is emitted even if the currently focused renderer did not change, this is because focus may change to the same renderer in the same cell area for a different row of data.

Gtk.CellArea.signals.remove_editable(cell_area, renderer, editable)¶

Signal Name:

remove-editable

Flags:

RUN_FIRST

Parameters:

cell_area (Gtk.CellArea) – The object which received the signal
renderer (Gtk.CellRenderer) – the GtkCellRenderer that finished editeding
editable (Gtk.CellEditable) – the GtkCellEditable widget to remove

Indicates that editing finished on renderer and that editable should be removed from the owning cell-layouting widget.

Property Details¶

Gtk.CellArea.props.edit_widget¶

Name:: edit-widget
Type:: Gtk.CellEditable
Default Value:: None
Flags:: READABLE

The widget currently editing the edited cell

This property is read-only and only changes as a result of a call Gtk.CellArea.activate_cell().

Gtk.CellArea.props.edited_cell¶

Name:: edited-cell
Type:: Gtk.CellRenderer
Default Value:: None
Flags:: READABLE

The cell in the area that is currently edited

This property is read-only and only changes as a result of a call Gtk.CellArea.activate_cell().

Gtk.CellArea.props.focus_cell¶

Name:: focus-cell
Type:: Gtk.CellRenderer
Default Value:: None
Flags:: READABLE, WRITABLE

The cell in the area that currently has focus