About all my projects
Gnome::Gtk4::CellArea

Gnome::Gtk4::CellArea

Description

An abstract class for laying out Gnome::Gtk4::CellRenderers

The Gnome::Gtk4::CellArea is an abstract class for Gnome::Gtk4::R-CellLayout widgets (also referred to as "layouting widgets") to interface with an arbitrary number of Gnome::Gtk4::CellRenderers and interact with the user for a given Gnome::Gtk4::R-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 Gnome::Gtk4::CellArea directly unless they are implementing a cell-layouting widget themselves.

Requesting area sizes

As outlined in [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management), GTK uses a height-for-width geometry management system to compute the sizes of widgets and user interfaces. Gnome::Gtk4::CellArea uses the same semantics to calculate the size of an area for an arbitrary number of Gnome::Gtk4::R-TreeModel 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 Gnome::Gtk4::TreeViewColumn always lines up the areas from top to bottom while a Gnome::Gtk4::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 Gnome::Gtk4::CellArea uses a Gnome::Gtk4::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 Gnome::Gtk4::CellAreaContext is an opaque object specific to the Gnome::Gtk4::CellArea which created it (see .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 Gnome::Gtk4::CellAreaContext which was used to request the sizes for a given Gnome::Gtk4::R-TreeModel 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 Gnome::Gtk4::R-TreeModel one would do the following:

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 Gnome::Gtk4::CellAreaContext object and can be consulted at any time.

This can be useful since Gnome::Gtk4::R-CellLayout widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The Gnome::Gtk4::R-CellLayout widget in that case would calculate the required width of the rows in an idle or timeout source (see .timeout-add() in package Gnome::GLib) 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 Gnome::Gtk4::CellAreaContext 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:

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 Gnome::Gtk4::CellAreaContext.

Requesting the height for width (or width for height) of an area is a similar task except in this case the Gnome::Gtk4::CellAreaContext 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 Gnome::Gtk4::CellArea).

In order to request the height for width of all the rows at the root level of a Gnome::Gtk4::R-TreeModel one would do the following:

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:

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 .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 .event() API as they come in. Usually Gnome::Gtk4::CellArea 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 focus-changed signal to fire; as well as add-editable in the case that an editable cell was clicked and needs to start editing. You can call .stop-editing() at any time to cancel any cell editing that is currently in progress.

The Gnome::Gtk4::CellArea drives keyboard focus from cell to cell in a way similar to Gnome::Gtk4::Widget. 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 Gnome::Gtk4::R-TreeModel rows are rendered inside the widget, so at [vfunc $Gtk.Widget.focus] time the layouting widget should use the Gnome::Gtk4::CellArea methods to navigate focus inside the area and then observe the enumeration DirectionType from Gnome::Gtk4::T-enums to pass the focus to adjacent rows and areas.

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

Note that the layouting widget is responsible for matching the enumeration GtkDirectionType defined in Gnome::Gtk4::T-enums values to the way it lays out its cells.

Cell Properties

The Gnome::Gtk4::CellArea introduces cell properties for Gnome::Gtk4::CellRenderers. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a Gnome::Gtk4::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 Gnome::Gtk4::CellAreaContext.

Use .install-cell-property() in class Gnome::Gtk4::CellArea to install cell properties for a cell area class and .find-cell-property() in class Gnome::Gtk4::CellArea or .list-cell-properties() in class Gnome::Gtk4::CellArea to get information about existing cell properties.

To set the value of a cell property, use .cell-set-property(), .cell-set() or .cell-set-valist(). To obtain the value of a cell property, use .cell-get-property() .cell-get() or .cell-get-valist().

Class initialization

Note: The native version of this class is deprecated in gtk4-lib() since version 4.10

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

Methods

activate

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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.

method activate ( N-Object() $context, N-Object() $widget, N-Object $cell-area, UInt $flags, Bool() $edit-only --> Bool )
  • $context; the Gnome::Gtk4::CellAreaContext in context with the current row data.

  • $widget; the Gnome::Gtk4::Widget that $area is rendering on.

  • $cell-area; the size and location of $area relative to $widget’s allocation

  • $flags; the Gnome::Gtk4::CellRendererState flags for $area for this row of data..

  • $edit-only; if True then only cell renderers that are GTK_CELL_RENDERER_MODE_EDITABLE will be activated..

Return value; Whether $area was successfully activated..

activate-cell

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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

