Gjsify LogoGjsify Logo

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_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:

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 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:

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

foo_ensure_at_least_one_handfull_of_rows_have_been_requested (foo);

gtk_cell_area_context_get_preferred_width (priv->context, minimum_size, natural_size);
}

In the above example the Foo widget has to make sure that some row sizes have been calculated (the amount of rows that Foo judged was appropriate to request space for in a single timeout iteration) before simply returning the amount of space required by the area via the #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:

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

valid = gtk_tree_model_get_iter_first (model, &iter);
while (valid)
{
gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE);
gtk_cell_area_get_preferred_height_for_width (area, context, widget,
width, &minimum_height, &natural_height);

if (width_is_for_allocation)
cache_row_height (&iter, minimum_height, natural_height);

full_minimum_height += minimum_height;
full_natural_height += natural_height;

valid = gtk_tree_model_iter_next (model, &iter);
}

Note that in the above example we would need to cache the heights returned for each row so that we would know what sizes to render the areas for each row. However we would only want to really cache the heights if the request is intended for the layouting widgets real allocation.

In some cases the layouting widget is requested the height for an arbitrary for_width, this is a special case for layouting widgets who need to request size for tens of thousands of rows. For this case it’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_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 #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_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:

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

focus_row = priv->focus_row;

if (!gtk_widget_has_focus (widget))
gtk_widget_grab_focus (widget);

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

if (gtk_cell_area_focus (priv->area, direction))
{
priv->focus_row = focus_row;
have_focus = TRUE;
break;
}
else
{
if (direction == GTK_DIR_RIGHT ||
direction == GTK_DIR_LEFT)
break;
else if (direction == GTK_DIR_UP ||
direction == GTK_DIR_TAB_BACKWARD)
{
if (focus_row == 0)
break;
else
{
focus_row--;
valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, focus_row);
}
}
else
{
if (focus_row == last_row)
break;
else
{
focus_row++;
valid = gtk_tree_model_iter_next (priv->model, &iter);
}
}
}
}
return have_focus;
}

Note that the layouting widget is responsible for matching the 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_install_cell_property() to install cell properties for a cell area class and gtk_cell_area_class_find_cell_property() or gtk_cell_area_class_list_cell_properties() to get information about existing cell properties.

To set the value of a cell property, use gtk_cell_area_cell_set_property(), gtk_cell_area_cell_set() or gtk_cell_area_cell_set_valist(). To obtain the value of a cell property, use gtk_cell_area_cell_get_property(), gtk_cell_area_cell_get() or gtk_cell_area_cell_get_valist().

Hierarchy

Index

Constructors

Properties

Methods

Constructors

Properties

edit_widget: Gtk.CellEditable

The widget currently editing the edited cell

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

edited_cell: Gtk.CellRenderer

The cell in the area that is currently edited

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

focus_cell: Gtk.CellRenderer

The cell in the area that currently has focus

g_type_instance: TypeInstance
$gtype: GType<Gtk.CellArea>
name: string

