class Gtk::CellArea

Overview

An abstract class for laying out Gtk::CellRenderers

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

Requesting area sizes

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

WARNING ⚠️ The following code is in c ⚠️

Gtk::TreeIter iter;
int minimum_width;
int natural_width;

valid = gtk_tree_model_get_iter_first (model, &iter);
while (valid)
  {
    gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE);
    gtk_cell_area_get_preferred_width (area, context, widget, NULL, NULL);

    valid = gtk_tree_model_iter_next (model, &iter);
  }

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

This can be useful since Gtk::CellLayout widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The Gtk::CellLayout widget in that case would calculate the required width of the rows in an idle or timeout source (see GLib::timeout_add) and when the widget is requested its actual width in Gtk::Widget#measure it can simply consult the width accumulated so far in the Gtk::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:

WARNING ⚠️ The following code is in 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_cell_area_context_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 Gtk::CellAreaContext.

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

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

WARNING ⚠️ The following code is in c ⚠️

Gtk::TreeIter iter;
int minimum_height;
int natural_height;
int full_minimum_height = 0;
int full_natural_height = 0;

valid = gtk_tree_model_get_iter_first (model, &iter);
while (valid)
  {
    gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE);
    gtk_cell_area_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_tree_model_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 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 Gtk::Widget#snapshot time.

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

WARNING ⚠️ The following code is in c ⚠️

Gtk::Allocation 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_tree_model_get_iter_first (model, &iter);
while (valid)
  {
    cell_area.height = get_cached_height_for_row (&iter);

    gtk_cell_area_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_tree_model_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 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 Gtk::CellArea#event API as they come in. Usually Gtk::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 [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 Gtk::CellArea#stop_editing at any time to cancel any cell editing that is currently in progress.

The Gtk::CellArea drives keyboard focus from cell to cell in a way similar to Gtk::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 Gtk::Widget#focus virtual method. The layouting widget is always responsible for knowing where Gtk::TreeModel rows are rendered inside the widget, so at Gtk::Widget#focus time the layouting widget should use the Gtk::CellArea methods to navigate focus inside the area and then observe the Gtk::DirectionType to pass the focus to adjacent rows and areas.

A basic example of how the Gtk::Widget#focus virtual method should be implemented:

static gboolean
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;
  gboolean have_focus = FALSE;

  if (!gtk_widget_has_focus (widget))
    gtk_widget_grab_focus (widget);

  valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, priv->focus_row);
  while (valid)
    {
      gtk_cell_area_apply_attributes (priv->area, priv->model, &iter, FALSE, FALSE);

      if (gtk_cell_area_focus (priv->area, direction))
        {
           priv->focus_row = focus_row;
           have_focus = TRUE;
           break;
        }
      else
        {
          if (direction == GTK_DIR_RIGHT ||
              direction == GTK_DIR_LEFT)
            break;
          else if (direction == GTK_DIR_UP ||
                   direction == GTK_DIR_TAB_BACKWARD)
           {
              if (focus_row == 0)
                break;
              else
               {
                  focus_row--;
                  valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, focus_row);
               }
            }
          else
            {
              if (focus_row == last_row)
                break;
              else
                {
                  focus_row++;
                  valid = gtk_tree_model_iter_next (priv->model, &iter);
                }
            }
        }
    }
    return have_focus;
}

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

Cell Properties

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

Use Gtk::CellAreaClass#install_cell_property to install cell properties for a cell area class and Gtk::CellAreaClass#find_cell_property or Gtk::CellAreaClass#list_cell_properties to get information about existing cell properties.

To set the value of a cell property, use Gtk::CellArea#cell_set_property, Gtk::CellArea#cell_set or Gtk::CellArea#cell_set_valist. To obtain the value of a cell property, use Gtk::CellArea#cell_get_property Gtk::CellArea#cell_get or Gtk::CellArea#cell_get_valist.

Included Modules

Direct Known Subclasses

Defined in:

lib/gi-crystal/src/auto/gtk-4.0/cell_area.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from module Gtk::CellLayout

