@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/combo-box.js

@@ -4,6 +4,68 @@ import { CellArea } from "./cell-area.js";
 import { CellRenderer } from "./cell-renderer.js";
 import { TreeModel } from "./tree-model.js";
 import { Widget } from "./widget.js";
+/**
+ * A `GtkComboBox` is a widget that allows the user to choose from a list of
+ * valid choices.
+ *
+ *
+ *
+ * The `GtkComboBox` displays the selected choice; when activated, the
+ * `GtkComboBox` displays a popup which allows the user to make a new choice.
+ *
+ * The `GtkComboBox` uses the model-view pattern; the list of valid choices
+ * is specified in the form of a tree model, and the display of the choices
+ * can be adapted to the data in the model by using cell renderers, as you
+ * would in a tree view. This is possible since `GtkComboBox` implements the
+ * [iface@Gtk.CellLayout] interface. The tree model holding the valid
+ * choices is not restricted to a flat list, it can be a real tree, and the
+ * popup will reflect the tree structure.
+ *
+ * To allow the user to enter values not in the model, the
+ * [property@Gtk.ComboBox:has-entry] property allows the `GtkComboBox` to
+ * contain a [class@Gtk.Entry]. This entry can be accessed by calling
+ * [method@Gtk.ComboBox.get_child] on the combo box.
+ *
+ * For a simple list of textual choices, the model-view API of `GtkComboBox`
+ * can be a bit overwhelming. In this case, [class@Gtk.ComboBoxText] offers
+ * a simple alternative. Both `GtkComboBox` and `GtkComboBoxText` can contain
+ * an entry.
+ *
+ * ## CSS nodes
+ *
+ * ```
+ * combobox
+ * ├── box.linked
+ * │   ╰── button.combo
+ * │       ╰── box
+ * │           ├── cellview
+ * │           ╰── arrow
+ * ╰── window.popup
+ * ```
+ *
+ * A normal combobox contains a box with the .linked class, a button
+ * with the .combo class and inside those buttons, there are a cellview and
+ * an arrow.
+ *
+ * ```
+ * combobox
+ * ├── box.linked
+ * │   ├── entry.combo
+ * │   ╰── button.combo
+ * │       ╰── box
+ * │           ╰── arrow
+ * ╰── window.popup
+ * ```
+ *
+ * A `GtkComboBox` with an entry has a single CSS node with name combobox.
+ * It contains a box with the .linked class. That box contains an entry and
+ * a button, both with the .combo class added. The button also contains another
+ * node with name arrow.
+ *
+ * ## Accessibility
+ *
+ * `GtkComboBox` uses the [enum@Gtk.AccessibleRole.combo_box] role.
+ */
 const SIGNAL_META = {
     activate: { params: [], returnType: { type: "undefined" } },
     changed: { params: [], returnType: { type: "undefined" } },
@@ -19,9 +81,19 @@ const SIGNAL_META = {
     popup: { params: [], returnType: { type: "undefined" } },
 };
 export class ComboBox extends Widget {
+    /**
+     * Creates a new empty `GtkComboBox`.
+     */
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Creates a new empty `GtkComboBox` with an entry.
+     *
+     * In order to use a combo box with entry, you need to tell it
+     * which column of the model contains the text for the entry
+     * by calling [method@Gtk.ComboBox.set_entry_text_column].
+     */
     static boxNewWithEntry() {
         const ptr = call("libgtk-4.so.1", "gtk_combo_box_new_with_entry", [], {
             type: "gobject",
@@ -29,6 +101,10 @@ export class ComboBox extends Widget {
         });
         return getObject(ptr, ComboBox);
     }
+    /**
+     * Creates a new `GtkComboBox` with a model.
+     * @param model - a `GtkTreeModel`
+     */
     static boxNewWithModel(model) {
         const ptr = call("libgtk-4.so.1", "gtk_combo_box_new_with_model", [
             {
@@ -38,6 +114,12 @@ export class ComboBox extends Widget {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, ComboBox);
     }
+    /**
+     * Creates a new empty `GtkComboBox` with an entry and a model.
+     *
+     * See also [ctor@Gtk.ComboBox.new_with_entry].
+     * @param model - A `GtkTreeModel`
+     */
     static boxNewWithModelAndEntry(model) {
         const ptr = call("libgtk-4.so.1", "gtk_combo_box_new_with_model_and_entry", [
             {
@@ -53,6 +135,14 @@ export class ComboBox extends Widget {
             borrowed: true,
         });
     }
+    /**
+     * Returns the index of the currently active item.
+     *
+     * If the model is a non-flat treemodel, and the active item is not
+     * an immediate child of the root of the tree, this function returns
+     * `gtk_tree_path_get_indices (path)[0]`, where `path` is the
+     * [struct@Gtk.TreePath] of the active item.
+     */
     getActive() {
         return call("libgtk-4.so.1", "gtk_combo_box_get_active", [
             {
@@ -61,6 +151,20 @@ export class ComboBox extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns the ID of the active row of @combo_box.
+     *
+     * This value is taken from the active row and the column specified
+     * by the [property@Gtk.ComboBox:id-column] property of `combo_box` (see [method@Gtk.ComboBox.set_id_column]).
+     *
+     * The returned value is an interned string which means that you can
+     * compare the pointer by value to other interned strings and that you
+     * must not free it.
+     *
+     * If the [property@Gtk.ComboBox:id-column] property of `combo_box` is
+     * not set, or if no row is active, or if the active row has a %NULL
+     * ID value, then %NULL is returned.
+     */
     getActiveId() {
         return call("libgtk-4.so.1", "gtk_combo_box_get_active_id", [
             {
@@ -69,6 +173,12 @@ export class ComboBox extends Widget {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Sets `iter` to point to the currently active item.
+     *
+     * If no item is active, `iter` is left unchanged.
+     * @param iter - A `GtkTreeIter`
+     */
     getActiveIter(iter) {
         return call("libgtk-4.so.1", "gtk_combo_box_get_active_iter", [
             {
@@ -88,6 +198,10 @@ export class ComboBox extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether the combo box sets the dropdown button
+     * sensitive or not when there are no items in the model.
+     */
     getButtonSensitivity() {
         return call("libgtk-4.so.1", "gtk_combo_box_get_button_sensitivity", [
             {
@@ -96,6 +210,9 @@ export class ComboBox extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the child widget of @combo_box.
+     */
     getChild() {
         const ptr = call("libgtk-4.so.1", "gtk_combo_box_get_child", [
             {
@@ -107,6 +224,10 @@ export class ComboBox extends Widget {
             return null;
         return getObject(ptr, Widget);
     }
+    /**
+     * Returns the column which `combo_box` is using to get the strings
+     * from to display in the internal entry.
+     */
     getEntryTextColumn() {
         return call("libgtk-4.so.1", "gtk_combo_box_get_entry_text_column", [
             {
@@ -115,6 +236,9 @@ export class ComboBox extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns whether the combo box has an entry.
+     */
     getHasEntry() {
         return call("libgtk-4.so.1", "gtk_combo_box_get_has_entry", [
             {
@@ -123,6 +247,10 @@ export class ComboBox extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the column which `combo_box` is using to get string IDs
+     * for values from.
+     */
     getIdColumn() {
         return call("libgtk-4.so.1", "gtk_combo_box_get_id_column", [
             {
@@ -131,6 +259,9 @@ export class ComboBox extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns the `GtkTreeModel` of @combo_box.
+     */
     getModel() {
         const ptr = call("libgtk-4.so.1", "gtk_combo_box_get_model", [
             {
@@ -142,6 +273,9 @@ export class ComboBox extends Widget {
             return null;
         return getObject(ptr, TreeModel);
     }
+    /**
+     * Gets whether the popup uses a fixed width.
+     */
     getPopupFixedWidth() {
         return call("libgtk-4.so.1", "gtk_combo_box_get_popup_fixed_width", [
             {
@@ -150,6 +284,12 @@ export class ComboBox extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Hides the menu or dropdown list of @combo_box.
+     *
+     * This function is mostly intended for use by accessibility technologies;
+     * applications should have little use for it.
+     */
     popdown() {
         call("libgtk-4.so.1", "gtk_combo_box_popdown", [
             {
@@ -158,6 +298,14 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Pops up the menu or dropdown list of @combo_box.
+     *
+     * This function is mostly intended for use by accessibility technologies;
+     * applications should have little use for it.
+     *
+     * Before calling this, `combo_box` must be mapped, or nothing will happen.
+     */
     popup() {
         call("libgtk-4.so.1", "gtk_combo_box_popup", [
             {
@@ -166,6 +314,15 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Pops up the menu of @combo_box.
+     *
+     * Note that currently this does not do anything with the device, as it was
+     * previously only used for list-mode combo boxes, and those were removed
+     * in GTK 4. However, it is retained in case similar functionality is added
+     * back later.
+     * @param device - a `GdkDevice`
+     */
     popupForDevice(device) {
         call("libgtk-4.so.1", "gtk_combo_box_popup_for_device", [
             {
@@ -178,6 +335,10 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the active item of `combo_box` to be the item at @index.
+     * @param index_ - An index in the model passed during construction,
+     */
     setActive(index_) {
         call("libgtk-4.so.1", "gtk_combo_box_set_active", [
             {
@@ -190,6 +351,18 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Changes the active row of `combo_box` to the one that has an ID equal to
+     * @active_id.
+     *
+     * If `active_id` is %NULL, the active row is unset. Rows having
+     * a %NULL ID string cannot be made active by this function.
+     *
+     * If the [property@Gtk.ComboBox:id-column] property of `combo_box` is
+     * unset or if no row has the given ID then the function does nothing
+     * and returns %FALSE.
+     * @param activeId - the ID of the row to select
+     */
     setActiveId(activeId) {
         return call("libgtk-4.so.1", "gtk_combo_box_set_active_id", [
             {
@@ -203,6 +376,12 @@ export class ComboBox extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Sets the current active item to be the one referenced by @iter.
+     *
+     * If `iter` is %NULL, the active item is unset.
+     * @param iter - The `GtkTreeIter`
+     */
     setActiveIter(iter) {
         call("libgtk-4.so.1", "gtk_combo_box_set_active_iter", [
             {
@@ -221,6 +400,11 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the dropdown button of the combo box should update
+     * its sensitivity depending on the model contents.
+     * @param sensitivity - specify the sensitivity of the dropdown button
+     */
     setButtonSensitivity(sensitivity) {
         call("libgtk-4.so.1", "gtk_combo_box_set_button_sensitivity", [
             {
@@ -233,6 +417,10 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the child widget of @combo_box.
+     * @param child - the child widget
+     */
     setChild(child) {
         call("libgtk-4.so.1", "gtk_combo_box_set_child", [
             {
@@ -246,6 +434,20 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the model column which `combo_box` should use to get strings
+     * from to be @text_column.
+     *
+     * For this column no separate
+     * [class@Gtk.CellRenderer] is needed.
+     *
+     * The column `text_column` in the model of `combo_box` must be of
+     * type %G_TYPE_STRING.
+     *
+     * This is only relevant if `combo_box` has been created with
+     * [property@Gtk.ComboBox:has-entry] as %TRUE.
+     * @param textColumn - A column in `model` to get the strings from for
+     */
     setEntryTextColumn(textColumn) {
         call("libgtk-4.so.1", "gtk_combo_box_set_entry_text_column", [
             {
@@ -258,6 +460,14 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the model column which `combo_box` should use to get string IDs
+     * for values from.
+     *
+     * The column `id_column` in the model of `combo_box` must be of type
+     * %G_TYPE_STRING.
+     * @param idColumn - A column in `model` to get string IDs for values from
+     */
     setIdColumn(idColumn) {
         call("libgtk-4.so.1", "gtk_combo_box_set_id_column", [
             {
@@ -270,6 +480,17 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the model used by `combo_box` to be @model.
+     *
+     * Will unset a previously set model (if applicable). If model is %NULL,
+     * then it will unset the model.
+     *
+     * Note that this function does not clear the cell renderers, you have to
+     * call [method@Gtk.CellLayout.clear] yourself if you need to set up different
+     * cell renderers for the new model.
+     * @param model - A `GtkTreeModel`
+     */
     setModel(model) {
         call("libgtk-4.so.1", "gtk_combo_box_set_model", [
             {
@@ -283,6 +504,13 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Specifies whether the popup’s width should be a fixed width.
+     *
+     * If `fixed` is %TRUE, the popup's width is set to match the
+     * allocated width of the combo box.
+     * @param fixed - whether to use a fixed popup width
+     */
     setPopupFixedWidth(fixed) {
         call("libgtk-4.so.1", "gtk_combo_box_set_popup_fixed_width", [
             {
@@ -295,6 +523,16 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the row separator function, which is used to determine
+     * whether a row should be drawn as a separator.
+     *
+     * If the row separator function is %NULL, no separators are drawn.
+     * This is the default value.
+     * @param func - a `GtkTreeViewRowSeparatorFunc`
+     * @param data - user data to pass to @func
+     * @param destroy - destroy notifier for @data
+     */
     setRowSeparatorFunc(func, data, destroy) {
         call("libgtk-4.so.1", "gtk_combo_box_set_row_separator_func", [
             {
@@ -318,6 +556,9 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Emits the `GtkCellEditable::editing-done` signal.
+     */
     editingDone() {
         call("libgtk-4.so.1", "gtk_cell_editable_editing_done", [
             {
@@ -326,6 +567,9 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Emits the `GtkCellEditable::remove-widget` signal.
+     */
     removeWidget() {
         call("libgtk-4.so.1", "gtk_cell_editable_remove_widget", [
             {
@@ -334,6 +578,19 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Begins editing on a @cell_editable.
+     *
+     * The `GtkCellRenderer` for the cell creates and returns a `GtkCellEditable` from
+     * gtk_cell_renderer_start_editing(), configured for the `GtkCellRenderer` type.
+     *
+     * gtk_cell_editable_start_editing() can then set up `cell_editable` suitably for
+     * editing a cell, e.g. making the Esc key emit `GtkCellEditable::editing-done`.
+     *
+     * Note that the `cell_editable` is created on-demand for the current edit; its
+     * lifetime is temporary and does not persist across other edits and/or cells.
+     * @param event - The `GdkEvent` that began the editing process, or
+     */
     startEditing(event) {
         call("libgtk-4.so.1", "gtk_cell_editable_start_editing", [
             {
@@ -347,6 +604,18 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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 property on `cell` to be set from that 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.
+     * In this context "attribute" and "property" are used interchangeably.
+     * @param cell - a `GtkCellRenderer`
+     * @param attribute - a property on the renderer
+     * @param column - the column position on the model to get the attribute from
+     */
     addAttribute(cell, attribute, column) {
         call("libgtk-4.so.1", "gtk_cell_layout_add_attribute", [
             {
@@ -367,6 +636,10 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Unsets all the mappings on all renderers on `cell_layout` and
+     * removes all renderers from @cell_layout.
+     */
     clear() {
         call("libgtk-4.so.1", "gtk_cell_layout_clear", [
             {
@@ -375,6 +648,11 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Clears all existing attributes previously set with
+     * gtk_cell_layout_set_attributes().
+     * @param cell - a `GtkCellRenderer` to clear the attribute mapping on
+     */
     clearAttributes(cell) {
         call("libgtk-4.so.1", "gtk_cell_layout_clear_attributes", [
             {
@@ -387,6 +665,10 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns the underlying `GtkCellArea` which might be `cell_layout` if called on a `GtkCellArea` or might be %NULL if no `GtkCellArea`
+     * is used by @cell_layout.
+     */
     getArea() {
         const ptr = call("libgtk-4.so.1", "gtk_cell_layout_get_area", [
             {
@@ -398,6 +680,9 @@ export class ComboBox extends Widget {
             return null;
         return getObject(ptr, CellArea);
     }
+    /**
+     * Returns the cell renderers which have been added to @cell_layout.
+     */
     getCells() {
         const ptrs = call("libgtk-4.so.1", "gtk_cell_layout_get_cells", [
             {
@@ -412,6 +697,15 @@ export class ComboBox extends Widget {
         });
         return ptrs.map((ptr) => getObject(ptr, CellRenderer));
     }
+    /**
+     * 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.
+     * @param cell - a `GtkCellRenderer`
+     * @param expand - %TRUE if `cell` is to be given extra space allocated to @cell_layout
+     */
     packEnd(cell, expand) {
         call("libgtk-4.so.1", "gtk_cell_layout_pack_end", [
             {
@@ -428,6 +722,15 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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.
+     * @param cell - a `GtkCellRenderer`
+     * @param expand - %TRUE if `cell` is to be given extra space allocated to @cell_layout
+     */
     packStart(cell, expand) {
         call("libgtk-4.so.1", "gtk_cell_layout_pack_start", [
             {
@@ -444,6 +747,13 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Re-inserts `cell` at @position.
+     *
+     * Note that `cell` has already to be packed into `cell_layout` for this to function properly.
+     * @param cell - a `GtkCellRenderer` to reorder
+     * @param position - new position to insert `cell` at
+     */
     reorder(cell, position) {
         call("libgtk-4.so.1", "gtk_cell_layout_reorder", [
             {
@@ -460,6 +770,19 @@ export class ComboBox extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the `GtkCellLayout`DataFunc 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.
+     * @param cell - a `GtkCellRenderer`
+     * @param func - the `GtkCellLayout`DataFunc to use
+     * @param funcData - user data for @func
+     * @param destroy - destroy notify for @func_data
+     */
     setCellDataFunc(cell, destroy, func, funcData) {
         call("libgtk-4.so.1", "gtk_cell_layout_set_cell_data_func", [
             {

package/dist/generated/gtk/constant-expression.d.ts

@@ -1,8 +1,16 @@
 import * as GObject from "../gobject/index.js";
 import { Expression } from "./expression.js";
+/** A constant value in a `GtkExpression`. */
 export declare class ConstantExpression extends Expression {
+    /**
+     * Creates an expression that always evaluates to the given `value`.
+     * @param value - a `GValue`
+     */
     constructor(value: GObject.Value);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Gets the value that a constant expression evaluates to.
+     */
     getValue(): GObject.Value;
 }

package/dist/generated/gtk/constant-expression.js

@@ -2,6 +2,7 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
 import { Expression } from "./expression.js";
+/** A constant value in a `GtkExpression`. */
 export class ConstantExpression extends Expression {
     constructor(...args) {
         super(...args);
@@ -20,6 +21,9 @@ export class ConstantExpression extends Expression {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets the value that a constant expression evaluates to.
+     */
     getValue() {
         const ptr = call("libgtk-4.so.1", "gtk_constant_expression_get_value", [
             {