method activate-cell ( N-Object() $widget, N-Object() $renderer, N-Object() $event, N-Object $cell-area, UInt $flags --> Bool )
  • $widget; the Gnome::Gtk4::Widget that $area is rendering onto.

  • $renderer; the Gnome::Gtk4::CellRenderer in $area to activate.

  • $event; the Gnome::Gdk4::Event for which cell activation should occur.

  • $cell-area; the Gnome::Gdk4::N-Rectangle in $widget relative coordinates of $renderer for the current row.

  • $flags; the Gnome::Gtk4::CellRendererState for $renderer.

Return value; whether cell activation was successful.

add

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Adds $renderer to $area with the default child cell properties.

method add ( N-Object() $renderer )
  • $renderer; the Gnome::Gtk4::CellRenderer to add to $area.

add-focus-sibling

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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.

method add-focus-sibling ( N-Object() $renderer, N-Object() $sibling )
  • $renderer; the Gnome::Gtk4::CellRenderer expected to have focus.

  • $sibling; the Gnome::Gtk4::CellRenderer to add to $renderer’s focus area.

add-with-properties This function is not yet available

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Adds $renderer to $area, setting cell properties at the same time. See .add() and .cell-set() for more details.

method add-with-properties ( N-Object() $renderer, Str $first-prop-name, … )
  • $renderer; a Gnome::Gtk4::CellRenderer to be placed inside $area.

  • $first-prop-name; the name of the first cell property to set.

  • …; …. Note that each argument must be specified as a type followed by its value!

apply-attributes

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Applies any connected attributes to the renderers in $area by pulling the values from $tree-model.

method apply-attributes ( N-Object() $tree-model, N-Object $iter, Bool() $is-expander, Bool() $is-expanded )
  • $tree-model; the Gnome::Gtk4::R-TreeModel to pull values from.

  • $iter; the Gnome::Gtk4::N-TreeIter 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

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Connects an $attribute to apply values from $column for the Gnome::Gtk4::R-TreeModel in use.

method attribute-connect ( N-Object() $renderer, Str $attribute, Int() $column )
  • $renderer; the Gnome::Gtk4::CellRenderer to connect an attribute for.

  • $attribute; the attribute name.

  • $column; the Gnome::Gtk4::R-TreeModel column to fetch attribute values from.

attribute-disconnect

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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

method attribute-disconnect ( N-Object() $renderer, Str $attribute )
  • $renderer; the Gnome::Gtk4::CellRenderer to disconnect an attribute for.

  • $attribute; the attribute name.

attribute-get-column

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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

method attribute-get-column ( N-Object() $renderer, Str $attribute --> Int )
  • $renderer; a Gnome::Gtk4::CellRenderer.

  • $attribute; an attribute on the renderer.

Return value; the model column, or -1.

cell-get This function is not yet available

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Gets the values of one or more cell properties for $renderer in $area.

method cell-get ( N-Object() $renderer, Str $first-prop-name, … )
  • $renderer; a Gnome::Gtk4::CellRenderer which is inside $area.

  • $first-prop-name; the name of the first cell property to get.

  • …; …. Note that each argument must be specified as a type followed by its value!

cell-get-property

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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

method cell-get-property ( N-Object() $renderer, Str $property-name, N-Object $value )
  • $renderer; a Gnome::Gtk4::CellRenderer inside $area.

  • $property-name; the name of the property to get.

  • $value; a location to return the value

cell-get-valist This function is not yet available

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Gets the values of one or more cell properties for $renderer in $area.

method cell-get-valist ( N-Object() $renderer, Str $first-property-name, … )
  • $renderer; a Gnome::Gtk4::CellRenderer inside $area.

  • $first-property-name; the name of the first property to get.

  • var-args; return location for the first property, followed optionally by more name/return location pairs, followed by undefined. Note that each argument must be specified as a type followed by its value!

cell-set This function is not yet available

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Sets one or more cell properties for $cell in $area.

method cell-set ( N-Object() $renderer, Str $first-prop-name, … )
  • $renderer; a Gnome::Gtk4::CellRenderer which is a cell inside $area.

  • $first-prop-name; the name of the first cell property to set.

  • …; …. Note that each argument must be specified as a type followed by its value!

cell-set-property

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Sets a cell property for $renderer in $area.

method cell-set-property ( N-Object() $renderer, Str $property-name, N-Object $value )
  • $renderer; a Gnome::Gtk4::CellRenderer inside $area.

  • $property-name; the name of the cell property to set.

  • $value; the value to set the cell property to

cell-set-valist This function is not yet available

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Sets one or more cell properties for $renderer in $area.

method cell-set-valist ( N-Object() $renderer, Str $first-property-name, … )
  • $renderer; a Gnome::Gtk4::CellRenderer which inside $area.

  • $first-property-name; the name of the first cell property to set.

  • var-args; a undefined-terminated list of property names and values, starting with $first-prop-name. Note that each argument must be specified as a type followed by its value!

