Requesting area sizes

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

1
2
3
4
5
6
7
8
9
10
11
12
13

CtkTreeIter iter;
gint        minimum_width;
gint        natural_width;

valid = ctk_tree_model_get_iter_first (model, &iter);
while (valid)
  {
    ctk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE);
    ctk_cell_area_get_preferred_width (area, context, widget, NULL, NULL);

    valid = ctk_tree_model_iter_next (model, &iter);
  }
ctk_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 CtkCellAreaContext object and can be consulted at any time.

This can be useful since CtkCellLayout widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The CtkCellLayout 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 CtkWidgetClass.get_preferred_width() it can simply consult the width accumulated so far in the CtkCellAreaContext 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:

1
2
3
4
5
6
7
8
9
10
11
12

static void
foo_get_preferred_width (CtkWidget       *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);

  ctk_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 CtkCellAreaContext.

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

CtkTreeIter iter;
gint        minimum_height;
gint        natural_height;
gint        full_minimum_height = 0;
gint        full_natural_height = 0;

valid = ctk_tree_model_get_iter_first (model, &iter);
while (valid)
  {
    ctk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE);
    ctk_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 = ctk_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 CtkWidgetClass.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 CtkWidgetClass.draw() time.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

CtkAllocation allocation;
CdkRectangle  cell_area = { 0, };
CtkTreeIter   iter;
gint          minimum_width;
gint          natural_width;

ctk_widget_get_allocation (widget, &allocation);
cell_area.width = allocation.width;

valid = ctk_tree_model_get_iter_first (model, &iter);
while (valid)
  {
    cell_area.height = get_cached_height_for_row (&iter);

    ctk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE);
    ctk_cell_area_render (area, context, widget, cr,
                          &cell_area, &cell_area, state_flags, FALSE);

    cell_area.y += cell_area.height;

    valid = ctk_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 ctk_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 ctk_cell_area_event() API as they come in. Usually CtkCellArea 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 ctk_cell_area_stop_editing() at any time to cancel any cell editing that is currently in progress.

The CtkCellArea drives keyboard focus from cell to cell in a way similar to CtkWidget. For layouting widgets that support giving focus to cells it’s important to remember to pass CTK_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 CtkWidgetClass.focus() virtual method. The layouting widget is always responsible for knowing where CtkTreeModel rows are rendered inside the widget, so at CtkWidgetClass.focus() time the layouting widget should use the CtkCellArea methods to navigate focus inside the area and then observe the CtkDirectionType to pass the focus to adjacent rows and areas.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

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

  focus_row = priv->focus_row;

  if (!ctk_widget_has_focus (widget))
    ctk_widget_grab_focus (widget);

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

      if (ctk_cell_area_focus (priv->area, direction))
        {
           priv->focus_row = focus_row;
           have_focus = TRUE;
           break;
        }
      else
        {
          if (direction == CTK_DIR_RIGHT ||
              direction == CTK_DIR_LEFT)
            break;
          else if (direction == CTK_DIR_UP ||
                   direction == CTK_DIR_TAB_BACKWARD)
           {
              if (focus_row == 0)
                break;
              else
               {
                  focus_row--;
                  valid = ctk_tree_model_iter_nth_child (priv->model, &iter, NULL, focus_row);
               }
            }
          else
            {
              if (focus_row == last_row)
                break;
              else
                {
                  focus_row++;
                  valid = ctk_tree_model_iter_next (priv->model, &iter);
                }
            }
        }
    }
    return have_focus;
}

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

Cell Properties

The CtkCellArea introduces cell properties for CtkCellRenderers in very much the same way that CtkContainer introduces child properties for CtkWidgets. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a CtkCellAreaBox 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 CtkCellAreaContext.

Use ctk_cell_area_class_install_cell_property() to install cell properties for a cell area class and ctk_cell_area_class_find_cell_property() or ctk_cell_area_class_list_cell_properties() to get information about existing cell properties.

