Description
The GtkCellArea is an abstract class for GtkCellLayout widgets
(also referred to as "layouting widgets") to interface with an
arbitrary number of GtkCellRenderers and interact with the user
for a given GtkTreeModel 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 GtkCellArea 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. GtkCellArea uses the same semantics to calculate the
size of an area for an arbitrary number of GtkTreeModel 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 GtkTreeViewColumn
always lines up the areas from top to bottom while a GtkIconView
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 GtkCellArea
uses a GtkCellAreaContext 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 GtkCellAreaContext is an opaque object specific to the
GtkCellArea which created it (see gtk_cell_area_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 GtkCellAreaContext which
was used to request the sizes for a given GtkTreeModel 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 GtkTreeModel 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 GtkCellAreaContext object and can be consulted
at any time.
This can be useful since GtkCellLayout widgets usually have to
support requesting and rendering rows in treemodels with an
exceedingly large amount of rows. The GtkCellLayout widget in
that case would calculate the required width of the rows in an
idle or timeout source (see g_timeout_add()) and when the widget
is requested its actual width in GtkWidgetClass.get_preferred_width()
it can simply consult the width accumulated so far in the
GtkCellAreaContext 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 GtkCellAreaContext.
Requesting the height for width (or width for height) of an area is
a similar task except in this case the GtkCellAreaContext 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 GtkCellArea).
In order to request the height for width of all the rows at the
root level of a GtkTreeModel 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 GtkWidgetClass.get_preferred_height_for_width(). 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 aquired at least for the rows in the
visible area of the layouting widget they can be rendered at
GtkWidgetClass.draw() 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
“size-allocate” time 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_cell_area_event()
API as they come in. Usually GtkCellArea 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
gtk_cell_area_stop_editing() at any time to cancel any cell editing
that is currently in progress.
The GtkCellArea drives keyboard focus from cell to cell in a way
similar to GtkWidget. 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
GtkWidgetClass.focus() virtual method. The layouting widget is always
responsible for knowing where GtkTreeModel rows are rendered inside
the widget, so at GtkWidgetClass.focus() time the layouting widget
should use the GtkCellArea methods to navigate focus inside the area
and then observe the GtkDirectionType to pass the focus to adjacent
rows and areas.
A basic example of how the GtkWidgetClass.focus() virtual method
should be implemented:
Note that the layouting widget is responsible for matching the
GtkDirectionType values to the way it lays out its cells.
Functions
GTK_CELL_AREA_WARN_INVALID_CELL_PROPERTY_ID()
#define GTK_CELL_AREA_WARN_INVALID_CELL_PROPERTY_ID(object, property_id, pspec)
This macro should be used to emit a standard warning about unexpected
properties in set_cell_property() and get_cell_property() implementations.
gtk_cell_area_add ()
void
gtk_cell_area_add (GtkCellArea *area,
GtkCellRenderer *renderer);
Adds renderer
to area
with the default child cell properties.
Since: 3.0
gtk_cell_area_create_context ()
GtkCellAreaContext *
gtk_cell_area_create_context (GtkCellArea *area);
Creates a GtkCellAreaContext to be used with area
for
all purposes. GtkCellAreaContext 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 GtkCellAreaContext
which was used to request the size of those rows of data).
Since: 3.0
gtk_cell_area_copy_context ()
GtkCellAreaContext *
gtk_cell_area_copy_context (GtkCellArea *area,
GtkCellAreaContext *context);
This is sometimes needed for cases where rows need to share
alignments in one orientation but may be separately grouped
in the opposing orientation.
For instance, GtkIconView creates all icons (rows) to have
the same width and the cells theirin to have the same
horizontal alignments. However each row of icons may have
a separate collective height. GtkIconView uses this to
request the heights of each row based on a context which
was already used to request all the row widths that are
to be displayed.
Since: 3.0
gtk_cell_area_get_request_mode ()
GtkSizeRequestMode
gtk_cell_area_get_request_mode (GtkCellArea *area);
Gets whether the area prefers a height-for-width layout
or a width-for-height layout.
Since: 3.0
gtk_cell_area_get_preferred_width ()
void
gtk_cell_area_get_preferred_width (GtkCellArea *area,
GtkCellAreaContext *context,
GtkWidget *widget,
gint *minimum_width,
gint *natural_width);
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.
Since: 3.0
gtk_cell_area_get_preferred_height ()
void
gtk_cell_area_get_preferred_height (GtkCellArea *area,
GtkCellAreaContext *context,
GtkWidget *widget,
gint *minimum_height,
gint *natural_height);
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.
Since: 3.0
gtk_cell_area_get_current_path_string ()
const gchar *
gtk_cell_area_get_current_path_string (GtkCellArea *area);
Gets the current GtkTreePath string for the currently
applied GtkTreeIter, this is implicitly updated when
gtk_cell_area_apply_attributes() is called and can be
used to interact with renderers from GtkCellArea
subclasses.
Returns
The current GtkTreePath string for the current
attributes applied to area
. This string belongs to the area and
should not be freed.
Since: 3.0
gtk_cell_area_apply_attributes ()
void
gtk_cell_area_apply_attributes (GtkCellArea *area,
GtkTreeModel *tree_model,
GtkTreeIter *iter,
gboolean is_expander,
gboolean is_expanded);
Applies any connected attributes to the renderers in
area
by pulling the values from tree_model
.
Since: 3.0
gtk_cell_area_attribute_disconnect ()
void
gtk_cell_area_attribute_disconnect (GtkCellArea *area,
GtkCellRenderer *renderer,
const gchar *attribute);
Disconnects attribute
for the renderer
in area
so that
attribute will no longer be updated with values from the
model.
Since: 3.0
gtk_cell_area_attribute_get_column ()
gint
gtk_cell_area_attribute_get_column (GtkCellArea *area,
GtkCellRenderer *renderer,
const gchar *attribute);
Returns the model column that an attribute has been mapped to,
or -1 if the attribute is not mapped.
Returns
the model column, or -1
Since: 3.14
gtk_cell_area_class_install_cell_property ()
void
gtk_cell_area_class_install_cell_property
(GtkCellAreaClass *aclass,
guint property_id,
GParamSpec *pspec);
Installs a cell property on a cell area class.
Since: 3.0
gtk_cell_area_class_find_cell_property ()
GParamSpec *
gtk_cell_area_class_find_cell_property
(GtkCellAreaClass *aclass,
const gchar *property_name);
Finds a cell property of a cell area class by name.
Returns
the GParamSpec of the child property
or NULL if aclass
has no child property with that name.
[transfer none]
Since: 3.0
gtk_cell_area_class_list_cell_properties ()
GParamSpec **
gtk_cell_area_class_list_cell_properties
(GtkCellAreaClass *aclass,
guint *n_properties);
Returns all cell properties of a cell area class.
Returns
a newly
allocated NULL-terminated array of GParamSpec*. The array
must be freed with g_free().
[array length=n_properties][transfer container]
Since: 3.0
gtk_cell_area_cell_set ()
void
gtk_cell_area_cell_set (GtkCellArea *area,
GtkCellRenderer *renderer,
const gchar *first_prop_name,
...);
Sets one or more cell properties for cell
in area
.
Since: 3.0
gtk_cell_area_cell_get ()
void
gtk_cell_area_cell_get (GtkCellArea *area,
GtkCellRenderer *renderer,
const gchar *first_prop_name,
...);
Gets the values of one or more cell properties for renderer
in area
.
Since: 3.0
gtk_cell_area_cell_set_valist ()
void
gtk_cell_area_cell_set_valist (GtkCellArea *area,
GtkCellRenderer *renderer,
const gchar *first_property_name,
va_list var_args);
Sets one or more cell properties for renderer
in area
.
Since: 3.0
gtk_cell_area_cell_get_valist ()
void
gtk_cell_area_cell_get_valist (GtkCellArea *area,
GtkCellRenderer *renderer,
const gchar *first_property_name,
va_list var_args);
Gets the values of one or more cell properties for renderer
in area
.
Since: 3.0
gtk_cell_area_cell_set_property ()
void
gtk_cell_area_cell_set_property (GtkCellArea *area,
GtkCellRenderer *renderer,
const gchar *property_name,
const GValue *value);
Sets a cell property for renderer
in area
.
Since: 3.0
gtk_cell_area_cell_get_property ()
void
gtk_cell_area_cell_get_property (GtkCellArea *area,
GtkCellRenderer *renderer,
const gchar *property_name,
GValue *value);
Gets the value of a cell property for renderer
in area
.
Since: 3.0
gtk_cell_area_is_activatable ()
gboolean
gtk_cell_area_is_activatable (GtkCellArea *area);
Returns whether the area can do anything when activated,
after applying new attributes to area
.
Returns
whether area
can do anything when activated.
Since: 3.0
gtk_cell_area_activate ()
gboolean
gtk_cell_area_activate (GtkCellArea *area,
GtkCellAreaContext *context,
GtkWidget *widget,
const GdkRectangle *cell_area,
GtkCellRendererState flags,
gboolean edit_only);
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.
Returns
Whether area
was successfully activated.
Since: 3.0
gtk_cell_area_focus ()
gboolean
gtk_cell_area_focus (GtkCellArea *area,
GtkDirectionType direction);
This should be called by the area
’s owning layout widget
when focus is to be passed to area
, or moved within area
for a given direction
and row data.
Implementing GtkCellArea classes should implement this
method to receive and navigate focus in its own way particular
to how it lays out cells.
Returns
TRUE if focus remains inside area
as a result of this call.
Since: 3.0
gtk_cell_area_get_focus_cell ()
GtkCellRenderer *
gtk_cell_area_get_focus_cell (GtkCellArea *area);
Retrieves the currently focused cell for area
Returns
the currently focused cell in area
.
[transfer none]
Since: 3.0
gtk_cell_area_add_focus_sibling ()
void
gtk_cell_area_add_focus_sibling (GtkCellArea *area,
GtkCellRenderer *renderer,
GtkCellRenderer *sibling);
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
.
Since: 3.0
gtk_cell_area_get_focus_siblings ()
const GList *
gtk_cell_area_get_focus_siblings (GtkCellArea *area,
GtkCellRenderer *renderer);
Gets the focus sibling cell renderers for renderer
.
Returns
A GList of GtkCellRenderers.
The returned list is internal and should not be freed.
[element-type GtkCellRenderer][transfer none]
Since: 3.0
gtk_cell_area_get_focus_from_sibling ()
GtkCellRenderer *
gtk_cell_area_get_focus_from_sibling (GtkCellArea *area,
GtkCellRenderer *renderer);
Gets the GtkCellRenderer which is expected to be focusable
for which renderer
is, or may be a sibling.
This is handy for GtkCellArea subclasses when handling events,
after determining the renderer at the event location it can
then chose to activate the focus cell for which the event
cell may have been a sibling.
Returns
the GtkCellRenderer for which renderer
is a sibling, or NULL.
[nullable][transfer none]
Since: 3.0