copy-context

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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, Gnome::Gtk4::IconView 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. Gnome::Gtk4::IconView 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.

method copy-context ( N-Object() $context --> N-Object )
  • $context; the Gnome::Gtk4::CellAreaContext to copy.

Return value; a newly created Gnome::Gtk4::CellAreaContext copy of $context..

create-context

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Creates a Gnome::Gtk4::CellAreaContext to be used with $area for all purposes. Gnome::Gtk4::CellAreaContext 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 Gnome::Gtk4::CellAreaContext which was used to request the size of those rows of data).

method create-context (--> N-Object )

Return value; a newly created Gnome::Gtk4::CellAreaContext which can be used with $area..

event

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Delegates event handling to a Gnome::Gtk4::CellArea.

method event ( N-Object() $context, N-Object() $widget, N-Object() $event, N-Object $cell-area, UInt $flags --> Int )
  • $context; the Gnome::Gtk4::CellAreaContext for this row of data..

  • $widget; the Gnome::Gtk4::Widget that $area is rendering to.

  • $event; the Gnome::Gdk4::Event to handle.

  • $cell-area; the $widget relative coordinates for $area

  • $flags; the Gnome::Gtk4::CellRendererState for $area in this row..

Return value; True if the event was handled by $area..

focus

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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 Gnome::Gtk4::CellArea classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells.

method focus ( GtkDirectionType $direction --> Bool )
  • $direction; the enumeration GtkDirectionType defined in Gnome::Gtk4::T-enums.

Return value; True if focus remains inside $area as a result of this call..

foreach

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Calls $callback for every Gnome::Gtk4::CellRenderer in $area.

method foreach ( &callback, gpointer $callback-data )
  • &callback; the Gnome::Gtk4::T-cellarea to call. Tthe function must be specified with following signature; :( N-Object $renderer, gpointer $data -- gboolean )>.

  • $callback-data; user provided data pointer.

foreach-alloc

Calls $callback for every Gnome::Gtk4::CellRenderer in $area with the allocated rectangle inside $cell-area.

method foreach-alloc ( N-Object() $context, N-Object() $widget, N-Object $cell-area, N-Object $background-area, &callback, gpointer $callback-data )
  • $context; the Gnome::Gtk4::CellAreaContext for this row of data..

  • $widget; the Gnome::Gtk4::Widget 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 Gnome::Gtk4::T-cellarea to call. Tthe function must be specified with following signature; :( N-Object $renderer, N-Object $cell-area, N-Object $cell-background, gpointer $data -- gboolean )>.

  • $callback-data; user provided data pointer.

get-cell-allocation

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Derives the allocation of $renderer inside $area if $area were to be rendered in $cell-area.

method get-cell-allocation ( N-Object() $context, N-Object() $widget, N-Object() $renderer, N-Object $cell-area, N-Object $allocation )
  • $context; the Gnome::Gtk4::CellAreaContext used to hold sizes for $area..

  • $widget; the Gnome::Gtk4::Widget that $area is rendering on.

  • $renderer; the Gnome::Gtk4::CellRenderer to get the allocation for.

  • $cell-area; the whole allocated area for $area in $widget for this row

  • $allocation; where to store the allocation for $renderer

get-cell-at-position

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Gets the Gnome::Gtk4::CellRenderer at $x and $y coordinates inside $area and optionally returns the full cell allocation for it inside $cell-area.

method get-cell-at-position ( N-Object() $context, N-Object() $widget, N-Object $cell-area, Int() $x, Int() $y, N-Object $alloc-area --> N-Object )
  • $context; the Gnome::Gtk4::CellAreaContext used to hold sizes for $area..

  • $widget; the Gnome::Gtk4::Widget 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.

  • $alloc-area; where to store the inner allocated area of the returned cell renderer

Return value; the Gnome::Gtk4::CellRenderer at $x and $y..

get-current-path-string

Gets the current Gnome::Gtk4::N-TreePath string for the currently applied Gnome::Gtk4::N-TreeIter, this is implicitly updated when .apply-attributes() is called and can be used to interact with renderers from Gnome::Gtk4::CellArea subclasses.

method get-current-path-string (--> Str )

Return value; The current Gnome::Gtk4::N-TreePath string for the current attributes applied to $area. This string belongs to the area and should not be freed..

get-edit-widget

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Gets the Gnome::Gtk4::R-CellEditable widget currently used to edit the currently edited cell.

method get-edit-widget (--> N-Object )

Return value; The currently active Gnome::Gtk4::R-CellEditable widget.

