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.TreeViewColumn
always lines up the areas from top to bottom while a gtk.icon_view.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.cell_area.CellArea
uses a gtk.cell_area_context.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 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.cell_area_context.CellAreaContext which
was used to request the sizes for a given gtk.tree_model.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.tree_model.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 gtk.cell_area_context.CellAreaContext object and can be consulted
at any time.
This can be useful since gtk.cell_layout.CellLayout widgets usually have to
support requesting and rendering rows in treemodels with an
exceedingly large amount of rows. The gtk.cell_layout.CellLayout widget in
that case would calculate the required width of the rows in an
idle or timeout source (see func@GLib.timeout_add) and when the widget
is requested its actual width in vfunc@Gtk.Widget.measure
it can simply consult the width accumulated so far in the
gtk.cell_area_context.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 gtk.cell_area_context.CellAreaContext.
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.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.cell_area.CellArea).
In order to request the height for width of all the rows at the
root level of a gtk.tree_model.TreeModel one would do the following:
GtkTreeIter 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 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.
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 func@Gtk.distribute_natural_allocation.
Passing events to the area is as simple as handling events on any
normal widget and then passing them to the gtk.cell_area.CellArea.event
API as they come in. Usually gtk.cell_area.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.cell_area.CellArea.stopEditing at any time to cancel any cell editing
that is currently in progress.
The gtk.cell_area.CellArea drives keyboard focus from cell to cell in a way
similar to gtk.widget.Widget. For layouting widgets that support giving
focus to cells it’s important to remember to pass gtk.types.CellRendererState.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 gtk.tree_model.TreeModel rows are rendered inside
the widget, so at vfunc@Gtk.Widget.focus time the layouting widget
should use the gtk.cell_area.CellArea methods to navigate focus inside the area
and then observe the gtk.types.DirectionType to pass the focus to adjacent
rows and areas.
A basic example of how the vfunc@Gtk.Widget.focus virtual method
should be implemented:
The gtk.cell_area.CellArea introduces cell properties for gtk.cell_renderer.CellRenderers.
This provides some general interfaces for defining the relationship
cell areas have with their cells. For instance in a gtk.cell_area_box.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.cell_area_context.CellAreaContext.
An abstract class for laying out gtk.cell_renderer.CellRenderers
The gtk.cell_area.CellArea is an abstract class for gtk.cell_layout.CellLayout widgets (also referred to as "layouting widgets") to interface with an arbitrary number of gtk.cell_renderer.CellRenderers and interact with the user for a given gtk.tree_model.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.cell_area.CellArea directly unless they are implementing a cell-layouting widget themselves.
Requesting area sizes
As outlined in GtkWidget’s geometry management section, GTK uses a height-for-width geometry management system to compute the sizes of widgets and user interfaces. gtk.cell_area.CellArea uses the same semantics to calculate the size of an area for an arbitrary number of gtk.tree_model.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.tree_view_column.TreeViewColumn always lines up the areas from top to bottom while a gtk.icon_view.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.cell_area.CellArea uses a gtk.cell_area_context.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.cell_area_context.CellAreaContext is an opaque object specific to the gtk.cell_area.CellArea which created it (see gtk.cell_area.CellArea.createContext).
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.cell_area_context.CellAreaContext which was used to request the sizes for a given gtk.tree_model.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.tree_model.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 gtk.cell_area_context.CellAreaContext object and can be consulted at any time.
This can be useful since gtk.cell_layout.CellLayout widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The gtk.cell_layout.CellLayout widget in that case would calculate the required width of the rows in an idle or timeout source (see func@GLib.timeout_add) and when the widget is requested its actual width in vfunc@Gtk.Widget.measure it can simply consult the width accumulated so far in the gtk.cell_area_context.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 gtk.cell_area_context.CellAreaContext.
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.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.cell_area.CellArea).
In order to request the height for width of all the rows at the root level of a gtk.tree_model.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:
GtkAllocation allocation; GdkRectangle cell_area = { 0, }; GtkTreeIter 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 func@Gtk.distribute_natural_allocation.
Handling Events and Driving Keyboard Focus
Passing events to the area is as simple as handling events on any normal widget and then passing them to the gtk.cell_area.CellArea.event API as they come in. Usually gtk.cell_area.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.cell_area.CellArea.stopEditing at any time to cancel any cell editing that is currently in progress.
The gtk.cell_area.CellArea drives keyboard focus from cell to cell in a way similar to gtk.widget.Widget. For layouting widgets that support giving focus to cells it’s important to remember to pass gtk.types.CellRendererState.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 gtk.tree_model.TreeModel rows are rendered inside the widget, so at vfunc@Gtk.Widget.focus time the layouting widget should use the gtk.cell_area.CellArea methods to navigate focus inside the area and then observe the gtk.types.DirectionType to pass the focus to adjacent rows and areas.
A basic example of how the vfunc@Gtk.Widget.focus virtual method should be implemented:
static gboolean foo_focus (GtkWidget *widget, GtkDirectionType 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.types.DirectionType values to the way it lays out its cells.
Cell Properties
The gtk.cell_area.CellArea introduces cell properties for gtk.cell_renderer.CellRenderers. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a gtk.cell_area_box.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.cell_area_context.CellAreaContext.
Use gtk.cell_area_class.CellAreaClass.installCellProperty to install cell properties for a cell area class and gtk.cell_area_class.CellAreaClass.findCellProperty or gtk.cell_area_class.CellAreaClass.listCellProperties to get information about existing cell properties.
To set the value of a cell property, use gtk.cell_area.CellArea.cellSetProperty, gtk.cell_area.CellArea.cellSet or gtk.cell_area.CellArea.cellSetValist. To obtain the value of a cell property, use gtk.cell_area.CellArea.cellGetProperty gtk.cell_area.CellArea.cellGet or gtk.cell_area.CellArea.cellGetValist.