add_attribute(cell : Gtk::CellRenderer, attribute : String, column : Int32) : Nil add_attribute, area : Gtk::CellArea? area, cells : GLib::List cells, clear : Nil clear, clear_attributes(cell : Gtk::CellRenderer) : Nil clear_attributes, pack_end(cell : Gtk::CellRenderer, expand : Bool) : Nil pack_end, pack_start(cell : Gtk::CellRenderer, expand : Bool) : Nil pack_start, reorder(cell : Gtk::CellRenderer, position : Int32) : Nil reorder, set_cell_data_func(cell : Gtk::CellRenderer, func : Gtk::CellLayoutDataFunc?) : Nil set_cell_data_func, to_unsafe to_unsafe

Class methods inherited from module Gtk::CellLayout

g_type : UInt64 g_type

Instance methods inherited from module Gtk::Buildable

buildable_id : String? buildable_id, to_unsafe to_unsafe

Class methods inherited from module Gtk::Buildable

g_type : UInt64 g_type

Constructor methods inherited from class GObject::InitiallyUnowned

new new

Class methods inherited from class GObject::InitiallyUnowned

g_type : UInt64 g_type

Instance methods inherited from class GObject::Object

bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void)? data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void)? qdata, ref_count : UInt32 ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void)?) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void)? steal_data, steal_qdata(quark : UInt32) : Pointer(Void)? steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, cast?(obj : GObject::Object) : self? cast?, new(pointer : Pointer(Void), transfer : GICrystal::Transfer)
new new, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

compat_control(what : UInt64, data : Pointer(Void)?) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Constructor Detail

def self.new #

Initialize a new CellArea.


def self.new(*, edit_widget : Gtk::CellEditable? = nil, edited_cell : Gtk::CellRenderer? = nil, focus_cell : Gtk::CellRenderer? = nil) #

Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


Instance Method Detail