Methods

  • 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.

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext in context with the current row data

    • widget: Gtk.Widget

      the #GtkWidget that area is rendering on

    • cell_area: Gdk.Rectangle

      the size and location of area relative to widget’s allocation

    • flags: Gtk.CellRendererState

      the #GtkCellRendererState flags for area for this row of data.

    • edit_only: boolean

      if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated.

    Returns boolean

  • 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.

    Parameters

    • widget: Gtk.Widget

      the #GtkWidget that area is rendering onto

    • renderer: Gtk.CellRenderer

      the #GtkCellRenderer in area to activate

    • event: Gdk.Event

      the #GdkEvent for which cell activation should occur

    • cell_area: Gdk.Rectangle

      the #GdkRectangle in widget relative coordinates of renderer for the current row.

    • flags: Gtk.CellRendererState

      the #GtkCellRendererState for renderer

    Returns boolean

  • add_attribute(cell: Gtk.CellRenderer, attribute: string, column: number): void
  • Adds an attribute mapping to the list in cell_layout.

    The column is the column of the model to get a value from, and the attribute is the parameter on cell to be set from the value. So for example if column 2 of the model contains strings, you could have the “text” attribute of a #GtkCellRendererText get its values from column 2.

    Parameters

    • cell: Gtk.CellRenderer

      a #GtkCellRenderer

    • attribute: string

      an attribute on the renderer

    • column: number

      the column position on the model to get the attribute from

    Returns void

  • 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.

    Parameters

    • renderer: Gtk.CellRenderer

      the #GtkCellRenderer expected to have focus

    • sibling: Gtk.CellRenderer

      the #GtkCellRenderer to add to renderer’s focus area

    Returns void

  • Applies any connected attributes to the renderers in area by pulling the values from tree_model.

    Parameters

    • tree_model: Gtk.TreeModel

      the #GtkTreeModel to pull values from

    • iter: Gtk.TreeIter

      the #GtkTreeIter in tree_model to apply values for

    • is_expander: boolean

      whether iter has children

    • is_expanded: boolean

      whether iter is expanded in the view and children are visible

    Returns void

  • attribute_connect(renderer: Gtk.CellRenderer, attribute: string, column: number): void
  • Connects an attribute to apply values from column for the #GtkTreeModel in use.

    Parameters

    • renderer: Gtk.CellRenderer

      the #GtkCellRenderer to connect an attribute for

    • attribute: string

      the attribute name

    • column: number

      the #GtkTreeModel column to fetch attribute values from

    Returns void

  • Disconnects attribute for the renderer in area so that attribute will no longer be updated with values from the model.

    Parameters

    • renderer: Gtk.CellRenderer

      the #GtkCellRenderer to disconnect an attribute for

    • attribute: string

      the attribute name

    Returns void

  • attribute_get_column(renderer: Gtk.CellRenderer, attribute: string): number
  • Returns the model column that an attribute has been mapped to, or -1 if the attribute is not mapped.

    Parameters

    • renderer: Gtk.CellRenderer

      a #GtkCellRenderer

    • attribute: string

      an attribute on the renderer

    Returns number

  • Creates a binding between source_property on source and target_property on target.

    Whenever the source_property is changed the target_property is updated using the same value. For instance:

      g_object_bind_property (action, "active", widget, "sensitive", 0);
    

    Will result in the "sensitive" property of the widget #GObject instance to be updated with the same value of the "active" property of the action #GObject instance.

    If flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: if target_property on target changes then the source_property on source will be updated as well.

    The binding will automatically be removed when either the source or the target instances are finalized. To remove the binding without affecting the source and the target you can just call g_object_unref() on the returned #GBinding instance.

    Removing the binding by calling g_object_unref() on it must only be done if the binding, source and target are only used from a single thread and it is clear that both source and target outlive the binding. Especially it is not safe to rely on this if the binding, source or target can be finalized from different threads. Keep another reference to the binding and use g_binding_unbind() instead to be on the safe side.

    A #GObject can have multiple bindings.

    Parameters

    • source_property: string

      the property on source to bind

    • target: GObject.Object

      the target #GObject

    • target_property: string

      the property on target to bind

    • flags: BindingFlags

      flags to pass to #GBinding

    Returns Binding

  • Creates a binding between source_property on source and target_property on target, allowing you to set the transformation functions to be used by the binding.

    This function is the language bindings friendly version of g_object_bind_property_full(), using #GClosures instead of function pointers.

    Parameters

    • source_property: string

      the property on source to bind

    • target: GObject.Object

      the target #GObject

    • target_property: string

      the property on target to bind

    • flags: BindingFlags

      flags to pass to #GBinding

    • transform_to: TClosure<any, any>

      a #GClosure wrapping the transformation function from the source to the target, or %NULL to use the default

    • transform_from: TClosure<any, any>

      a #GClosure wrapping the transformation function from the target to the source, or %NULL to use the default

    Returns Binding

  • cell_get_property(renderer: Gtk.CellRenderer, property_name: string, value: any): void
  • Gets the value of a cell property for renderer in area.

    Parameters

    • renderer: Gtk.CellRenderer

      a #GtkCellRenderer inside area

    • property_name: string

      the name of the property to get

    • value: any

      a location to return the value

    Returns void

  • cell_set_property(renderer: Gtk.CellRenderer, property_name: string, value: any): void
  • Sets a cell property for renderer in area.

    Parameters

    • renderer: Gtk.CellRenderer

      a #GtkCellRenderer inside area

    • property_name: string

      the name of the cell property to set

    • value: any

      the value to set the cell property to

    Returns void

  • clear(): void
  • 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.

    Parameters

    Returns Gtk.CellAreaContext

  • 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).

    Returns Gtk.CellAreaContext

  • This is similar to gtk_buildable_parser_finished() but is called once for each custom tag handled by the buildable.

    Parameters

    • builder: Gtk.Builder

      a #GtkBuilder

    • child: GObject.Object

      child object or %NULL for non-child tags

    • tagname: string

      the name of the tag

    • data: object

      user data created in custom_tag_start

    Returns void

  • This is called at the end of each custom element handled by the buildable.

    Parameters

    • builder: Gtk.Builder

      #GtkBuilder used to construct this object

    • child: GObject.Object

      child object or %NULL for non-child tags

    • tagname: string

      name of tag

    • data: object

      user data that will be passed in to parser functions

    Returns void

  • disconnect(id: number): void
  • emit(sigName: "add-editable", renderer: Gtk.CellRenderer, editable: Gtk.CellEditable, cell_area: Gdk.Rectangle, path: string, ...args: any[]): void
  • emit(sigName: "apply-attributes", model: Gtk.TreeModel, iter: Gtk.TreeIter, is_expander: boolean, is_expanded: boolean, ...args: any[]): void
  • emit(sigName: "focus-changed", renderer: Gtk.CellRenderer, path: string, ...args: any[]): void
  • emit(sigName: "remove-editable", renderer: Gtk.CellRenderer, editable: Gtk.CellEditable, ...args: any[]): void
  • emit(sigName: "notify::edit-widget", ...args: any[]): void
  • emit(sigName: "notify::edited-cell", ...args: any[]): void
  • emit(sigName: "notify::focus-cell", ...args: any[]): void
  • emit(sigName: string, ...args: any[]): void
  • 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.

    Parameters

    Returns boolean

  • force_floating(): void
  • This function is intended for #GObject implementations to re-enforce a [floating][floating-ref] object reference. Doing this is seldom required: all #GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink().

    Returns void

  • Calls callback for every #GtkCellRenderer in area with the allocated rectangle inside cell_area.

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext for this row of data.

    • widget: Gtk.Widget

      the #GtkWidget that area is rendering to

    • cell_area: Gdk.Rectangle

      the widget relative coordinates and size for area

    • background_area: Gdk.Rectangle

      the widget relative coordinates of the background area

    • callback: Gtk.CellAllocCallback

      the #GtkCellAllocCallback to call

    Returns void

  • freeze_notify(): void
  • Increases the freeze count on object. If the freeze count is non-zero, the emission of "notify" signals on object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one #GObject::notify signal is emitted for each property modified while the object is frozen.

    This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.

    Returns void

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

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext used to hold sizes for area.

    • widget: Gtk.Widget

      the #GtkWidget that area is rendering on

    • cell_area: Gdk.Rectangle

      the whole allocated area for area in widget for this row

    • x: number

      the x position

    • y: number

      the y position

    Returns [Gtk.CellRenderer, Gdk.Rectangle]

  • get_current_path_string(): string
  • 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 string

  • get_data(key?: string): object
  • 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.

    Parameters

    Returns Gtk.CellRenderer

  • get_name(): string
  • Gets the name of the buildable object.

    #GtkBuilder sets the name based on the [GtkBuilder UI definition][BUILDER-UI] used to construct the buildable.

    Returns string

  • 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.

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext to perform this request with

    • widget: Gtk.Widget

      the #GtkWidget where area will be rendering

    Returns [number, number]

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

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext which has already been requested for widths.

    • widget: Gtk.Widget

      the #GtkWidget where area will be rendering

    • width: number

      the width for which to check the height of this area

    Returns [number, number]

  • 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.

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext to perform this request with

    • widget: Gtk.Widget

      the #GtkWidget where area will be rendering

    Returns [number, number]

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

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext which has already been requested for widths.

    • widget: Gtk.Widget

      the #GtkWidget where area will be rendering

    • height: number

      the height for which to check the width of this area

    Returns [number, number]

  • get_property(property_name?: string, value?: any): void
  • Gets a property of an object.

    The value can be:

    • an empty #GValue initialized by %G_VALUE_INIT, which will be automatically initialized with the expected type of the property (since GLib 2.60)
    • a #GValue initialized with the expected type of the property
    • a #GValue initialized with a type to which the expected type of the property can be transformed

    In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling g_value_unset().

    Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming.

    Parameters

    • Optional property_name: string

      the name of the property to get

    • Optional value: any

      return location for the property value

    Returns void

  • get_qdata(quark: number): object
  • getv(names: string[], values: any[]): void
  • Gets n_properties properties for an object. Obtained properties will be set to values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.

    Parameters

    • names: string[]

      the names of each property to get

    • values: any[]

      the values of each property to get

    Returns void

  • 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_request_renderer().

    Parameters

    • widget: Gtk.Widget

      the #GtkWidget that area is rendering onto

    • cell_area: Gdk.Rectangle

      the widget relative coordinates where one of area’s cells is to be placed

    Returns Gdk.Rectangle

  • is_activatable(): boolean
  • Returns whether the area can do anything when activated, after applying new attributes to area.

    Returns boolean

  • is_floating(): boolean
  • Returns whether sibling is one of renderer’s focus siblings (see gtk_cell_area_add_focus_sibling()).

    Parameters

    • renderer: Gtk.CellRenderer

      the #GtkCellRenderer expected to have focus

    • sibling: Gtk.CellRenderer

      the #GtkCellRenderer to check against renderer’s sibling list

    Returns boolean

  • notify(property_name: string): void
  • Emits a "notify" signal for the property property_name on object.

    When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

    Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.

    Parameters

    • property_name: string

      the name of a property installed on the class of object.

    Returns void

  • Emits a "notify" signal for the property specified by pspec on object.

    This function omits the property name lookup, hence it is faster than g_object_notify().

    One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_object_class_install_property() inside a static array, e.g.:

      enum
    {
    PROP_0,
    PROP_FOO,
    PROP_LAST
    };

    static GParamSpec *properties[PROP_LAST];

    static void
    my_object_class_init (MyObjectClass *klass)
    {
    properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
    0, 100,
    50,
    G_PARAM_READWRITE);
    g_object_class_install_property (gobject_class,
    PROP_FOO,
    properties[PROP_FOO]);
    }

    and then notify a change on the "foo" property with:

      g_object_notify_by_pspec (self, properties[PROP_FOO]);
    

    Parameters

    • pspec: ParamSpec

      the #GParamSpec of a property installed on the class of object.

    Returns void

  • 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.

    Note that reusing the same cell renderer is not supported.

    Parameters

    • cell: Gtk.CellRenderer

      a #GtkCellRenderer

    • Optional expand: boolean

      %TRUE if cell is to be given extra space allocated to cell_layout

    Returns void

  • 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.

    Note that reusing the same cell renderer is not supported.

    Parameters

    • cell: Gtk.CellRenderer

      a #GtkCellRenderer

    • Optional expand: boolean

      %TRUE if cell is to be given extra space allocated to cell_layout

    Returns void

  • 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_add_from_file() or gtk_builder_add_from_string() is called on a builder.

    Parameters

    Returns void

  • Increases the reference count of object.

    Since GLib 2.56, if GLIB_VERSION_MAX_ALLOWED is 2.56 or greater, the type of object will be propagated to the return type (using the GCC typeof() extension), so any casting the caller needs to do on the return type must be explicit.

    Returns GObject.Object

  • Increase the reference count of object, and possibly remove the [floating][floating-ref] reference, if object has a floating reference.

    In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.

    Since GLib 2.56, the type of object will be propagated to the return type under the same conditions as for g_object_ref().

    Returns GObject.Object

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

    Parameters

    • renderer: Gtk.CellRenderer

      the #GtkCellRenderer expected to have focus

    • sibling: Gtk.CellRenderer

      the #GtkCellRenderer to remove from renderer’s focus area

    Returns void

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

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext for this row of data.

    • widget: Gtk.Widget

      the #GtkWidget that area is rendering to

    • cr: cairo.Context

      the #cairo_t to render with

    • background_area: Gdk.Rectangle

      the widget relative coordinates for area’s background

    • cell_area: Gdk.Rectangle

      the widget relative coordinates for area

    • flags: Gtk.CellRendererState

      the #GtkCellRendererState for area in this row.

    • paint_focus: boolean

      whether area should paint focus on focused cells for focused rows or not.

    Returns void

  • Re-inserts cell at position.

    Note that cell has already to be packed into cell_layout for this to function properly.

    Parameters

    • cell: Gtk.CellRenderer

      a #GtkCellRenderer to reorder

    • position: number

      new position to insert cell at

    Returns void

  • 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_inner_cell_area() at render and event time since this function will add padding around the cell for focus painting.

    Parameters

    • renderer: Gtk.CellRenderer

      the #GtkCellRenderer to request size for

    • orientation: Gtk.Orientation

      the #GtkOrientation in which to request size

    • widget: Gtk.Widget

      the #GtkWidget that area is rendering onto

    • for_size: number

      the allocation contextual size to request for, or -1 if the base request for the orientation is to be returned.

    Returns [number, number]

  • run_dispose(): void
  • set_buildable_property(builder: Gtk.Builder, name: string, value: any): void
  • Sets the #GtkCellLayoutDataFunc to use for cell_layout.

    This function is used instead of the standard attributes mapping for setting the column value, and should set the value of cell_layout’s cell renderer(s) as appropriate.

    func may be %NULL to remove a previously set function.

    Parameters

    Returns void

  • set_data(key: string, data?: object): void
  • Each object carries around a table of associations from strings to pointers. This function lets you set an association.

    If the object already had an association with that name, the old association will be destroyed.

    Internally, the key is converted to a #GQuark using g_quark_from_string(). This means a copy of key is kept permanently (even after object has been finalized) — so it is recommended to only use a small, bounded set of values for key in your program, to avoid the #GQuark storage growing unbounded.

    Parameters

    • key: string

      name of the key

    • Optional data: object

      data to associate with that key

    Returns void

  • Explicitly sets the currently focused cell to renderer.

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

    Parameters

    Returns void

  • set_name(name: string): void
  • set_property(property_name: string, value?: any): void
  • steal_data(key?: string): object
  • steal_qdata(quark: number): object
  • This function gets back user data pointers stored via g_object_set_qdata() and removes the data from object without invoking its destroy() function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier, for example:

    void
    object_add_to_user_list (GObject *object,
    const gchar *new_string)
    {
    // the quark, naming the object data
    GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
    // retrieve the old string list
    GList *list = g_object_steal_qdata (object, quark_string_list);

    // prepend new string
    list = g_list_prepend (list, g_strdup (new_string));
    // this changed 'list', so we need to set it again
    g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
    }
    static void
    free_string_list (gpointer data)
    {
    GList *node, *list = data;

    for (node = list; node; node = node->next)
    g_free (node->data);
    g_list_free (list);
    }

    Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full().

    Parameters

    • quark: number

      A #GQuark, naming the user data pointer

    Returns object

  • stop_editing(canceled: boolean): void
  • 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 gtk_cell_area_get_edited_cell() and gtk_cell_area_get_edit_widget().

    Parameters

    • canceled: boolean

      whether editing was canceled.

    Returns void

  • thaw_notify(): void
  • Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on object and when it reaches zero, queued "notify" signals are emitted.

    Duplicate notifications for each property are squashed so that at most one #GObject::notify signal is emitted for each property, in the reverse order in which they have been queued.

    It is an error to call this function when the freeze count is zero.

    Returns void

  • unref(): void
  • Decreases the reference count of object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).

    If the pointer to the #GObject may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to %NULL rather than retain a dangling pointer to a potentially invalid #GObject instance. Use g_clear_object() for this.

    Returns void

  • 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.

    virtual

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext in context with the current row data

    • widget: Gtk.Widget

      the #GtkWidget that area is rendering on

    • cell_area: Gdk.Rectangle

      the size and location of area relative to widget’s allocation

    • flags: Gtk.CellRendererState

      the #GtkCellRendererState flags for area for this row of data.

    • edit_only: boolean

      if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated.

    Returns boolean

  • vfunc_add_attribute(cell: Gtk.CellRenderer, attribute: string, column: number): void
  • Adds an attribute mapping to the list in cell_layout.

    The column is the column of the model to get a value from, and the attribute is the parameter on cell to be set from the value. So for example if column 2 of the model contains strings, you could have the “text” attribute of a #GtkCellRendererText get its values from column 2.

    virtual

    Parameters

    • cell: Gtk.CellRenderer

      a #GtkCellRenderer

    • attribute: string

      an attribute on the renderer

    • column: number

      the column position on the model to get the attribute from

    Returns void

  • vfunc_apply_attributes(tree_model: Gtk.TreeModel, iter: Gtk.TreeIter, is_expander: boolean, is_expanded: boolean): void
  • Applies any connected attributes to the renderers in area by pulling the values from tree_model.

    virtual

    Parameters

    • tree_model: Gtk.TreeModel

      the #GtkTreeModel to pull values from

    • iter: Gtk.TreeIter

      the #GtkTreeIter in tree_model to apply values for

    • is_expander: boolean

      whether iter has children

    • is_expanded: boolean

      whether iter is expanded in the view and children are visible

    Returns void

  • vfunc_clear(): void
  • vfunc_constructed(): void
  • 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.

    virtual

    Parameters

    Returns Gtk.CellAreaContext

  • 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).

    virtual

    Returns Gtk.CellAreaContext

  • This is similar to gtk_buildable_parser_finished() but is called once for each custom tag handled by the buildable.

    virtual

    Parameters

    • builder: Gtk.Builder

      a #GtkBuilder

    • child: GObject.Object

      child object or %NULL for non-child tags

    • tagname: string

      the name of the tag

    • data: object

      user data created in custom_tag_start

    Returns void

  • This is called at the end of each custom element handled by the buildable.

    virtual

    Parameters

    • builder: Gtk.Builder

      #GtkBuilder used to construct this object

    • child: GObject.Object

      child object or %NULL for non-child tags

    • tagname: string

      name of tag

    • data: object

      user data that will be passed in to parser functions

    Returns void

  • vfunc_dispatch_properties_changed(n_pspecs: number, pspecs: ParamSpec): void
  • vfunc_dispose(): void
  • vfunc_finalize(): void
  • 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.

    virtual

    Parameters

    Returns boolean

  • Calls callback for every #GtkCellRenderer in area with the allocated rectangle inside cell_area.

    virtual

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext for this row of data.

    • widget: Gtk.Widget

      the #GtkWidget that area is rendering to

    • cell_area: Gdk.Rectangle

      the widget relative coordinates and size for area

    • background_area: Gdk.Rectangle

      the widget relative coordinates of the background area

    • callback: Gtk.CellAllocCallback

      the #GtkCellAllocCallback to call

    Returns void

  • vfunc_get_name(): string
  • 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.

    virtual

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext to perform this request with

    • widget: Gtk.Widget

      the #GtkWidget where area will be rendering

    Returns [number, number]

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

    virtual

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext which has already been requested for widths.

    • widget: Gtk.Widget

      the #GtkWidget where area will be rendering

    • width: number

      the width for which to check the height of this area

    Returns [number, number]

  • 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.

    virtual

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext to perform this request with

    • widget: Gtk.Widget

      the #GtkWidget where area will be rendering

    Returns [number, number]

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

    virtual

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext which has already been requested for widths.

    • widget: Gtk.Widget

      the #GtkWidget where area will be rendering

    • height: number

      the height for which to check the width of this area

    Returns [number, number]

  • vfunc_get_property(property_id: number, value?: any, pspec?: ParamSpec): void
  • vfunc_is_activatable(): boolean
  • Returns whether the area can do anything when activated, after applying new attributes to area.

    virtual

    Returns boolean

  • Emits a "notify" signal for the property property_name on object.

    When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

    Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.

    virtual

    Parameters

    Returns void

  • 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.

    Note that reusing the same cell renderer is not supported.

    virtual

    Parameters

    • cell: Gtk.CellRenderer

      a #GtkCellRenderer

    • expand: boolean

      %TRUE if cell is to be given extra space allocated to cell_layout

    Returns void

  • 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.

    Note that reusing the same cell renderer is not supported.

    virtual

    Parameters

    • cell: Gtk.CellRenderer

      a #GtkCellRenderer

    • expand: boolean

      %TRUE if cell is to be given extra space allocated to cell_layout

    Returns void

  • 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_add_from_file() or gtk_builder_add_from_string() is called on a builder.

    virtual

    Parameters

    Returns void

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

    virtual

    Parameters

    • context: Gtk.CellAreaContext

      the #GtkCellAreaContext for this row of data.

    • widget: Gtk.Widget

      the #GtkWidget that area is rendering to

    • cr: cairo.Context

      the #cairo_t to render with

    • background_area: Gdk.Rectangle

      the widget relative coordinates for area’s background

    • cell_area: Gdk.Rectangle

      the widget relative coordinates for area

    • flags: Gtk.CellRendererState

      the #GtkCellRendererState for area in this row.

    • paint_focus: boolean

      whether area should paint focus on focused cells for focused rows or not.

    Returns void

  • vfunc_set_buildable_property(builder: Gtk.Builder, name: string, value: any): void
  • Sets the #GtkCellLayoutDataFunc to use for cell_layout.

    This function is used instead of the standard attributes mapping for setting the column value, and should set the value of cell_layout’s cell renderer(s) as appropriate.

    func may be %NULL to remove a previously set function.

    virtual

    Parameters

    Returns void

  • vfunc_set_name(name: string): void
  • vfunc_set_property(property_id: number, value?: any, pspec?: ParamSpec): void
  • watch_closure(closure: TClosure<any, any>): void
  • This function essentially limits the life time of the closure to the life time of the object. That is, when the object is finalized, the closure is invalidated by calling g_closure_invalidate() on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also, g_object_ref() and g_object_unref() are added as marshal guards to the closure, to ensure that an extra reference count is held on object during invocation of the closure. Usually, this function will be called on closures that use this object as closure data.

    Parameters

    • closure: TClosure<any, any>

      #GClosure to watch

    Returns void

  • compat_control(what: number, data: object): number
  • Find the #GParamSpec with the given name for an interface. Generally, the interface vtable passed in as g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek().

    Parameters

    • g_iface: TypeInterface

      any interface vtable for the interface, or the default vtable for the interface

    • property_name: string

      name of a property to look up.

    Returns ParamSpec

  • Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created #GParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property.

    This function is meant to be called from the interface's default vtable initialization function (the class_init member of #GTypeInfo.) It must not be called after after class_init has been called for any object types implementing this interface.

    If pspec is a floating reference, it will be consumed.

    Parameters

    • g_iface: TypeInterface

      any interface vtable for the interface, or the default vtable for the interface.

    • pspec: ParamSpec

      the #GParamSpec for the new property

    Returns void

  • Lists the properties of an interface.Generally, the interface vtable passed in as g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek().

    Parameters

    • g_iface: TypeInterface

      any interface vtable for the interface, or the default vtable for the interface

    Returns ParamSpec[]

  • Creates a new instance of a #GObject subtype and sets its properties.

    Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values.

    Parameters

    • object_type: GType<unknown>

      the type id of the #GObject subtype to instantiate

    • parameters: GObject.Parameter[]

      an array of #GParameter

    Returns GObject.Object

Legend

  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Type alias with type parameter
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method