@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -2,6 +2,33 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { TreeView } from "./tree-view.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * The selection object for GtkTreeView
+ *
+ * The `GtkTreeSelection` object is a helper object to manage the selection
+ * for a `GtkTreeView` widget.  The `GtkTreeSelection` object is
+ * automatically created when a new `GtkTreeView` widget is created, and
+ * cannot exist independently of this widget.  The primary reason the
+ * `GtkTreeSelection` objects exists is for cleanliness of code and API.
+ * That is, there is no conceptual reason all these functions could not be
+ * methods on the `GtkTreeView` widget instead of a separate function.
+ *
+ * The `GtkTreeSelection` object is gotten from a `GtkTreeView` by calling
+ * gtk_tree_view_get_selection().  It can be manipulated to check the
+ * selection status of the tree, as well as select and deselect individual
+ * rows.  Selection is done completely view side.  As a result, multiple
+ * views of the same model can have completely different selections.
+ * Additionally, you cannot change the selection of a row on the model that
+ * is not currently displayed by the view without expanding its parents
+ * first.
+ *
+ * One of the important things to remember when monitoring the selection of
+ * a view is that the `GtkTreeSelection`::changed signal is mostly a hint.
+ * That is, it may only emit one signal when a range of rows is selected.
+ * Additionally, it may on occasion emit a `GtkTreeSelection`::changed signal
+ * when nothing has happened (mostly as a result of programmers calling
+ * select_row on an already selected row).
+ */
 const SIGNAL_META = {
     changed: { params: [], returnType: { type: "undefined" } },
 };