get-edited-cell

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Gets the Gnome::Gtk4::CellRenderer in $area that is currently being edited.

method get-edited-cell (--> N-Object )

Return value; The currently edited Gnome::Gtk4::CellRenderer.

get-focus-cell

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Retrieves the currently focused cell for $area

method get-focus-cell (--> N-Object )

Return value; the currently focused cell in $area..

get-focus-from-sibling

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Gets the Gnome::Gtk4::CellRenderer which is expected to be focusable for which $renderer is, or may be a sibling.

This is handy for Gnome::Gtk4::CellArea 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.

method get-focus-from-sibling ( N-Object() $renderer --> N-Object )
  • $renderer; the Gnome::Gtk4::CellRenderer.

Return value; the Gnome::Gtk4::CellRenderer for which $renderer is a sibling.

get-focus-siblings

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Gets the focus sibling cell renderers for $renderer.

method get-focus-siblings ( N-Object() $renderer --> N-List )
  • $renderer; the Gnome::Gtk4::CellRenderer expected to have focus.

Return value; A Gnome::Glib::N-List of Gnome::Gtk4::CellRenderers. The returned list is internal and should not be freed..

get-preferred-height

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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 .context-get-preferred-height() after a series of requests.

method get-preferred-height ( N-Object() $context, N-Object() $widget, Array[Int] $minimum-height, Array[Int] $natural-height )
  • $context; the Gnome::Gtk4::CellAreaContext to perform this request with.

  • $widget; the Gnome::Gtk4::Widget where $area will be rendering.

  • $minimum-height; (transfer ownership: full) location to store the minimum height.

  • $natural-height; (transfer ownership: full) location to store the natural height.

get-preferred-height-for-width

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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 .context-get-preferred-width().

method get-preferred-height-for-width ( N-Object() $context, N-Object() $widget, Int() $width, Array[Int] $minimum-height, Array[Int] $natural-height )
  • $context; the Gnome::Gtk4::CellAreaContext which has already been requested for widths..

  • $widget; the Gnome::Gtk4::Widget where $area will be rendering.

  • $width; the width for which to check the height of this area.

  • $minimum-height; (transfer ownership: full) location to store the minimum height.

  • $natural-height; (transfer ownership: full) location to store the natural height.

get-preferred-width

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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 .context-get-preferred-width() after a series of requests.

method get-preferred-width ( N-Object() $context, N-Object() $widget, Array[Int] $minimum-width, Array[Int] $natural-width )
  • $context; the Gnome::Gtk4::CellAreaContext to perform this request with.

  • $widget; the Gnome::Gtk4::Widget where $area will be rendering.

  • $minimum-width; (transfer ownership: full) location to store the minimum width.

  • $natural-width; (transfer ownership: full) location to store the natural width.

get-preferred-width-for-height

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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 .context-get-preferred-height().

method get-preferred-width-for-height ( N-Object() $context, N-Object() $widget, Int() $height, Array[Int] $minimum-width, Array[Int] $natural-width )
  • $context; the Gnome::Gtk4::CellAreaContext which has already been requested for widths..

  • $widget; the Gnome::Gtk4::Widget where $area will be rendering.

  • $height; the height for which to check the width of this area.

  • $minimum-width; (transfer ownership: full) location to store the minimum width.

  • $natural-width; (transfer ownership: full) location to store the natural width.

get-request-mode

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

method get-request-mode (--> GtkSizeRequestMode )

Return value; The enumeration GtkSizeRequestMode defined in Gnome::Gtk4::T-enums preferred by $area..

has-renderer

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Checks if $area contains $renderer.

method has-renderer ( N-Object() $renderer --> Bool )
  • $renderer; the Gnome::Gtk4::CellRenderer to check.

Return value; True if $renderer is in the $area..

inner-cell-area

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

This is a convenience function for Gnome::Gtk4::CellArea implementations to get the inner area where a given Gnome::Gtk4::CellRenderer will be rendered. It removes any padding previously added by .request-renderer().

method inner-cell-area ( N-Object() $widget, N-Object $cell-area, N-Object $inner-area )
  • $widget; the Gnome::Gtk4::Widget that $area is rendering onto.

  • $cell-area; the $widget relative coordinates where one of $area’s cells is to be placed

  • $inner-area; the return location for the inner cell area

is-activatable

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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

method is-activatable (--> Bool )

Return value; whether $area can do anything when activated..

is-focus-sibling

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Returns whether $sibling is one of $renderer’s focus siblings (see .add-focus-sibling()).

method is-focus-sibling ( N-Object() $renderer, N-Object() $sibling --> Bool )
  • $renderer; the Gnome::Gtk4::CellRenderer expected to have focus.

  • $sibling; the Gnome::Gtk4::CellRenderer to check against $renderer’s sibling list.

