@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/tree-path.js

@@ -1,10 +1,20 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/** An opaque structure representing a path to a row in a model. */
 export class TreePath {
     ptr;
+    /**
+     * Creates a new `GtkTreePath`
+     * This refers to a row.
+     */
     constructor() {
         this.ptr = this.createPtr([]);
     }
+    /**
+     * Creates a new `GtkTreePath`.
+     *
+     * The string representation of this path is “0”.
+     */
     static pathNewFirst() {
         const ptr = call("libgtk-4.so.1", "gtk_tree_path_new_first", [], {
             type: "boxed",
@@ -13,6 +23,11 @@ export class TreePath {
         });
         return getObject(ptr, TreePath);
     }
+    /**
+     * Creates a new path with the given `indices` array of @length.
+     * @param indices - array of indices
+     * @param length - length of `indices` array
+     */
     static pathNewFromIndicesv(indices, length) {
         const ptr = call("libgtk-4.so.1", "gtk_tree_path_new_from_indicesv", [
             {
@@ -29,6 +44,16 @@ export class TreePath {
         ], { type: "boxed", borrowed: true, innerType: "TreePath" });
         return getObject(ptr, TreePath);
     }
+    /**
+     * Creates a new `GtkTreePath` initialized to @path.
+     *
+     * `path` is expected to be a colon separated list of numbers.
+     * For example, the string “10:4:0” would create a path of depth
+     * 3 pointing to the 11th child of the root node, the 5th
+     * child of that 11th child, and the 1st child of that 5th child.
+     * If an invalid path string is passed in, %NULL is returned.
+     * @param path - The string representation of a path
+     */
     static pathNewFromString(path) {
         const ptr = call("libgtk-4.so.1", "gtk_tree_path_new_from_string", [
             {
@@ -45,6 +70,12 @@ export class TreePath {
             innerType: "GtkTreePath",
         });
     }
+    /**
+     * Appends a new index to a path.
+     *
+     * As a result, the depth of the path is increased.
+     * @param index_ - the index
+     */
     appendIndex(index_) {
         call("libgtk-4.so.1", "gtk_tree_path_append_index", [
             {
@@ -57,6 +88,14 @@ export class TreePath {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Compares two paths.
+     *
+     * If `a` appears before `b` in a tree, then -1 is returned.
+     * If `b` appears before @a, then 1 is returned.
+     * If the two nodes are equal, then 0 is returned.
+     * @param b - a `GtkTreePath` to compare with
+     */
     compare(b) {
         return call("libgtk-4.so.1", "gtk_tree_path_compare", [
             {
@@ -74,6 +113,9 @@ export class TreePath {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Creates a new `GtkTreePath` as a copy of @path.
+     */
     copy() {
         const ptr = call("libgtk-4.so.1", "gtk_tree_path_copy", [
             {
@@ -88,6 +130,9 @@ export class TreePath {
         });
         return getObject(ptr, TreePath);
     }
+    /**
+     * Moves `path` to point to the first child of the current path.
+     */
     down() {
         call("libgtk-4.so.1", "gtk_tree_path_down", [
             {
@@ -96,6 +141,9 @@ export class TreePath {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Frees @path. If `path` is %NULL, it simply returns.
+     */
     free() {
         call("libgtk-4.so.1", "gtk_tree_path_free", [
             {
@@ -104,6 +152,9 @@ export class TreePath {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns the current depth of @path.
+     */
     getDepth() {
         return call("libgtk-4.so.1", "gtk_tree_path_get_depth", [
             {
@@ -112,6 +163,14 @@ export class TreePath {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns the current indices of @path.
+     *
+     * This is an array of integers, each representing a node in a tree.
+     * It also returns the number of elements in the array.
+     * The array should not be freed.
+     * @param depth - return location for number of elements
+     */
     getIndicesWithDepth(depth) {
         return call("libgtk-4.so.1", "gtk_tree_path_get_indices_with_depth", [
             {
@@ -128,6 +187,10 @@ export class TreePath {
             },
         ], { type: "array", itemType: { type: "int", size: 32, unsigned: false } });
     }
+    /**
+     * Returns %TRUE if `descendant` is a descendant of @path.
+     * @param descendant - another `GtkTreePath`
+     */
     isAncestor(descendant) {
         return call("libgtk-4.so.1", "gtk_tree_path_is_ancestor", [
             {
@@ -145,6 +208,10 @@ export class TreePath {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns %TRUE if `path` is a descendant of @ancestor.
+     * @param ancestor - another `GtkTreePath`
+     */
     isDescendant(ancestor) {
         return call("libgtk-4.so.1", "gtk_tree_path_is_descendant", [
             {
@@ -162,6 +229,9 @@ export class TreePath {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Moves the `path` to point to the next node at the current depth.
+     */
     next() {
         call("libgtk-4.so.1", "gtk_tree_path_next", [
             {
@@ -170,6 +240,12 @@ export class TreePath {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Prepends a new index to a path.
+     *
+     * As a result, the depth of the path is increased.
+     * @param index_ - the index
+     */
     prependIndex(index_) {
         call("libgtk-4.so.1", "gtk_tree_path_prepend_index", [
             {
@@ -182,6 +258,10 @@ export class TreePath {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Moves the `path` to point to the previous node at the
+     * current depth, if it exists.
+     */
     prev() {
         return call("libgtk-4.so.1", "gtk_tree_path_prev", [
             {
@@ -190,6 +270,14 @@ export class TreePath {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Generates a string representation of the path.
+     *
+     * This string is a “:” separated list of numbers.
+     * For example, “4:10:0:3” would be an acceptable
+     * return value for this string. If the path has
+     * depth 0, %NULL is returned.
+     */
     toString() {
         return call("libgtk-4.so.1", "gtk_tree_path_to_string", [
             {
@@ -198,6 +286,9 @@ export class TreePath {
             },
         ], { type: "string" });
     }
+    /**
+     * Moves the `path` to point to its parent node, if it has a parent.
+     */
     up() {
         return call("libgtk-4.so.1", "gtk_tree_path_up", [
             {

package/dist/generated/gtk/tree-row-reference.d.ts

@@ -1,17 +1,91 @@
 import { TreePath } from "./tree-path.js";
 import { TreeModel } from "./tree-model.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * A GtkTreeRowReference tracks model changes so that it always refers to the
+ * same row (a `GtkTreePath` refers to a position, not a fixed row). Create a
+ * new GtkTreeRowReference with gtk_tree_row_reference_new().
+ */
 export declare class TreeRowReference {
     ptr: unknown;
+    /**
+     * Creates a row reference based on @path.
+     *
+     * This reference will keep pointing to the node pointed to
+     * by @path, so long as it exists. Any changes that occur on `model` are
+     * propagated, and the path is updated appropriately. If
+     * `path` isn’t a valid path in @model, then %NULL is returned.
+     * @param model - a `GtkTreeModel`
+     * @param path - a valid `GtkTreePath` to monitor
+     */
     constructor(model: TreeModel, path: TreePath);
     constructor(_args: unknown[]);
+    /**
+     * You do not need to use this function.
+     *
+     * Creates a row reference based on @path.
+     *
+     * This reference will keep pointing to the node pointed to
+     * by @path, so long as it exists. If `path` isn’t a valid
+     * path in @model, then %NULL is returned. However, unlike
+     * references created with gtk_tree_row_reference_new(), it
+     * does not listen to the model for changes. The creator of
+     * the row reference must do this explicitly using
+     * gtk_tree_row_reference_inserted(), gtk_tree_row_reference_deleted(),
+     * gtk_tree_row_reference_reordered().
+     *
+     * These functions must be called exactly once per proxy when the
+     * corresponding signal on the model is emitted. This single call
+     * updates all row references for that proxy. Since built-in GTK
+     * objects like `GtkTreeView` already use this mechanism internally,
+     * using them as the proxy object will produce unpredictable results.
+     * Further more, passing the same object as `model` and `proxy` doesn’t work for reasons of internal implementation.
+     *
+     * This type of row reference is primarily meant by structures that
+     * need to carefully monitor exactly when a row reference updates
+     * itself, and is not generally needed by most applications.
+     * @param proxy - a proxy `GObject`
+     * @param model - a `GtkTreeModel`
+     * @param path - a valid `GtkTreePath` to monitor
+     */
     static rowReferenceNewProxy(proxy: GObject.GObject, model: TreeModel, path: TreePath): TreeRowReference;
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Lets a set of row reference created by
+     * gtk_tree_row_reference_new_proxy() know that the
+     * model emitted the ::row-deleted signal.
+     * @param proxy - a `GObject`
+     * @param path - the path position that was deleted
+     */
     static deleted(proxy: GObject.GObject, path: TreePath): void;
+    /**
+     * Lets a set of row reference created by
+     * gtk_tree_row_reference_new_proxy() know that the
+     * model emitted the ::row-inserted signal.
+     * @param proxy - a `GObject`
+     * @param path - the row position that was inserted
+     */
     static inserted(proxy: GObject.GObject, path: TreePath): void;
+    /**
+     * Copies a `GtkTreeRowReference`.
+     */
     copy(): TreeRowReference;
+    /**
+     * Free’s @reference. `reference` may be %NULL
+     */
     free(): void;
+    /**
+     * Returns the model that the row reference is monitoring.
+     */
     getModel(): TreeModel;
+    /**
+     * Returns a path that the row reference currently points to,
+     * or %NULL if the path pointed to is no longer valid.
+     */
     getPath(): TreePath | null;
+    /**
+     * Returns %TRUE if the `reference` is non-%NULL and refers to
+     * a current valid path.
+     */
     valid(): boolean;
 }

package/dist/generated/gtk/tree-row-reference.js

@@ -2,12 +2,45 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { TreePath } from "./tree-path.js";
 import { TreeModel } from "./tree-model.js";
+/**
+ * A GtkTreeRowReference tracks model changes so that it always refers to the
+ * same row (a `GtkTreePath` refers to a position, not a fixed row). Create a
+ * new GtkTreeRowReference with gtk_tree_row_reference_new().
+ */
 export class TreeRowReference {
     ptr;
     constructor(...args) {
         const _args = args.length === 1 && Array.isArray(args[0]) ? args[0] : args;
         this.ptr = this.createPtr(_args);
     }
+    /**
+     * You do not need to use this function.
+     *
+     * Creates a row reference based on @path.
+     *
+     * This reference will keep pointing to the node pointed to
+     * by @path, so long as it exists. If `path` isn’t a valid
+     * path in @model, then %NULL is returned. However, unlike
+     * references created with gtk_tree_row_reference_new(), it
+     * does not listen to the model for changes. The creator of
+     * the row reference must do this explicitly using
+     * gtk_tree_row_reference_inserted(), gtk_tree_row_reference_deleted(),
+     * gtk_tree_row_reference_reordered().
+     *
+     * These functions must be called exactly once per proxy when the
+     * corresponding signal on the model is emitted. This single call
+     * updates all row references for that proxy. Since built-in GTK
+     * objects like `GtkTreeView` already use this mechanism internally,
+     * using them as the proxy object will produce unpredictable results.
+     * Further more, passing the same object as `model` and `proxy` doesn’t work for reasons of internal implementation.
+     *
+     * This type of row reference is primarily meant by structures that
+     * need to carefully monitor exactly when a row reference updates
+     * itself, and is not generally needed by most applications.
+     * @param proxy - a proxy `GObject`
+     * @param model - a `GtkTreeModel`
+     * @param path - a valid `GtkTreePath` to monitor
+     */
     static rowReferenceNewProxy(proxy, model, path) {
         const ptr = call("libgtk-4.so.1", "gtk_tree_row_reference_new_proxy", [
             {
@@ -48,6 +81,13 @@ export class TreeRowReference {
             },
         ], { type: "boxed", borrowed: true, innerType: "GtkTreeRowReference" });
     }
+    /**
+     * Lets a set of row reference created by
+     * gtk_tree_row_reference_new_proxy() know that the
+     * model emitted the ::row-deleted signal.
+     * @param proxy - a `GObject`
+     * @param path - the path position that was deleted
+     */
     static deleted(proxy, path) {
         call("libgtk-4.so.1", "gtk_tree_row_reference_deleted", [
             {
@@ -65,6 +105,13 @@ export class TreeRowReference {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Lets a set of row reference created by
+     * gtk_tree_row_reference_new_proxy() know that the
+     * model emitted the ::row-inserted signal.
+     * @param proxy - a `GObject`
+     * @param path - the row position that was inserted
+     */
     static inserted(proxy, path) {
         call("libgtk-4.so.1", "gtk_tree_row_reference_inserted", [
             {
@@ -82,6 +129,9 @@ export class TreeRowReference {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Copies a `GtkTreeRowReference`.
+     */
     copy() {
         const ptr = call("libgtk-4.so.1", "gtk_tree_row_reference_copy", [
             {
@@ -96,6 +146,9 @@ export class TreeRowReference {
         });
         return getObject(ptr, TreeRowReference);
     }
+    /**
+     * Free’s @reference. `reference` may be %NULL
+     */
     free() {
         call("libgtk-4.so.1", "gtk_tree_row_reference_free", [
             {
@@ -104,6 +157,9 @@ export class TreeRowReference {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns the model that the row reference is monitoring.
+     */
     getModel() {
         const ptr = call("libgtk-4.so.1", "gtk_tree_row_reference_get_model", [
             {
@@ -113,6 +169,10 @@ export class TreeRowReference {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, TreeModel);
     }
+    /**
+     * Returns a path that the row reference currently points to,
+     * or %NULL if the path pointed to is no longer valid.
+     */
     getPath() {
         const ptr = call("libgtk-4.so.1", "gtk_tree_row_reference_get_path", [
             {
@@ -129,6 +189,10 @@ export class TreeRowReference {
             return null;
         return getObject(ptr, TreePath);
     }
+    /**
+     * Returns %TRUE if the `reference` is non-%NULL and refers to
+     * a current valid path.
+     */
     valid() {
         return call("libgtk-4.so.1", "gtk_tree_row_reference_valid", [
             {

package/dist/generated/gtk/tree-selection.d.ts

@@ -8,23 +8,121 @@ import * as GObject from "../gobject/index.js";
 export declare class TreeSelection extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Returns the number of rows that have been selected in @tree.
+     */
     countSelectedRows(): number;
+    /**
+     * Gets the selection mode for @selection. See
+     * gtk_tree_selection_set_mode().
+     */
     getMode(): SelectionMode;
+    /**
+     * Sets `iter` to the currently selected node if `selection` is set to
+     * %GTK_SELECTION_SINGLE or %GTK_SELECTION_BROWSE.  `iter` may be NULL if you
+     * just want to test if `selection` has any selected nodes.  `model` is filled
+     * with the current model as a convenience.  This function will not work if you
+     * use `selection` is %GTK_SELECTION_MULTIPLE.
+     * @param model - A pointer to set to the `GtkTreeModel`
+     * @param iter - The `GtkTreeIter`
+     */
     getSelected(model?: Ref<TreeModel> | null, iter?: Ref<TreeIter> | null): boolean;
+    /**
+     * Creates a list of path of all selected rows. Additionally, if you are
+     * planning on modifying the model after calling this function, you may
+     * want to convert the returned list into a list of `GtkTreeRowReference`s.
+     * To do this, you can use gtk_tree_row_reference_new().
+     *
+     * To free the return value, use:
+     *
+     * ```c
+     * g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free);
+     * ```
+     * @param model - A pointer to set to the `GtkTreeModel`
+     */
     getSelectedRows(model?: Ref<TreeModel> | null): TreePath[];
+    /**
+     * Returns the tree view associated with @selection.
+     */
     getTreeView(): TreeView;
+    /**
+     * Returns %TRUE if the row at `iter` is currently selected.
+     * @param iter - A valid `GtkTreeIter`
+     */
     iterIsSelected(iter: TreeIter): boolean;
+    /**
+     * Returns %TRUE if the row pointed to by `path` is currently selected.  If `path` does not point to a valid location, %FALSE is returned
+     * @param path - A `GtkTreePath` to check selection on.
+     */
     pathIsSelected(path: TreePath): boolean;
+    /**
+     * Selects all the nodes. `selection` must be set to %GTK_SELECTION_MULTIPLE
+     * mode.
+     */
     selectAll(): void;
+    /**
+     * Selects the specified iterator.
+     * @param iter - The `GtkTreeIter` to be selected.
+     */
     selectIter(iter: TreeIter): void;
+    /**
+     * Select the row at @path.
+     * @param path - The `GtkTreePath` to be selected.
+     */
     selectPath(path: TreePath): void;
+    /**
+     * Selects a range of nodes, determined by `start_path` and `end_path` inclusive.
+     * `selection` must be set to %GTK_SELECTION_MULTIPLE mode.
+     * @param startPath - The initial node of the range.
+     * @param endPath - The final node of the range.
+     */
     selectRange(startPath: TreePath, endPath: TreePath): void;
+    /**
+     * Calls a function for each selected node. Note that you cannot modify
+     * the tree or selection from within this function. As a result,
+     * gtk_tree_selection_get_selected_rows() might be more useful.
+     * @param func - The function to call for each selected node.
+     * @param data - user data to pass to the function.
+     */
     selectedForeach(func: (...args: unknown[]) => unknown, data?: number | null): void;
+    /**
+     * Sets the selection mode of the @selection.  If the previous type was
+     * %GTK_SELECTION_MULTIPLE, then the anchor is kept selected, if it was
+     * previously selected.
+     * @param type - The selection mode
+     */
     setMode(type: SelectionMode): void;
+    /**
+     * Sets the selection function.
+     *
+     * If set, this function is called before any node is selected or unselected,
+     * giving some control over which nodes are selected. The select function
+     * should return %TRUE if the state of the node may be toggled, and %FALSE
+     * if the state of the node should be left unchanged.
+     * @param func - The selection function. May be %NULL
+     * @param data - The selection function’s data. May be %NULL
+     * @param destroy - The destroy function for user data.  May be %NULL
+     */
     setSelectFunction(destroy: () => void, func?: (...args: unknown[]) => unknown | null, data?: number | null): void;
+    /**
+     * Unselects all the nodes.
+     */
     unselectAll(): void;
+    /**
+     * Unselects the specified iterator.
+     * @param iter - The `GtkTreeIter` to be unselected.
+     */
     unselectIter(iter: TreeIter): void;
+    /**
+     * Unselects the row at @path.
+     * @param path - The `GtkTreePath` to be unselected.
+     */
     unselectPath(path: TreePath): void;
+    /**
+     * Unselects a range of nodes, determined by `start_path` and `end_path` inclusive.
+     * @param startPath - The initial node of the range.
+     * @param endPath - The initial node of the range.
+     */
     unselectRange(startPath: TreePath, endPath: TreePath): void;
     connect(signal: "changed", handler: (self: TreeSelection) => void, after?: boolean): number;
     connect(signal: "notify", handler: (self: TreeSelection, pspec: GObject.ParamSpec) => void, after?: boolean): number;