@@ -20,6 +47,9 @@ export class TreeSelection extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Returns the number of rows that have been selected in @tree.
+     */
     countSelectedRows() {
         return call("libgtk-4.so.1", "gtk_tree_selection_count_selected_rows", [
             {
@@ -28,6 +58,10 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the selection mode for @selection. See
+     * gtk_tree_selection_set_mode().
+     */
     getMode() {
         return call("libgtk-4.so.1", "gtk_tree_selection_get_mode", [
             {
@@ -36,6 +70,15 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * 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, iter) {
         return call("libgtk-4.so.1", "gtk_tree_selection_get_selected", [
             {
@@ -61,6 +104,19 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "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) {
         return call("libgtk-4.so.1", "gtk_tree_selection_get_selected_rows", [
             {
@@ -83,6 +139,9 @@ export class TreeSelection extends GObject.GObject {
             borrowed: true,
         });
     }
+    /**
+     * Returns the tree view associated with @selection.
+     */
     getTreeView() {
         const ptr = call("libgtk-4.so.1", "gtk_tree_selection_get_tree_view", [
             {
@@ -92,6 +151,10 @@ export class TreeSelection extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, TreeView);
     }
+    /**
+     * Returns %TRUE if the row at `iter` is currently selected.
+     * @param iter - A valid `GtkTreeIter`
+     */
     iterIsSelected(iter) {
         return call("libgtk-4.so.1", "gtk_tree_selection_iter_is_selected", [
             {
@@ -109,6 +172,10 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "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) {
         return call("libgtk-4.so.1", "gtk_tree_selection_path_is_selected", [
             {
@@ -126,6 +193,10 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Selects all the nodes. `selection` must be set to %GTK_SELECTION_MULTIPLE
+     * mode.
+     */
     selectAll() {
         call("libgtk-4.so.1", "gtk_tree_selection_select_all", [
             {
@@ -134,6 +205,10 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Selects the specified iterator.
+     * @param iter - The `GtkTreeIter` to be selected.
+     */
     selectIter(iter) {
         call("libgtk-4.so.1", "gtk_tree_selection_select_iter", [
             {
@@ -151,6 +226,10 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Select the row at @path.
+     * @param path - The `GtkTreePath` to be selected.
+     */
     selectPath(path) {
         call("libgtk-4.so.1", "gtk_tree_selection_select_path", [
             {
@@ -168,6 +247,12 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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, endPath) {
         call("libgtk-4.so.1", "gtk_tree_selection_select_range", [
             {
@@ -194,6 +279,13 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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, data) {
         call("libgtk-4.so.1", "gtk_tree_selection_selected_foreach", [
             {
@@ -211,6 +303,12 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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) {
         call("libgtk-4.so.1", "gtk_tree_selection_set_mode", [
             {
@@ -223,6 +321,17 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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, func, data) {
         call("libgtk-4.so.1", "gtk_tree_selection_set_select_function", [
             {
@@ -245,6 +354,9 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Unselects all the nodes.
+     */
     unselectAll() {
         call("libgtk-4.so.1", "gtk_tree_selection_unselect_all", [
             {
@@ -253,6 +365,10 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Unselects the specified iterator.
+     * @param iter - The `GtkTreeIter` to be unselected.
+     */
     unselectIter(iter) {
         call("libgtk-4.so.1", "gtk_tree_selection_unselect_iter", [
             {
@@ -270,6 +386,10 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Unselects the row at @path.
+     * @param path - The `GtkTreePath` to be unselected.
+     */
     unselectPath(path) {
         call("libgtk-4.so.1", "gtk_tree_selection_unselect_path", [
             {
@@ -287,6 +407,11 @@ export class TreeSelection extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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, endPath) {
         call("libgtk-4.so.1", "gtk_tree_selection_unselect_range", [
             {

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

@@ -1,13 +1,71 @@
 import { Ref } from "@gtkx/native";
 import { SortType } from "./enums.js";
+/**
+ * The interface for sortable models used by GtkTreeView
+ *
+ * `GtkTreeSortable` is an interface to be implemented by tree models which
+ * support sorting. The `GtkTreeView` uses the methods provided by this interface
+ * to sort the model.
+ */
 export declare class TreeSortable {
     ptr: unknown;
     protected constructor(ptr: unknown);
     static fromPtr(ptr: unknown): TreeSortable;
+    /**
+     * Fills in `sort_column_id` and `order` with the current sort column and the
+     * order. It returns %TRUE unless the `sort_column_id` is
+     * %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or
+     * %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID.
+     * @param sortColumnId - The sort column id to be filled in
+     * @param order - The `GtkSortType` to be filled in
+     */
     getSortColumnId(sortColumnId: Ref<number>, order: Ref<SortType>): boolean;
+    /**
+     * Returns %TRUE if the model has a default sort function. This is used
+     * primarily by GtkTreeViewColumns in order to determine if a model can
+     * go back to the default state, or not.
+     */
     hasDefaultSortFunc(): boolean;
+    /**
+     * Sets the default comparison function used when sorting to be @sort_func.
+     * If the current sort column id of `sortable` is
+     * %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using
+     * this function.
+     *
+     * If `sort_func` is %NULL, then there will be no default comparison function.
+     * This means that once the model  has been sorted, it can’t go back to the
+     * default state. In this case, when the current sort column id of `sortable` is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted.
+     * @param sortFunc - The comparison function
+     * @param userData - User data to pass to @sort_func
+     * @param destroy - Destroy notifier of @user_data
+     */
     setDefaultSortFunc(sortFunc: (...args: unknown[]) => unknown, userData?: number | null, destroy?: () => void | null): void;
+    /**
+     * Sets the current sort column to be @sort_column_id. The `sortable` will
+     * resort itself to reflect this change, after emitting a
+     * `GtkTreeSortable::sort-column-changed` signal. `sort_column_id` may either be
+     * a regular column id, or one of the following special values:
+     *
+     * - %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID: the default sort function
+     * will be used, if it is set
+     *
+     * - %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID: no sorting will occur
+     * @param sortColumnId - the sort column id to set
+     * @param order - The sort order of the column
+     */
     setSortColumnId(sortColumnId: number, order: SortType): void;
+    /**
+     * Sets the comparison function used when sorting to be @sort_func. If the
+     * current sort column id of `sortable` is the same as @sort_column_id, then
+     * the model will sort using this function.
+     * @param sortColumnId - the sort column id to set the function for
+     * @param sortFunc - The comparison function
+     * @param userData - User data to pass to @sort_func
+     * @param destroy - Destroy notifier of @user_data
+     */
     setSortFunc(sortColumnId: number, sortFunc: (...args: unknown[]) => unknown, userData?: number | null, destroy?: () => void | null): void;
+    /**
+     * Emits a `GtkTreeSortable::sort-column-changed` signal on @sortable.
+     */
     sortColumnChanged(): void;
 }

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

@@ -1,4 +1,11 @@
 import { call } from "@gtkx/native";
+/**
+ * The interface for sortable models used by GtkTreeView
+ *
+ * `GtkTreeSortable` is an interface to be implemented by tree models which
+ * support sorting. The `GtkTreeView` uses the methods provided by this interface
+ * to sort the model.
+ */
 export class TreeSortable {
     ptr;
     constructor(ptr) {
@@ -7,6 +14,14 @@ export class TreeSortable {
     static fromPtr(ptr) {
         return new TreeSortable(ptr);
     }
+    /**
+     * Fills in `sort_column_id` and `order` with the current sort column and the
+     * order. It returns %TRUE unless the `sort_column_id` is
+     * %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or
+     * %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID.
+     * @param sortColumnId - The sort column id to be filled in
+     * @param order - The `GtkSortType` to be filled in
+     */
     getSortColumnId(sortColumnId, order) {
         return call("libgtk-4.so.1", "gtk_tree_sortable_get_sort_column_id", [
             {
@@ -29,6 +44,11 @@ export class TreeSortable {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns %TRUE if the model has a default sort function. This is used
+     * primarily by GtkTreeViewColumns in order to determine if a model can
+     * go back to the default state, or not.
+     */
     hasDefaultSortFunc() {
         return call("libgtk-4.so.1", "gtk_tree_sortable_has_default_sort_func", [
             {
@@ -37,6 +57,19 @@ export class TreeSortable {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Sets the default comparison function used when sorting to be @sort_func.
+     * If the current sort column id of `sortable` is
+     * %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using
+     * this function.
+     *
+     * If `sort_func` is %NULL, then there will be no default comparison function.
+     * This means that once the model  has been sorted, it can’t go back to the
+     * default state. In this case, when the current sort column id of `sortable` is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted.
+     * @param sortFunc - The comparison function
+     * @param userData - User data to pass to @sort_func
+     * @param destroy - Destroy notifier of @user_data
+     */
     setDefaultSortFunc(sortFunc, userData, destroy) {
         call("libgtk-4.so.1", "gtk_tree_sortable_set_default_sort_func", [
             {
@@ -59,6 +92,19 @@ export class TreeSortable {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the current sort column to be @sort_column_id. The `sortable` will
+     * resort itself to reflect this change, after emitting a
+     * `GtkTreeSortable::sort-column-changed` signal. `sort_column_id` may either be
+     * a regular column id, or one of the following special values:
+     *
+     * - %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID: the default sort function
+     * will be used, if it is set
+     *
+     * - %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID: no sorting will occur
+     * @param sortColumnId - the sort column id to set
+     * @param order - The sort order of the column
+     */
     setSortColumnId(sortColumnId, order) {
         call("libgtk-4.so.1", "gtk_tree_sortable_set_sort_column_id", [
             {
@@ -75,6 +121,15 @@ export class TreeSortable {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the comparison function used when sorting to be @sort_func. If the
+     * current sort column id of `sortable` is the same as @sort_column_id, then
+     * the model will sort using this function.
+     * @param sortColumnId - the sort column id to set the function for
+     * @param sortFunc - The comparison function
+     * @param userData - User data to pass to @sort_func
+     * @param destroy - Destroy notifier of @user_data
+     */
     setSortFunc(sortColumnId, sortFunc, userData, destroy) {
         call("libgtk-4.so.1", "gtk_tree_sortable_set_sort_func", [
             {
@@ -101,6 +156,9 @@ export class TreeSortable {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Emits a `GtkTreeSortable::sort-column-changed` signal on @sortable.
+     */
     sortColumnChanged() {
         call("libgtk-4.so.1", "gtk_tree_sortable_sort_column_changed", [
             {