def activate(context : Gtk::CellAreaContext, widget : Gtk::Widget, cell_area : Gdk::Rectangle, flags : Gtk::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.


def activate_cell(widget : Gtk::Widget, renderer : Gtk::CellRenderer, event : Gdk::Event, cell_area : Gdk::Rectangle, flags : Gtk::CellRendererState) : Bool #

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


def add(renderer : Gtk::CellRenderer) : Nil #

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


def add_editable_signal #

def add_focus_sibling(renderer : Gtk::CellRenderer, sibling : Gtk::CellRenderer) : Nil #

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.


def apply_attributes(tree_model : Gtk::TreeModel, iter : Gtk::TreeIter, is_expander : Bool, is_expanded : Bool) : Nil #

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


def apply_attributes_signal #

def attribute_connect(renderer : Gtk::CellRenderer, attribute : String, column : Int32) : Nil #

Connects an @attribute to apply values from @column for the Gtk::TreeModel in use.


def attribute_disconnect(renderer : Gtk::CellRenderer, attribute : String) : Nil #

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


def attribute_get_column(renderer : Gtk::CellRenderer, attribute : String) : Int32 #

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


def cell_allocation(context : Gtk::CellAreaContext, widget : Gtk::Widget, renderer : Gtk::CellRenderer, cell_area : Gdk::Rectangle) : Gdk::Rectangle #

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


def cell_at_position(context : Gtk::CellAreaContext, widget : Gtk::Widget, cell_area : Gdk::Rectangle, x : Int32, y : Int32) : Gdk::Rectangle #

Gets the Gtk::CellRenderer at @x and @y coordinates inside @area and optionally returns the full cell allocation for it inside @cell_area.


def cell_get_property(renderer : Gtk::CellRenderer, property_name : String, value : _) : Nil #

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


def cell_set_property(renderer : Gtk::CellRenderer, property_name : String, value : _) : Nil #

Sets a cell property for @renderer in @area.


def copy_context(context : Gtk::CellAreaContext) : 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, Gtk::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. Gtk::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.


def create_context : Gtk::CellAreaContext #

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


def current_path_string : String #

Gets the current Gtk::TreePath string for the currently applied Gtk::TreeIter, this is implicitly updated when gtk_cell_area_apply_attributes() is called and can be used to interact with renderers from Gtk::CellArea subclasses.


def edit_widget : Gtk::CellEditable? #

Gets the Gtk::CellEditable widget currently used to edit the currently edited cell.


def edited_cell : Gtk::CellRenderer? #

Gets the Gtk::CellRenderer in @area that is currently being edited.


def event(context : Gtk::CellAreaContext, widget : Gtk::Widget, event : Gdk::Event, cell_area : Gdk::Rectangle, flags : Gtk::CellRendererState) : Int32 #

Delegates event handling to a Gtk::CellArea.


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


def focus_cell : Gtk::CellRenderer? #

Retrieves the currently focused cell for @area


def focus_cell=(renderer : Gtk::CellRenderer?) : Nil #

Explicitly sets the currently focused cell to @renderer.

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


def focus_changed_signal #

def focus_from_sibling(renderer : Gtk::CellRenderer) : Gtk::CellRenderer? #

Gets the Gtk::CellRenderer which is expected to be focusable for which @renderer is, or may be a sibling.

This is handy for Gtk::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.


def focus_siblings(renderer : Gtk::CellRenderer) : GLib::List #

Gets the focus sibling cell renderers for @renderer.


def foreach(callback : Gtk::CellCallback, callback_data : Pointer(Void)?) : Nil #

Calls @callback for every Gtk::CellRenderer in @area.


def foreach_alloc(context : Gtk::CellAreaContext, widget : Gtk::Widget, cell_area : Gdk::Rectangle, background_area : Gdk::Rectangle, callback : Gtk::CellAllocCallback, callback_data : Pointer(Void)?) : Nil #

Calls @callback for every Gtk::CellRenderer in @area with the allocated rectangle inside @cell_area.


def has_renderer(renderer : Gtk::CellRenderer) : Bool #

Checks if @area contains @renderer.


def inner_cell_area(widget : Gtk::Widget, cell_area : Gdk::Rectangle) : Gdk::Rectangle #

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


def is_activatable : Bool #

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


def is_focus_sibling(renderer : Gtk::CellRenderer, sibling : Gtk::CellRenderer) : Bool #

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


def preferred_height(context : Gtk::CellAreaContext, widget : Gtk::Widget) : Nil #

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_cell_area_context_get_preferred_height() after a series of requests.


def preferred_height_for_width(context : Gtk::CellAreaContext, widget : Gtk::Widget, width : Int32) : Nil #

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_cell_area_get_preferred_width(). It’s important to perform a series of gtk_cell_area_get_preferred_width() requests with @context first and then call gtk_cell_area_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_cell_area_get_preferred_width() again and then the full width of the requested rows checked again with gtk_cell_area_context_get_preferred_width().


def preferred_width(context : Gtk::CellAreaContext, widget : Gtk::Widget) : Nil #

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_cell_area_context_get_preferred_width() after a series of requests.


def preferred_width_for_height(context : Gtk::CellAreaContext, widget : Gtk::Widget, height : Int32) : Nil #

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_cell_area_get_preferred_height(). It’s important to perform a series of gtk_cell_area_get_preferred_height() requests with @context first and then call gtk_cell_area_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_cell_area_get_preferred_height() again and then the full height of the requested rows checked again with gtk_cell_area_context_get_preferred_height().


def remove(renderer : Gtk::CellRenderer) : Nil #

Removes @renderer from @area.


def remove_editable_signal #

def remove_focus_sibling(renderer : Gtk::CellRenderer, sibling : Gtk::CellRenderer) : Nil #

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


def request_mode : Gtk::SizeRequestMode #

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


def request_renderer(renderer : Gtk::CellRenderer, orientation : Gtk::Orientation, widget : Gtk::Widget, for_size : Int32) : Nil #

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


def snapshot(context : Gtk::CellAreaContext, widget : Gtk::Widget, snapshot : Gtk::Snapshot, background_area : Gdk::Rectangle, cell_area : Gdk::Rectangle, flags : Gtk::CellRendererState, paint_focus : Bool) : Nil #

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


def stop_editing(canceled : Bool) : Nil #

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_cell_area_get_edited_cell() and gtk_cell_area_get_edit_widget().