gtk-cell-layout, gtk-buildable, g-object, common-lisp:standard-object, common-lisp:t

The gtk-cell-area class is an abstract class for gtk-cell-layout widgets, also referred to as "layouting widgets", to interface with an arbitrary number of gtk-cell-renderer objects and interact with the user for a given gtk-tree-model row.

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

Usually users do not have to interact with the gtk-cell-area object directly unless they are implementing a cell-layouting widget themselves.

Requesting area sizes

As outlined in the gtk-widget geometry management section, GTK uses a height-for-width geometry management system to compute the sizes of widgets and user interfaces. The gtk-cell-area object uses the same semantics to calculate the size of an area for an arbitrary number of gtk-tree-model 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-tree-view-column object always lines up the areas from top to bottom while a gtk-icon-view widget 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 is 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-cell-area object uses a gtk-cell-area-context 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-cell-area-context object is an opaque object specific to the gtk-cell-area object which created it, see the gtk-cell-area-create-context function. 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 is important that the same gtk-cell-area-context object which was used to request the sizes for a given gtk-tree-model 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-tree-model object one would do the following:

Example: Requesting the width of a handful of gtk-tree-model rows

GtkTreeIter iter;
gint        minimum_width;
gint        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 is 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-cell-area-context object and can be consulted at any time.

This can be useful since gtk-cell-layout widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The gtk-cell-layout widget in that case would calculate the required width of the rows in an idle or timeout source, see the g-timeout-add function, and when the widget is requested its actual width in get_preferred_width() it can simply consult the width accumulated so far in the gtk-cell-area-context 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:

Example: A typical get_preferred_width() implementation

static void
foo_get_preferred_width (GtkWidget       *widget,
                         gint            *minimum_size,
                         gint            *natural_size)
{
  Foo        *foo  = FOO (widget);
  FooPrivate *priv = foo->priv;


  foo_ensure_at_least_one_handfull_of_rows_have_been_requested (foo);


  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-cell-area-context object.

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

In order to request the height for width of all the rows at the root level of a gtk-tree-model object one would do the following:

Example: Requesting the height for width of a handful of gtk-tree-model rows

GtkTreeIter iter;
gint        minimum_height;
gint        natural_height;
gint        full_minimum_height = 0;
gint        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 is 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 the get_preferred_height_for_width() function. 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 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 aquired at least for the rows in the visible area of the layouting widget they can be rendered at draw() time.

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

Example: Requesting the width of a handful of gtk-tree-model rows

GtkAllocation allocation;
GdkRectangle  cell_area = { 0, };
GtkTreeIter   iter;
gint          minimum_width;
gint          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 "size-allocate" time using the gtk_distribute_natural_allocation() function.

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 the gtk-cell-area-event function API as they come in. Usually the gtk-cell-area object 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 the gtk-cell-area-stop-editing function at any time to cancel any cell editing that is currently in progress.

The gtk-cell-area object drives keyboard focus from cell to cell in a way similar to gtk-widget object. For layouting widgets that support giving focus to cells it is important to remember to pass the GTK_CELL_RENDERER_FOCUSED value 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 focus() virtual method. The layouting widget is always responsible for knowing where gtk-tree-model rows are rendered inside the widget, so at focus() time the layouting widget should use the gtk-cell-area methods to navigate focus inside the area and then observe the gtk-direction-type value to pass the focus to adjacent rows and areas.

A basic example of how the focus() virtual method should be implemented:

Example: Implementing keyboard focus navigation

static gboolean
foo_focus (GtkWidget       *widget,
           GtkDirectionType direction)
{
  Foo        *foo  = FOO (widget);
  FooPrivate *priv = foo->priv;
  gint        focus_row;
  gboolean    have_focus = FALSE;


  focus_row = priv->focus_row;


  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-direction-type values to the way it lays out its cells.

Cell Properties

The gtk-cell-area class introduces cell properties for gtk-cell-renderer objects in very much the same way that the gtk-container class introduces child properties for gtk-widget objects. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a gtk-cell-area-box object 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-cell-area-context object.

Use the gtk_cell_area_class_install_cell_property() function to install cell properties for a cell area class and the gtk-cell-area-class-find-cell-property or gtk-cell-area-class-list-cell-properties functions to get information about existing cell properties.

To set or get the value of a cell property, use the gtk-cell-area-cell-property, gtk-cell-area-cell-get, and gtk-cell-area-cell-set functions.

The "add-editable" signal

 lambda (area renderer editable cell-area path)    :run-first      

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

area

The gtk-cell-area object where editing started.

renderer

The gtk-cell-renderer object that started the edited.

editable

The gtk-cell-editable widget to add.

cell-area

The gtk-widget object relative gdk-rectangle coordinates where editable should be added.

path

The gtk-tree-path string this edit was initiated for.

The "apply-attributes" signal

 lambda (area model iter is-expander is-expanded)    :run-first      

The signal is emitted whenever applying attributes to the cell area from the model.

area

The gtk-cell-area object to apply the attributes to.

model

The gtk-tree-model object to apply the attributes from.

iter

The gtk-tree-iter instance 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.

The "focus-changed" signal

 lambda (area renderer path)    :run-first      

Indicates that focus changed on the cell area. The signal is emitted either as a result of focus handling or event handling. It is 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.

area

The gtk-cell-area object where focus changed.

renderer

The gtk-cell-renderer object that has focus.

path

The current gtk-tree-path string set for area.

The "remove-editable" signal

 lambda (area renderer editable)    :run-first      

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

area

The gtk-cell-area object where editing finished.

renderer

The gtk-cell-renderer object that finished editeding.

editable

The gtk-cell-editable widget to remove.