Return value; True if $sibling is a focus sibling of $renderer.

remove

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Removes $renderer from $area.

method remove ( N-Object() $renderer )
  • $renderer; the Gnome::Gtk4::CellRenderer to remove from $area.

remove-focus-sibling

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Removes $sibling from $renderer’s focus sibling list (see .add-focus-sibling()).

method remove-focus-sibling ( N-Object() $renderer, N-Object() $sibling )
  • $renderer; the Gnome::Gtk4::CellRenderer expected to have focus.

  • $sibling; the Gnome::Gtk4::CellRenderer to remove from $renderer’s focus area.

request-renderer

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

This is a convenience function for Gnome::Gtk4::CellArea 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.

method request-renderer ( N-Object() $renderer, GtkOrientation $orientation, N-Object() $widget, Int() $for-size, Array[Int] $minimum-size, Array[Int] $natural-size )
  • $renderer; the Gnome::Gtk4::CellRenderer to request size for.

  • $orientation; the enumeration GtkOrientation defined in Gnome::Gtk4::T-enums in which to request size.

  • $widget; the Gnome::Gtk4::Widget 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..

  • $minimum-size; (transfer ownership: full) location to store the minimum size.

  • $natural-size; (transfer ownership: full) location to store the natural size.

set-focus-cell

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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

method set-focus-cell ( N-Object() $renderer )
  • $renderer; the Gnome::Gtk4::CellRenderer to give focus to.

snapshot

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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

method snapshot ( N-Object() $context, N-Object() $widget, N-Object() $snapshot, N-Object $background-area, N-Object $cell-area, UInt $flags, Bool() $paint-focus )
  • $context; the Gnome::Gtk4::CellAreaContext for this row of data..

  • $widget; the Gnome::Gtk4::Widget that $area is rendering to.

  • $snapshot; the Gnome::Gtk4::Snapshot to draw to.

  • $background-area; the $widget relative coordinates for $area’s background

  • $cell-area; the $widget relative coordinates for $area

  • $flags; the Gnome::Gtk4::CellRendererState for $area in this row..

  • $paint-focus; whether $area should paint focus on focused cells for focused rows or not..

stop-editing

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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

method stop-editing ( Bool() $canceled )
  • $canceled; whether editing was canceled..

Signals

add-editable

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

method handler (
  N-Object $renderer,
  N-Object $editable,
   $cell-area,
  Str $path,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::CellArea :$_widget,
  *C<user>-options
)
  • $renderer; the Gnome::Gtk4::CellRenderer that started the edited.

  • $editable; the Gnome::Gtk4::R-CellEditable widget to add.

  • $cell-area; the Gnome::Gtk4::Widget relative Gnome::Gdk4::N-Rectangle coordinates where $editable should be added.

  • $path; the Gnome::Gtk4::N-TreePath string this edit was initiated for.

  • $_handle_id; The registered event handler id.

  • $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::CellArea object.

  • $_widget; The object which registered the signal. User code may have left the object going out of scope.

  • user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

apply-attributes

This signal is emitted whenever applying attributes to $area from $model

method handler (
  N-Object $model,
  N-Object $iter,
  gboolean $is-expander,
  gboolean $is-expanded,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::CellArea :$_widget,
  *C<user>-options
)
  • $model; the Gnome::Gtk4::R-TreeModel to apply the attributes from.

  • $iter; the Gnome::Gtk4::N-TreeIter 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.

  • $_handle_id; The registered event handler id.

  • $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::CellArea object.

  • $_widget; The object which registered the signal. User code may have left the object going out of scope.

  • user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

focus-changed

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.

method handler (
  N-Object $renderer,
  Str $path,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::CellArea :$_widget,
  *C<user>-options
)
  • $renderer; the Gnome::Gtk4::CellRenderer that has focus.

  • $path; the current Gnome::Gtk4::N-TreePath string set for $area.

  • $_handle_id; The registered event handler id.

  • $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::CellArea object.

  • $_widget; The object which registered the signal. User code may have left the object going out of scope.

  • user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

remove-editable

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

method handler (
  N-Object $renderer,
  N-Object $editable,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::CellArea :$_widget,
  *C<user>-options
)
  • $renderer; the Gnome::Gtk4::CellRenderer that finished editeding.

  • $editable; the Gnome::Gtk4::R-CellEditable widget to remove.

  • $_handle_id; The registered event handler id.

  • $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::CellArea object.

  • $_widget; The object which registered the signal. User code may have left the object going out of scope.

  • user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.