To set the value of a cell property, use ctk_cell_area_cell_set_property(), ctk_cell_area_cell_set() or ctk_cell_area_cell_set_valist(). To obtain the value of a cell property, use ctk_cell_area_cell_get_property(), ctk_cell_area_cell_get() or ctk_cell_area_cell_get_valist().

CtkCellCallback ()

gboolean
(*CtkCellCallback) (CtkCellRenderer *renderer,
                    gpointer data);

The type of the callback functions used for iterating over the cell renderers of a CtkCellArea, see ctk_cell_area_foreach().

CtkCellAllocCallback ()

gboolean
(*CtkCellAllocCallback) (CtkCellRenderer *renderer,
                         const CdkRectangle *cell_area,
                         const CdkRectangle *cell_background,
                         gpointer data);

The type of the callback functions used for iterating over the cell renderers and their allocated areas inside a CtkCellArea, see ctk_cell_area_foreach_alloc().

CTK_CELL_AREA_WARN_INVALID_CELL_PROPERTY_ID()

#define             CTK_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.

ctk_cell_area_add ()

void
ctk_cell_area_add (CtkCellArea *area,
                   CtkCellRenderer *renderer);

Adds renderer to area with the default child cell properties.

Since: 3.0

ctk_cell_area_remove ()

void
ctk_cell_area_remove (CtkCellArea *area,
                      CtkCellRenderer *renderer);

Removes renderer from area .

Since: 3.0

ctk_cell_area_has_renderer ()

gboolean
ctk_cell_area_has_renderer (CtkCellArea *area,
                            CtkCellRenderer *renderer);

Checks if area contains renderer .

Since: 3.0

ctk_cell_area_foreach ()

void
ctk_cell_area_foreach (CtkCellArea *area,
                       CtkCellCallback callback,
                       gpointer callback_data);

Calls callback for every CtkCellRenderer in area .

Since: 3.0

ctk_cell_area_foreach_alloc ()

void
ctk_cell_area_foreach_alloc (CtkCellArea *area,
                             CtkCellAreaContext *context,
                             CtkWidget *widget,
                             const CdkRectangle *cell_area,
                             const CdkRectangle *background_area,
                             CtkCellAllocCallback callback,
                             gpointer callback_data);

Calls callback for every CtkCellRenderer in area with the allocated rectangle inside cell_area .

Since: 3.0

ctk_cell_area_event ()

gint
ctk_cell_area_event (CtkCellArea *area,
                     CtkCellAreaContext *context,
                     CtkWidget *widget,
                     CdkEvent *event,
                     const CdkRectangle *cell_area,
                     CtkCellRendererState flags);

Delegates event handling to a CtkCellArea.

Since: 3.0

ctk_cell_area_render ()

void
ctk_cell_area_render (CtkCellArea *area,
                      CtkCellAreaContext *context,
                      CtkWidget *widget,
                      cairo_t *cr,
                      const CdkRectangle *background_area,
                      const CdkRectangle *cell_area,
                      CtkCellRendererState flags,
                      gboolean paint_focus);

Renders area ’s cells according to area ’s layout onto widget at the given coordinates.

Since: 3.0

ctk_cell_area_get_cell_allocation ()

void
ctk_cell_area_get_cell_allocation (CtkCellArea *area,
                                   CtkCellAreaContext *context,
                                   CtkWidget *widget,
                                   CtkCellRenderer *renderer,
                                   const CdkRectangle *cell_area,
                                   CdkRectangle *allocation);

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

Since: 3.0

ctk_cell_area_get_cell_at_position ()

CtkCellRenderer *
ctk_cell_area_get_cell_at_position (CtkCellArea *area,
                                    CtkCellAreaContext *context,
                                    CtkWidget *widget,
                                    const CdkRectangle *cell_area,
                                    gint x,
                                    gint y,
                                    CdkRectangle *alloc_area);

Gets the CtkCellRenderer at x and y coordinates inside area and optionally returns the full cell allocation for it inside cell_area .

