CellArea

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

class CellArea(**properties: Any)

Superclasses: InitiallyUnowned, Object

Subclasses: CellAreaBox

Implemented Interfaces: Buildable, CellLayout

Constructors:

CellArea(**properties)

Methods

class CellArea

activate(context: CellAreaContext, widget: Widget, cell_area: Rectangle, flags: CellRendererState, edit_only: bool) → 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: Please do not use it in newly written code

Parameters:

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

activate_cell(widget: Widget, renderer: CellRenderer, event: Event, cell_area: Rectangle, flags: CellRendererState) → 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 GtkCellArea->activate() implementation.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

widget – the GtkWidget that area is rendering onto
renderer – the GtkCellRenderer in area to activate
event – the GdkEvent for which cell activation should occur
cell_area – the GdkRectangle in widget relative coordinates of renderer for the current row.
flags – the GtkCellRenderer``State for ``renderer

add(renderer: CellRenderer) → None

Adds renderer to area with the default child cell properties.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:: renderer – the GtkCellRenderer to add to area

add_focus_sibling(renderer: CellRenderer, sibling: CellRenderer) → None

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: Please do not use it in newly written code

Parameters:

renderer – the GtkCellRenderer expected to have focus
sibling – the GtkCellRenderer to add to renderer’s focus area

apply_attributes(tree_model: TreeModel, iter: TreeIter, is_expander: bool, is_expanded: bool) → None

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

tree_model – the GtkTreeModel to pull values from
iter – the GtkTreeIter in tree_model to apply values for
is_expander – whether iter has children
is_expanded – whether iter is expanded in the view and children are visible

attribute_connect(renderer: CellRenderer, attribute: str, column: int) → None

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

renderer – the GtkCellRenderer to connect an attribute for
attribute – the attribute name
column – the GtkTreeModel column to fetch attribute values from

attribute_disconnect(renderer: CellRenderer, attribute: str) → None

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

renderer – the GtkCellRenderer to disconnect an attribute for
attribute – the attribute name

attribute_get_column(renderer: CellRenderer, attribute: str) → 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: Please do not use it in newly written code

Parameters:

renderer – a GtkCellRenderer
attribute – an attribute on the renderer

cell_get_property(renderer: CellRenderer, property_name: str, value: Any) → None

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

renderer – a GtkCellRenderer inside area
property_name – the name of the property to get
value – a location to return the value

cell_set_property(renderer: CellRenderer, property_name: str, value: Any) → None

Sets a cell property for renderer in area.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

renderer – a GtkCellRenderer inside area
property_name – the name of the cell property to set
value – the value to set the cell property to

create_context() → 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: Please do not use it in newly written code

event(context: CellAreaContext, widget: Widget, event: Event, cell_area: Rectangle, flags: CellRendererState) → int

Delegates event handling to a GtkCellArea.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

context – the ``GtkCellArea``Context for this row of data.
widget – the GtkWidget that area is rendering to
event – the GdkEvent to handle
cell_area – the widget relative coordinates for area
flags – the GtkCellRenderer``State for ``area in this row.

classmethod find_cell_property(property_name: str) → ParamSpec

Parameters:: property_name

focus(direction: DirectionType) → 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: Please do not use it in newly written code

Parameters:: direction – the GtkDirectionType

foreach(callback: Callable[[...], bool], *callback_data: Any) → None

Calls callback for every GtkCellRenderer in area.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

callback – the GtkCellCallback to call
callback_data – user provided data pointer

foreach_alloc(context: CellAreaContext, widget: Widget, cell_area: Rectangle, background_area: Rectangle, callback: Callable[[...], bool], *callback_data: Any) → None

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

Parameters:

context – the ``GtkCellArea``Context for this row of data.
widget – the GtkWidget that area is rendering to
cell_area – the widget relative coordinates and size for area
background_area – the widget relative coordinates of the background area
callback – the GtkCellAllocCallback to call
callback_data – user provided data pointer

get_cell_allocation(context: CellAreaContext, widget: Widget, renderer: CellRenderer, cell_area: Rectangle) → Rectangle

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

context – the GtkCellArea``Context used to hold sizes for ``area.
widget – the GtkWidget that area is rendering on
renderer – the GtkCellRenderer to get the allocation for
cell_area – the whole allocated area for area in widget for this row

get_cell_at_position(context: CellAreaContext, widget: Widget, cell_area: Rectangle, x: int, y: int) → tuple[CellRenderer, Rectangle]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

context – the GtkCellArea``Context used to hold sizes for ``area.
widget – the GtkWidget that area is rendering on
cell_area – the whole allocated area for area in widget for this row
x – the x position
y – the y position

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

