@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/entry-completion.js

@@ -5,6 +5,46 @@ import { CellRenderer } from "./cell-renderer.js";
 import { TreeModel } from "./tree-model.js";
 import { Widget } from "./widget.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GtkEntryCompletion` is an auxiliary object to provide completion functionality
+ * for `GtkEntry`.
+ *
+ * It implements the [iface@Gtk.CellLayout] interface, to allow the user
+ * to add extra cells to the `GtkTreeView` with completion matches.
+ *
+ * “Completion functionality” means that when the user modifies the text
+ * in the entry, `GtkEntryCompletion` checks which rows in the model match
+ * the current content of the entry, and displays a list of matches.
+ * By default, the matching is done by comparing the entry text
+ * case-insensitively against the text column of the model (see
+ * [method@Gtk.EntryCompletion.set_text_column]), but this can be overridden
+ * with a custom match function (see [method@Gtk.EntryCompletion.set_match_func]).
+ *
+ * When the user selects a completion, the content of the entry is
+ * updated. By default, the content of the entry is replaced by the
+ * text column of the model, but this can be overridden by connecting
+ * to the [signal@Gtk.EntryCompletion::match-selected] signal and updating the
+ * entry in the signal handler. Note that you should return %TRUE from
+ * the signal handler to suppress the default behaviour.
+ *
+ * To add completion functionality to an entry, use
+ * [method@Gtk.Entry.set_completion].
+ *
+ * `GtkEntryCompletion` uses a [class@Gtk.TreeModelFilter] model to
+ * represent the subset of the entire model that is currently matching.
+ * While the `GtkEntryCompletion` signals
+ * [signal@Gtk.EntryCompletion::match-selected] and
+ * [signal@Gtk.EntryCompletion::cursor-on-match] take the original model
+ * and an iter pointing to that model as arguments, other callbacks and
+ * signals (such as `GtkCellLayoutDataFunc` or
+ * [signal@Gtk.CellArea::apply-attributes)]
+ * will generally take the filter model as argument. As long as you are
+ * only calling [method@Gtk.TreeModel.get], this will make no difference to
+ * you. If for some reason, you need the original model, use
+ * [method@Gtk.TreeModelFilter.get_model]. Don’t forget to use
+ * [method@Gtk.TreeModelFilter.convert_iter_to_child_iter] to obtain a
+ * matching iter.
+ */
 const SIGNAL_META = {
     "cursor-on-match": {
         params: [
@@ -27,9 +67,20 @@ const SIGNAL_META = {
     "no-matches": { params: [], returnType: { type: "undefined" } },
 };
 export class EntryCompletion extends GObject.GObject {
+    /**
+     * Creates a new `GtkEntryCompletion` object.
+     */
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Creates a new `GtkEntryCompletion` object using the
+     * specified @area.
+     *
+     * The `GtkCellArea` is used to layout cells in the underlying
+     * `GtkTreeViewColumn` for the drop-down menu.
+     * @param area - the `GtkCellArea` used to layout cells
+     */
     static completionNewWithArea(area) {
         const ptr = call("libgtk-4.so.1", "gtk_entry_completion_new_with_area", [
             {
@@ -45,6 +96,12 @@ export class EntryCompletion extends GObject.GObject {
             borrowed: false,
         });
     }
+    /**
+     * Requests a completion operation, or in other words a refiltering of the
+     * current list with completions, using the current key.
+     *
+     * The completion list view will be updated accordingly.
+     */
     complete() {
         call("libgtk-4.so.1", "gtk_entry_completion_complete", [
             {
@@ -53,6 +110,14 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Computes the common prefix that is shared by all rows in `completion` that start with @key.
+     *
+     * If no row matches @key, %NULL will be returned.
+     * Note that a text column must have been set for this function to work,
+     * see [method@Gtk.EntryCompletion.set_text_column] for details.
+     * @param key - The text to complete for
+     */
     computePrefix(key) {
         return call("libgtk-4.so.1", "gtk_entry_completion_compute_prefix", [
             {
@@ -65,6 +130,10 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "string" });
     }
+    /**
+     * Get the original text entered by the user that triggered
+     * the completion or %NULL if there’s no completion ongoing.
+     */
     getCompletionPrefix() {
         return call("libgtk-4.so.1", "gtk_entry_completion_get_completion_prefix", [
             {
@@ -73,6 +142,9 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the entry `completion` has been attached to.
+     */
     getEntry() {
         const ptr = call("libgtk-4.so.1", "gtk_entry_completion_get_entry", [
             {
@@ -82,6 +154,10 @@ export class EntryCompletion extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Widget);
     }
+    /**
+     * Returns whether the common prefix of the possible completions should
+     * be automatically inserted in the entry.
+     */
     getInlineCompletion() {
         return call("libgtk-4.so.1", "gtk_entry_completion_get_inline_completion", [
             {
@@ -90,6 +166,9 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns %TRUE if inline-selection mode is turned on.
+     */
     getInlineSelection() {
         return call("libgtk-4.so.1", "gtk_entry_completion_get_inline_selection", [
             {
@@ -98,6 +177,9 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the minimum key length as set for @completion.
+     */
     getMinimumKeyLength() {
         return call("libgtk-4.so.1", "gtk_entry_completion_get_minimum_key_length", [
             {
@@ -106,6 +188,11 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns the model the `GtkEntryCompletion` is using as data source.
+     *
+     * Returns %NULL if the model is unset.
+     */
     getModel() {
         const ptr = call("libgtk-4.so.1", "gtk_entry_completion_get_model", [
             {
@@ -117,6 +204,9 @@ export class EntryCompletion extends GObject.GObject {
             return null;
         return getObject(ptr, TreeModel);
     }
+    /**
+     * Returns whether the completions should be presented in a popup window.
+     */
     getPopupCompletion() {
         return call("libgtk-4.so.1", "gtk_entry_completion_get_popup_completion", [
             {
@@ -125,6 +215,10 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether the completion popup window will be resized to the
+     * width of the entry.
+     */
     getPopupSetWidth() {
         return call("libgtk-4.so.1", "gtk_entry_completion_get_popup_set_width", [
             {
@@ -133,6 +227,10 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether the completion popup window will appear even if there is
+     * only a single match.
+     */
     getPopupSingleMatch() {
         return call("libgtk-4.so.1", "gtk_entry_completion_get_popup_single_match", [
             {
@@ -141,6 +239,9 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the column in the model of `completion` to get strings from.
+     */
     getTextColumn() {
         return call("libgtk-4.so.1", "gtk_entry_completion_get_text_column", [
             {
@@ -149,6 +250,9 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Requests a prefix insertion.
+     */
     insertPrefix() {
         call("libgtk-4.so.1", "gtk_entry_completion_insert_prefix", [
             {
@@ -157,6 +261,11 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the common prefix of the possible completions should
+     * be automatically inserted in the entry.
+     * @param inlineCompletion - %TRUE to do inline completion
+     */
     setInlineCompletion(inlineCompletion) {
         call("libgtk-4.so.1", "gtk_entry_completion_set_inline_completion", [
             {
@@ -169,6 +278,11 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether it is possible to cycle through the possible completions
+     * inside the entry.
+     * @param inlineSelection - %TRUE to do inline selection
+     */
     setInlineSelection(inlineSelection) {
         call("libgtk-4.so.1", "gtk_entry_completion_set_inline_selection", [
             {
@@ -181,6 +295,15 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the match function for `completion` to be @func.
+     *
+     * The match function is used to determine if a row should or
+     * should not be in the completion list.
+     * @param func - the `GtkEntryCompletion`MatchFunc to use
+     * @param funcData - user data for @func
+     * @param funcNotify - destroy notify for @func_data.
+     */
     setMatchFunc(func, funcNotify, funcData) {
         call("libgtk-4.so.1", "gtk_entry_completion_set_match_func", [
             {
@@ -202,6 +325,15 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Requires the length of the search key for `completion` to be at least
+     * @length.
+     *
+     * This is useful for long lists, where completing using a small
+     * key takes a lot of time and will come up with meaningless results anyway
+     * (ie, a too large dataset).
+     * @param length - the minimum length of the key in order to start completing
+     */
     setMinimumKeyLength(length) {
         call("libgtk-4.so.1", "gtk_entry_completion_set_minimum_key_length", [
             {
@@ -214,6 +346,14 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the model for a `GtkEntryCompletion`.
+     *
+     * If `completion` already has a model set, it will remove it
+     * before setting the new model. If model is %NULL, then it
+     * will unset the model.
+     * @param model - the `GtkTreeModel`
+     */
     setModel(model) {
         call("libgtk-4.so.1", "gtk_entry_completion_set_model", [
             {
@@ -227,6 +367,10 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the completions should be presented in a popup window.
+     * @param popupCompletion - %TRUE to do popup completion
+     */
     setPopupCompletion(popupCompletion) {
         call("libgtk-4.so.1", "gtk_entry_completion_set_popup_completion", [
             {
@@ -239,6 +383,11 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the completion popup window will be resized to be the same
+     * width as the entry.
+     * @param popupSetWidth - %TRUE to make the width of the popup the same as the entry
+     */
     setPopupSetWidth(popupSetWidth) {
         call("libgtk-4.so.1", "gtk_entry_completion_set_popup_set_width", [
             {
@@ -251,6 +400,14 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the completion popup window will appear even if there is
+     * only a single match.
+     *
+     * You may want to set this to %FALSE if you
+     * are using [property@Gtk.EntryCompletion:inline-completion].
+     * @param popupSingleMatch - %TRUE if the popup should appear even for a single match
+     */
     setPopupSingleMatch(popupSingleMatch) {
         call("libgtk-4.so.1", "gtk_entry_completion_set_popup_single_match", [
             {
@@ -263,6 +420,19 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Convenience function for setting up the most used case of this code: a
+     * completion list with just strings.
+     *
+     * This function will set up `completion` to have a list displaying all (and just) strings in the completion list,
+     * and to get those strings from `column` in the model of @completion.
+     *
+     * This functions creates and adds a `GtkCellRendererText` for the selected
+     * column. If you need to set the text column, but don't want the cell
+     * renderer, use g_object_set() to set the
+     * [property@Gtk.EntryCompletion:text-column] property directly.
+     * @param column - the column in the model of `completion` to get strings from
+     */
     setTextColumn(column) {
         call("libgtk-4.so.1", "gtk_entry_completion_set_text_column", [
             {
@@ -275,6 +445,12 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the ID of the `buildable` object.
+     *
+     * `GtkBuilder` sets the name based on the ID attribute
+     * of the `<object>` tag used to construct the @buildable.
+     */
     getBuildableId() {
         return call("libgtk-4.so.1", "gtk_buildable_get_buildable_id", [
             {
@@ -283,6 +459,18 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * 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", [
             {
@@ -303,6 +491,10 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { 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", [
             {
@@ -311,6 +503,11 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { 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", [
             {
@@ -323,6 +520,10 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { 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", [
             {
@@ -334,6 +535,9 @@ export class EntryCompletion extends GObject.GObject {
             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", [
             {
@@ -348,6 +552,15 @@ export class EntryCompletion extends GObject.GObject {
         });
         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", [
             {
@@ -364,6 +577,15 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { 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", [
             {
@@ -380,6 +602,13 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { 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", [
             {
@@ -396,6 +625,19 @@ export class EntryCompletion extends GObject.GObject {
             },
         ], { 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", [
             {