Since: 3.0

ctk_cell_area_create_context ()

CtkCellAreaContext *
ctk_cell_area_create_context (CtkCellArea *area);

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

Since: 3.0

ctk_cell_area_copy_context ()

CtkCellAreaContext *
ctk_cell_area_copy_context (CtkCellArea *area,
                            CtkCellAreaContext *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, CtkIconView 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. CtkIconView 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

ctk_cell_area_get_request_mode ()

CtkSizeRequestMode
ctk_cell_area_get_request_mode (CtkCellArea *area);

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

Since: 3.0

ctk_cell_area_get_preferred_width ()

void
ctk_cell_area_get_preferred_width (CtkCellArea *area,
                                   CtkCellAreaContext *context,
                                   CtkWidget *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 ctk_cell_area_context_get_preferred_width() after a series of requests.

Since: 3.0

ctk_cell_area_get_preferred_height_for_width ()

void
ctk_cell_area_get_preferred_height_for_width
                               (CtkCellArea *area,
                                CtkCellAreaContext *context,
                                CtkWidget *widget,
                                gint width,
                                gint *minimum_height,
                                gint *natural_height);

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

Since: 3.0

ctk_cell_area_get_preferred_height ()

void
ctk_cell_area_get_preferred_height (CtkCellArea *area,
                                    CtkCellAreaContext *context,
                                    CtkWidget *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 ctk_cell_area_context_get_preferred_height() after a series of requests.

Since: 3.0

ctk_cell_area_get_preferred_width_for_height ()

void
ctk_cell_area_get_preferred_width_for_height
                               (CtkCellArea *area,
                                CtkCellAreaContext *context,
                                CtkWidget *widget,
                                gint height,
                                gint *minimum_width,
                                gint *natural_width);

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

Since: 3.0

ctk_cell_area_get_current_path_string ()

const gchar *
ctk_cell_area_get_current_path_string (CtkCellArea *area);

Gets the current CtkTreePath string for the currently applied CtkTreeIter, this is implicitly updated when ctk_cell_area_apply_attributes() is called and can be used to interact with renderers from CtkCellArea subclasses.

Since: 3.0

ctk_cell_area_apply_attributes ()

void
ctk_cell_area_apply_attributes (CtkCellArea *area,
                                CtkTreeModel *tree_model,
                                CtkTreeIter *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

ctk_cell_area_attribute_connect ()

void
ctk_cell_area_attribute_connect (CtkCellArea *area,
                                 CtkCellRenderer *renderer,
                                 const gchar *attribute,
                                 gint column);

Connects an attribute to apply values from column for the CtkTreeModel in use.

Since: 3.0

ctk_cell_area_attribute_disconnect ()

void
ctk_cell_area_attribute_disconnect (CtkCellArea *area,
                                    CtkCellRenderer *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

ctk_cell_area_attribute_get_column ()

gint
ctk_cell_area_attribute_get_column (CtkCellArea *area,
                                    CtkCellRenderer *renderer,
                                    const gchar *attribute);

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

Since: 3.14

ctk_cell_area_class_install_cell_property ()

void
ctk_cell_area_class_install_cell_property
                               (CtkCellAreaClass *aclass,
                                guint property_id,
                                GParamSpec *pspec);

Installs a cell property on a cell area class.

Since: 3.0

ctk_cell_area_class_find_cell_property ()

GParamSpec *
ctk_cell_area_class_find_cell_property
                               (CtkCellAreaClass *aclass,
                                const gchar *property_name);

Finds a cell property of a cell area class by name.

Since: 3.0

ctk_cell_area_class_list_cell_properties ()

GParamSpec **
ctk_cell_area_class_list_cell_properties
                               (CtkCellAreaClass *aclass,
                                guint *n_properties);

Returns all cell properties of a cell area class.

Since: 3.0

ctk_cell_area_add_with_properties ()

void
ctk_cell_area_add_with_properties (CtkCellArea *area,
                                   CtkCellRenderer *renderer,
                                   const gchar *first_prop_name,
                                   ...);

Adds renderer to area , setting cell properties at the same time. See ctk_cell_area_add() and ctk_cell_area_cell_set() for more details.

Since: 3.0

ctk_cell_area_cell_set ()

void
ctk_cell_area_cell_set (CtkCellArea *area,
                        CtkCellRenderer *renderer,
                        const gchar *first_prop_name,
                        ...);

Sets one or more cell properties for cell in area .

Since: 3.0

ctk_cell_area_cell_get ()

void
ctk_cell_area_cell_get (CtkCellArea *area,
                        CtkCellRenderer *renderer,
                        const gchar *first_prop_name,
                        ...);

Gets the values of one or more cell properties for renderer in area .

Since: 3.0

ctk_cell_area_cell_set_valist ()

void
ctk_cell_area_cell_set_valist (CtkCellArea *area,
                               CtkCellRenderer *renderer,
                               const gchar *first_property_name,
                               va_list var_args);

Sets one or more cell properties for renderer in area .

Since: 3.0

ctk_cell_area_cell_get_valist ()

void
ctk_cell_area_cell_get_valist (CtkCellArea *area,
                               CtkCellRenderer *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

ctk_cell_area_cell_set_property ()

void
ctk_cell_area_cell_set_property (CtkCellArea *area,
                                 CtkCellRenderer *renderer,
                                 const gchar *property_name,
                                 const GValue *value);

Sets a cell property for renderer in area .

Since: 3.0

ctk_cell_area_cell_get_property ()

void
ctk_cell_area_cell_get_property (CtkCellArea *area,
                                 CtkCellRenderer *renderer,
                                 const gchar *property_name,
                                 GValue *value);

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

Since: 3.0

ctk_cell_area_is_activatable ()

gboolean
ctk_cell_area_is_activatable (CtkCellArea *area);

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

Since: 3.0

ctk_cell_area_activate ()

gboolean
ctk_cell_area_activate (CtkCellArea *area,
                        CtkCellAreaContext *context,
                        CtkWidget *widget,
                        const CdkRectangle *cell_area,
                        CtkCellRendererState 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.

Since: 3.0

ctk_cell_area_focus ()

gboolean
ctk_cell_area_focus (CtkCellArea *area,
                     CtkDirectionType 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 CtkCellArea classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells.

Since: 3.0

ctk_cell_area_set_focus_cell ()

void
ctk_cell_area_set_focus_cell (CtkCellArea *area,
                              CtkCellRenderer *renderer);

Explicitly sets the currently focused cell to renderer .

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

Since: 3.0

ctk_cell_area_get_focus_cell ()

CtkCellRenderer *
ctk_cell_area_get_focus_cell (CtkCellArea *area);

Retrieves the currently focused cell for area

Since: 3.0

ctk_cell_area_add_focus_sibling ()

void
ctk_cell_area_add_focus_sibling (CtkCellArea *area,
                                 CtkCellRenderer *renderer,
                                 CtkCellRenderer *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

ctk_cell_area_remove_focus_sibling ()

void
ctk_cell_area_remove_focus_sibling (CtkCellArea *area,
                                    CtkCellRenderer *renderer,
                                    CtkCellRenderer *sibling);

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

Since: 3.0

ctk_cell_area_is_focus_sibling ()

gboolean
ctk_cell_area_is_focus_sibling (CtkCellArea *area,
                                CtkCellRenderer *renderer,
                                CtkCellRenderer *sibling);

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

Since: 3.0

ctk_cell_area_get_focus_siblings ()

const GList *
ctk_cell_area_get_focus_siblings (CtkCellArea *area,
                                  CtkCellRenderer *renderer);

Gets the focus sibling cell renderers for renderer .

Since: 3.0

ctk_cell_area_get_focus_from_sibling ()

CtkCellRenderer *
ctk_cell_area_get_focus_from_sibling (CtkCellArea *area,
                                      CtkCellRenderer *renderer);

Gets the CtkCellRenderer which is expected to be focusable for which renderer is, or may be a sibling.

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

Since: 3.0

ctk_cell_area_get_edited_cell ()

CtkCellRenderer *
ctk_cell_area_get_edited_cell (CtkCellArea *area);

Gets the CtkCellRenderer in area that is currently being edited.

Since: 3.0

ctk_cell_area_get_edit_widget ()

CtkCellEditable *
ctk_cell_area_get_edit_widget (CtkCellArea *area);

Gets the CtkCellEditable widget currently used to edit the currently edited cell.

Since: 3.0

ctk_cell_area_activate_cell ()

gboolean
ctk_cell_area_activate_cell (CtkCellArea *area,
                             CtkWidget *widget,
                             CtkCellRenderer *renderer,
                             CdkEvent *event,
                             const CdkRectangle *cell_area,
                             CtkCellRendererState flags);

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

Since: 3.0

ctk_cell_area_stop_editing ()

void
ctk_cell_area_stop_editing (CtkCellArea *area,
                            gboolean canceled);

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 ctk_cell_area_get_edited_cell() and ctk_cell_area_get_edit_widget().

Since: 3.0

ctk_cell_area_inner_cell_area ()

void
ctk_cell_area_inner_cell_area (CtkCellArea *area,
                               CtkWidget *widget,
                               const CdkRectangle *cell_area,
                               CdkRectangle *inner_area);

This is a convenience function for CtkCellArea implementations to get the inner area where a given CtkCellRenderer will be rendered. It removes any padding previously added by ctk_cell_area_request_renderer().

Since: 3.0

ctk_cell_area_request_renderer ()

void
ctk_cell_area_request_renderer (CtkCellArea *area,
                                CtkCellRenderer *renderer,
                                CtkOrientation orientation,
                                CtkWidget *widget,
                                gint for_size,
                                gint *minimum_size,
                                gint *natural_size);

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

Since: 3.0

struct CtkCellArea

struct CtkCellArea;

struct CtkCellAreaClass

struct CtkCellAreaClass {
  /* Basic methods */
  void               (* add)                             (CtkCellArea             *area,
                                                          CtkCellRenderer         *renderer);
  void               (* remove)                          (CtkCellArea             *area,
                                                          CtkCellRenderer         *renderer);
  void               (* foreach)                         (CtkCellArea             *area,
                                                          CtkCellCallback          callback,
                                                          gpointer                 callback_data);
  void               (* foreach_alloc)                   (CtkCellArea             *area,
                                                          CtkCellAreaContext      *context,
                                                          CtkWidget               *widget,
                                                          const CdkRectangle      *cell_area,
                                                          const CdkRectangle      *background_area,
                                                          CtkCellAllocCallback     callback,
                                                          gpointer                 callback_data);
  gint               (* event)                           (CtkCellArea             *area,
                                                          CtkCellAreaContext      *context,
                                                          CtkWidget               *widget,
                                                          CdkEvent                *event,
                                                          const CdkRectangle      *cell_area,
                                                          CtkCellRendererState     flags);
  void               (* render)                          (CtkCellArea             *area,
                                                          CtkCellAreaContext      *context,
                                                          CtkWidget               *widget,
                                                          cairo_t                 *cr,
                                                          const CdkRectangle      *background_area,
                                                          const CdkRectangle      *cell_area,
                                                          CtkCellRendererState     flags,
                                                          gboolean                 paint_focus);
  void               (* apply_attributes)                (CtkCellArea             *area,
                                                          CtkTreeModel            *tree_model,
                                                          CtkTreeIter             *iter,
                                                          gboolean                 is_expander,
                                                          gboolean                 is_expanded);

  /* Geometry */
  CtkCellAreaContext *(* create_context)                 (CtkCellArea             *area);
  CtkCellAreaContext *(* copy_context)                   (CtkCellArea             *area,
                                                          CtkCellAreaContext      *context);
  CtkSizeRequestMode (* get_request_mode)                (CtkCellArea             *area);
  void               (* get_preferred_width)             (CtkCellArea             *area,
                                                          CtkCellAreaContext      *context,
                                                          CtkWidget               *widget,
                                                          gint                    *minimum_width,
                                                          gint                    *natural_width);
  void               (* get_preferred_height_for_width)  (CtkCellArea             *area,
                                                          CtkCellAreaContext      *context,
                                                          CtkWidget               *widget,
                                                          gint                     width,
                                                          gint                    *minimum_height,
                                                          gint                    *natural_height);
  void               (* get_preferred_height)            (CtkCellArea             *area,
                                                          CtkCellAreaContext      *context,
                                                          CtkWidget               *widget,
                                                          gint                    *minimum_height,
                                                          gint                    *natural_height);
  void               (* get_preferred_width_for_height)  (CtkCellArea             *area,
                                                          CtkCellAreaContext      *context,
                                                          CtkWidget               *widget,
                                                          gint                     height,
                                                          gint                    *minimum_width,
                                                          gint                    *natural_width);

  /* Cell Properties */
  void               (* set_cell_property)               (CtkCellArea             *area,
                                                          CtkCellRenderer         *renderer,
                                                          guint                    property_id,
                                                          const GValue            *value,
                                                          GParamSpec              *pspec);
  void               (* get_cell_property)               (CtkCellArea             *area,
                                                          CtkCellRenderer         *renderer,
                                                          guint                    property_id,
                                                          GValue                  *value,
                                                          GParamSpec              *pspec);

  /* Focus */
  gboolean           (* focus)                           (CtkCellArea             *area,
                                                          CtkDirectionType         direction);
  gboolean           (* is_activatable)                  (CtkCellArea             *area);
  gboolean           (* activate)                        (CtkCellArea             *area,
                                                          CtkCellAreaContext      *context,
                                                          CtkWidget               *widget,
                                                          const CdkRectangle      *cell_area,
                                                          CtkCellRendererState     flags,
                                                          gboolean                 edit_only);
};

The “edit-widget” property

  “edit-widget”              CtkCellEditable *

The widget currently editing the edited cell

This property is read-only and only changes as a result of a call ctk_cell_area_activate_cell().

Owner: CtkCellArea

Flags: Read

Since: 3.0

The “edited-cell” property

  “edited-cell”              CtkCellRenderer *

The cell in the area that is currently edited

This property is read-only and only changes as a result of a call ctk_cell_area_activate_cell().

Owner: CtkCellArea

Flags: Read

Since: 3.0

The “focus-cell” property

  “focus-cell”               CtkCellRenderer *

The cell in the area that currently has focus

Owner: CtkCellArea

Flags: Read / Write

Since: 3.0

The “add-editable” signal

void
user_function (CtkCellArea     *area,
               CtkCellRenderer *renderer,
               CtkCellEditable *editable,
               CdkRectangle    *cell_area,
               char            *path,
               gpointer         user_data)

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

Flags: Run First

Since: 3.0

The “apply-attributes” signal

void
user_function (CtkCellArea  *area,
               CtkTreeModel *model,
               CtkTreeIter  *iter,
               gboolean      is_expander,
               gboolean      is_expanded,
               gpointer      user_data)

This signal is emitted whenever applying attributes to area from model

Flags: Run First

Since: 3.0

The “focus-changed” signal

void
user_function (CtkCellArea     *area,
               CtkCellRenderer *renderer,
               char            *path,
               gpointer         user_data)

Indicates that focus changed on this area . This signal is emitted either as a result of focus handling or event handling.

It's 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.

Flags: Run First

Since: 3.0

The “remove-editable” signal

void
user_function (CtkCellArea     *area,
               CtkCellRenderer *renderer,
               CtkCellEditable *editable,
               gpointer         user_data)

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

Flags: Run First

Since: 3.0