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.
This is used by #GtkCellArea subclasses when handling events to activate cells, the base #GtkCellArea class activates cells for keyboard events for free in its own GtkCellArea->activate() implementation.
Adds renderer to area with the default child cell properties.
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.
Applies any connected attributes to the renderers in area by pulling the values from tree_model.
Connects an attribute to apply values from column for the #GtkTreeModel in use.
Disconnects attribute for the renderer in area so that attribute will no longer be updated with values from the model.
Returns the model column that an attribute has been mapped to, or -1 if the attribute is not mapped.
Gets the value of a cell property for renderer in area.
Sets a cell property for renderer in area.
Connect to AddEditable signal.
Connect to ApplyAttributes signal.
Connect to FocusChanged signal.
Connect to RemoveEditable signal.
This is sometimes needed for cases where rows need to share alignments in one orientation but may be separately grouped in the opposing orientation.
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).
Delegates event handling to a #GtkCellArea.
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.
Calls callback for every #GtkCellRenderer in area with the allocated rectangle inside cell_area.
Calls callback for every #GtkCellRenderer in area.
Derives the allocation of renderer inside area if area were to be renderered in cell_area.
Gets the #GtkCellRenderer at x and y coordinates inside area and optionally returns the full cell allocation for it inside cell_area.
Gets the current #GtkTreePath string for the currently applied #GtkTreeIter, this is implicitly updated when gtk.cell_area.CellArea.applyAttributes is called and can be used to interact with renderers from #GtkCellArea subclasses.
Gets the #GtkCellEditable widget currently used to edit the currently edited cell.
Gets the #GtkCellRenderer in area that is currently being edited.
Retrieves the currently focused cell for area
Gets the #GtkCellRenderer which is expected to be focusable for which renderer is, or may be a sibling.
Gets the focus sibling cell renderers for renderer.
Retrieves a cell area’s initial minimum and natural height.
Retrieves a cell area’s minimum and natural height if it would be given the specified width.
Retrieves a cell area’s initial minimum and natural width.
Retrieves a cell area’s minimum and natural width if it would be given the specified height.
Gets whether the area prefers a height-for-width layout or a width-for-height layout.
Checks if area contains renderer.
This is a convenience function for #GtkCellArea implementations to get the inner area where a given #GtkCellRenderer will be rendered. It removes any padding previously added by gtk.cell_area.CellArea.requestRenderer.
Returns whether the area can do anything when activated, after applying new attributes to area.
Returns whether sibling is one of renderer’s focus siblings (see gtk.cell_area.CellArea.addFocusSibling).
Removes renderer from area.
Removes sibling from renderer’s focus sibling list (see gtk.cell_area.CellArea.addFocusSibling).
Renders area’s cells according to area’s layout onto widget at the given coordinates.
This is a convenience function for #GtkCellArea implementations to request size for cell renderers. It’s important to use this function to request size and then use gtk.cell_area.CellArea.innerCellArea at render and event time since this function will add padding around the cell for focus painting.
Returns this, for use in with statements.
Explicitly sets the currently focused cell to renderer.
Explicitly stops the editing of the currently edited cell.
Get editWidget property.
Get editedCell property.
Get focusCell property.
Set focusCell property.
Get builder for gtk.cell_area.CellArea
Adds a child to buildable. type is an optional string describing how the child should be added.
Constructs a child of buildable with the name name.
This is similar to gtk.buildable.Buildable.parserFinished but is called once for each custom tag handled by the buildable.
This is called for each unknown element under <child>.
Get the internal child called childname of the buildable object.
Gets the name of the buildable object.
Called when the builder finishes the parsing of a [GtkBuilder UI definition][BUILDER-UI]. Note that this will be called once for each time gtk.builder.Builder.addFromFile or gtk.builder.Builder.addFromString is called on a builder.
Sets the property name name to value on the buildable object.
Sets the name of the buildable object.
Adds an attribute mapping to the list in cell_layout.
Unsets all the mappings on all renderers on cell_layout and removes all renderers from cell_layout.
Clears all existing attributes previously set with gtk.cell_layout.CellLayout.setAttributes.
Returns the underlying #GtkCellArea which might be cell_layout if called on a #GtkCellArea or might be null if no #GtkCellArea is used by cell_layout.
Returns the cell renderers which have been added to cell_layout.
Adds the cell to the end of cell_layout. If expand is false, then the cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which expand is true.
Packs the cell into the beginning of cell_layout. If expand is false, then the cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which expand is true.
Re-inserts cell at position.
Sets the #GtkCellLayoutDataFunc to use for cell_layout.
Returns this, for use in with statements.
Get builder for gobject.initially_unowned.InitiallyUnowned
Adds a child to buildable. type is an optional string describing how the child should be added.
Constructs a child of buildable with the name name.
This is similar to gtk.buildable.Buildable.parserFinished but is called once for each custom tag handled by the buildable.
This is called for each unknown element under <child>.
Get the internal child called childname of the buildable object.
Gets the name of the buildable object.
Called when the builder finishes the parsing of a [GtkBuilder UI definition][BUILDER-UI]. Note that this will be called once for each time gtk.builder.Builder.addFromFile or gtk.builder.Builder.addFromString is called on a builder.
Sets the property name name to value on the buildable object.
Sets the name of the buildable object.
Adds an attribute mapping to the list in cell_layout.
Unsets all the mappings on all renderers on cell_layout and removes all renderers from cell_layout.
Clears all existing attributes previously set with gtk.cell_layout.CellLayout.setAttributes.
Returns the underlying #GtkCellArea which might be cell_layout if called on a #GtkCellArea or might be null if no #GtkCellArea is used by cell_layout.
Returns the cell renderers which have been added to cell_layout.
Adds the cell to the end of cell_layout. If expand is false, then the cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which expand is true.
Packs the cell into the beginning of cell_layout. If expand is false, then the cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which expand is true.
Re-inserts cell at position.
Sets the #GtkCellLayoutDataFunc to use for cell_layout.
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][geometry-management], 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.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 #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:
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’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 glib.global.timeoutAdd) 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:
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 #GtkWidget::size-allocate time using gtk.global.distributeNaturalAllocation.
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 #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 #GtkCellArea::focus-changed signal to fire; as well as #GtkCellArea::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 #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.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 #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.
Cell Properties
The #GtkCellArea introduces cell properties for #GtkCellRenderers in very much the same way that #GtkContainer introduces [child properties][child-properties] for #GtkWidgets. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a #GtkCellAreaBox 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 #GtkCellAreaContext.
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.