get_edit_widget() → CellEditable | None: Gets the GtkCellEditable widget currently used to edit the currently edited cell.

Deprecated since version 4.10: Please do not use it in newly written code

get_edited_cell() → CellRenderer | None: Gets the GtkCellRenderer in area that is currently being edited.

Deprecated since version 4.10: Please do not use it in newly written code

get_focus_cell() → CellRenderer | None: Retrieves the currently focused cell for area

Deprecated since version 4.10: Please do not use it in newly written code

get_focus_from_sibling(renderer: CellRenderer) → CellRenderer | 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: Please do not use it in newly written code

Parameters:: renderer – the GtkCellRenderer

get_focus_siblings(renderer: CellRenderer) → list[CellRenderer]

Gets the focus sibling cell renderers for renderer.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:: renderer – the GtkCellRenderer expected to have focus

get_preferred_height(context: CellAreaContext, widget: Widget) → tuple[int, 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 get_preferred_height() after a series of requests.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

context – the ``GtkCellArea``Context to perform this request with
widget – the GtkWidget where area will be rendering

get_preferred_height_for_width(context: CellAreaContext, widget: Widget, width: int) → tuple[int, 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 get_preferred_width(). It’s important to perform a series of get_preferred_width() requests with context first and then call 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 get_preferred_width() again and then the full width of the requested rows checked again with get_preferred_width().

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

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

get_preferred_width(context: CellAreaContext, widget: Widget) → tuple[int, 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 get_preferred_width() after a series of requests.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

context – the ``GtkCellArea``Context to perform this request with
widget – the GtkWidget where area will be rendering

get_preferred_width_for_height(context: CellAreaContext, widget: Widget, height: int) → tuple[int, 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 get_preferred_height(). It’s important to perform a series of get_preferred_height() requests with context first and then call 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 get_preferred_height() again and then the full height of the requested rows checked again with get_preferred_height().

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

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

get_request_mode() → SizeRequestMode: Gets whether the area prefers a height-for-width layout or a width-for-height layout.

has_renderer(renderer: CellRenderer) → bool

Checks if area contains renderer.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:: renderer – the GtkCellRenderer to check

inner_cell_area(widget: Widget, cell_area: Rectangle) → 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 request_renderer().

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

widget – the GtkWidget that area is rendering onto
cell_area – the widget relative coordinates where one of area’s cells is to be placed

classmethod install_cell_property(property_id: int, pspec: ParamSpec) → None

Parameters:

property_id
pspec

is_activatable() → bool: Returns whether the area can do anything when activated, after applying new attributes to area.

Deprecated since version 4.10: Please do not use it in newly written code

is_focus_sibling(renderer: CellRenderer, sibling: CellRenderer) → bool

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

renderer – the GtkCellRenderer expected to have focus
sibling – the GtkCellRenderer to check against renderer’s sibling list

classmethod list_cell_properties() → list[ParamSpec]

remove(renderer: CellRenderer) → None

Removes renderer from area.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:: renderer – the GtkCellRenderer to remove from area

remove_focus_sibling(renderer: CellRenderer, sibling: CellRenderer) → None

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

renderer – the GtkCellRenderer expected to have focus
sibling – the GtkCellRenderer to remove from renderer’s focus area

request_renderer(renderer: CellRenderer, orientation: Orientation, widget: Widget, for_size: int) → tuple[int, 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 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: Please do not use it in newly written code

Parameters:

renderer – the GtkCellRenderer to request size for
orientation – the GtkOrientation in which to request size
widget – the GtkWidget that area is rendering onto
for_size – the allocation contextual size to request for, or -1 if the base request for the orientation is to be returned.

set_focus_cell(renderer: CellRenderer | None = None) → None

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 set_cursor_on_cell().

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:: renderer – the GtkCellRenderer to give focus to

snapshot(context: CellAreaContext, widget: Widget, snapshot: Snapshot, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState, paint_focus: bool) → None

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

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

stop_editing(canceled: bool) → None

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 get_edited_cell() and get_edit_widget().

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:: canceled – whether editing was canceled.

Properties

class CellArea

props.edit_widget: CellEditable

The widget currently editing the edited cell

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

props.edited_cell: CellRenderer

The cell in the area that is currently edited

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

props.focus_cell: CellRenderer: The cell in the area that currently has focus

Signals

class CellArea.signals

add_editable(renderer: CellRenderer, editable: CellEditable, cell_area: Rectangle, path: str) → None

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

Parameters:

renderer – the GtkCellRenderer that started the edited
editable – the GtkCellEditable widget to add
cell_area – the GtkWidget relative GdkRectangle coordinates where editable should be added
path – the GtkTreePath string this edit was initiated for

apply_attributes(model: TreeModel, iter: TreeIter, is_expander: bool, is_expanded: bool) → None

This signal is emitted whenever applying attributes to area from model

Parameters:

model – the GtkTreeModel to apply the attributes from
iter – the GtkTreeIter indicating which row to apply the attributes of
is_expander – whether the view shows children for this row
is_expanded – whether the view is currently showing the children of this row

focus_changed(renderer: CellRenderer, path: str) → None

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.

Parameters:

renderer – the GtkCellRenderer that has focus
path – the current GtkTreePath string set for area

remove_editable(renderer: CellRenderer, editable: CellEditable) → None

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

Parameters:

renderer – the GtkCellRenderer that finished editeding
editable – the GtkCellEditable widget to remove

Virtual Methods

class CellArea

do_activate(context: CellAreaContext, widget: Widget, cell_area: Rectangle, flags: CellRendererState, edit_only: bool) → 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: Please do not use it in newly written code

Parameters:

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

do_add(renderer: CellRenderer) → None

Adds renderer to area with the default child cell properties.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:: renderer – the GtkCellRenderer to add to area

do_apply_attributes(tree_model: TreeModel, iter: TreeIter, is_expander: bool, is_expanded: bool) → None

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

tree_model – the GtkTreeModel to pull values from
iter – the GtkTreeIter in tree_model to apply values for
is_expander – whether iter has children
is_expanded – whether iter is expanded in the view and children are visible

do_copy_context(context: CellAreaContext) → 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: Please do not use it in newly written code

Parameters:: context – the ``GtkCellArea``Context to copy

do_create_context() → 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: Please do not use it in newly written code

do_event(context: CellAreaContext, widget: Widget, event: Event, cell_area: Rectangle, flags: CellRendererState) → int

Delegates event handling to a GtkCellArea.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

context – the ``GtkCellArea``Context for this row of data.
widget – the GtkWidget that area is rendering to
event – the GdkEvent to handle
cell_area – the widget relative coordinates for area
flags – the GtkCellRenderer``State for ``area in this row.

do_focus(direction: DirectionType) → 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: Please do not use it in newly written code

Parameters:: direction – the GtkDirectionType

do_foreach(callback: Callable[[...], bool], *callback_data: Any) → None

Calls callback for every GtkCellRenderer in area.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

callback – the GtkCellCallback to call
callback_data – user provided data pointer

do_foreach_alloc(context: CellAreaContext, widget: Widget, cell_area: Rectangle, background_area: Rectangle, callback: Callable[[...], bool], *callback_data: Any) → None

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

Parameters:

context – the ``GtkCellArea``Context for this row of data.
widget – the GtkWidget that area is rendering to
cell_area – the widget relative coordinates and size for area
background_area – the widget relative coordinates of the background area
callback – the GtkCellAllocCallback to call
callback_data – user provided data pointer

do_get_cell_property(renderer: CellRenderer, property_id: int, value: Any, pspec: ParamSpec) → None

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

Parameters:

renderer
property_id
value
pspec

do_get_preferred_height(context: CellAreaContext, widget: Widget) → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

context – the ``GtkCellArea``Context to perform this request with
widget – the GtkWidget where area will be rendering

do_get_preferred_height_for_width(context: CellAreaContext, widget: Widget, width: int) → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

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

do_get_preferred_width(context: CellAreaContext, widget: Widget) → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

context – the ``GtkCellArea``Context to perform this request with
widget – the GtkWidget where area will be rendering

do_get_preferred_width_for_height(context: CellAreaContext, widget: Widget, height: int) → tuple[int, int]

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

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

do_get_request_mode() → SizeRequestMode: Gets whether the area prefers a height-for-width layout or a width-for-height layout.

do_is_activatable() → bool: Returns whether the area can do anything when activated, after applying new attributes to area.

Deprecated since version 4.10: Please do not use it in newly written code

do_remove(renderer: CellRenderer) → None

Removes renderer from area.

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:: renderer – the GtkCellRenderer to remove from area

do_set_cell_property(renderer: CellRenderer, property_id: int, value: Any, pspec: ParamSpec) → None

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

Parameters:

renderer
property_id
value
pspec

do_snapshot(context: CellAreaContext, widget: Widget, snapshot: Snapshot, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState, paint_focus: bool) → None

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

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

Fields

class CellArea

parent_instance