@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/tree-model-filter.d.ts

@@ -5,46 +5,455 @@ import { TreePath } from "./tree-path.js";
 import { TreeModel } from "./tree-model.js";
 import * as GObject from "../gobject/index.js";
 import * as Gdk from "../gdk/index.js";
+/**
+ * A `GtkTreeModel` which hides parts of an underlying tree model
+ *
+ * A `GtkTreeModelFilter` is a tree model which wraps another tree model,
+ * and can do the following things:
+ *
+ * - Filter specific rows, based on data from a “visible column”, a column
+ * storing booleans indicating whether the row should be filtered or not,
+ * or based on the return value of a “visible function”, which gets a
+ * model, iter and user_data and returns a boolean indicating whether the
+ * row should be filtered or not.
+ *
+ * - Modify the “appearance” of the model, using a modify function.
+ * This is extremely powerful and allows for just changing some
+ * values and also for creating a completely different model based
+ * on the given child model.
+ *
+ * - Set a different root node, also known as a “virtual root”. You can pass
+ * in a `GtkTreePath` indicating the root node for the filter at construction
+ * time.
+ *
+ * The basic API is similar to `GtkTreeModelSort`. For an example on its usage,
+ * see the section on `GtkTreeModelSort`.
+ *
+ * When using `GtkTreeModelFilter`, it is important to realize that
+ * `GtkTreeModelFilter` maintains an internal cache of all nodes which are
+ * visible in its clients. The cache is likely to be a subtree of the tree
+ * exposed by the child model. `GtkTreeModelFilter` will not cache the entire
+ * child model when unnecessary to not compromise the caching mechanism
+ * that is exposed by the reference counting scheme. If the child model
+ * implements reference counting, unnecessary signals may not be emitted
+ * because of reference counting rule 3, see the `GtkTreeModel`
+ * documentation. (Note that e.g. `GtkTreeStore` does not implement
+ * reference counting and will always emit all signals, even when
+ * the receiving node is not visible).
+ *
+ * Because of this, limitations for possible visible functions do apply.
+ * In general, visible functions should only use data or properties from
+ * the node for which the visibility state must be determined, its siblings
+ * or its parents. Usually, having a dependency on the state of any child
+ * node is not possible, unless references are taken on these explicitly.
+ * When no such reference exists, no signals may be received for these child
+ * nodes (see reference counting rule number 3 in the `GtkTreeModel` section).
+ *
+ * Determining the visibility state of a given node based on the state
+ * of its child nodes is a frequently occurring use case. Therefore,
+ * `GtkTreeModelFilter` explicitly supports this. For example, when a node
+ * does not have any children, you might not want the node to be visible.
+ * As soon as the first row is added to the node’s child level (or the
+ * last row removed), the node’s visibility should be updated.
+ *
+ * This introduces a dependency from the node on its child nodes. In order
+ * to accommodate this, `GtkTreeModelFilter` must make sure the necessary
+ * signals are received from the child model. This is achieved by building,
+ * for all nodes which are exposed as visible nodes to `GtkTreeModelFilter`'s
+ * clients, the child level (if any) and take a reference on the first node
+ * in this level. Furthermore, for every row-inserted, row-changed or
+ * row-deleted signal (also these which were not handled because the node
+ * was not cached), `GtkTreeModelFilter` will check if the visibility state
+ * of any parent node has changed.
+ *
+ * Beware, however, that this explicit support is limited to these two
+ * cases. For example, if you want a node to be visible only if two nodes
+ * in a child’s child level (2 levels deeper) are visible, you are on your
+ * own. In this case, either rely on `GtkTreeStore` to emit all signals
+ * because it does not implement reference counting, or for models that
+ * do implement reference counting, obtain references on these child levels
+ * yourself.
+ */
 export declare class TreeModelFilter extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * This function should almost never be called. It clears the `filter` of any cached iterators that haven’t been reffed with
+     * gtk_tree_model_ref_node(). This might be useful if the child model
+     * being filtered is static (and doesn’t change often) and there has been
+     * a lot of unreffed access to nodes. As a side effect of this function,
+     * all unreffed iters will be invalid.
+     */
     clearCache(): void;
+    /**
+     * Sets `filter_iter` to point to the row in `filter` that corresponds to the
+     * row pointed at by @child_iter.  If `filter_iter` was not set, %FALSE is
+     * returned.
+     * @param filterIter - An uninitialized `GtkTreeIter`
+     * @param childIter - A valid `GtkTreeIter` pointing to a row on the child model.
+     */
     convertChildIterToIter(filterIter: Ref<TreeIter>, childIter: TreeIter): boolean;
+    /**
+     * Converts `child_path` to a path relative to @filter. That is, `child_path` points to a path in the child model. The rerturned path will point to the
+     * same row in the filtered model. If `child_path` isn’t a valid path on the
+     * child model or points to a row which is not visible in @filter, then %NULL
+     * is returned.
+     * @param childPath - A `GtkTreePath` to convert.
+     */
     convertChildPathToPath(childPath: TreePath): TreePath | null;
+    /**
+     * Sets `child_iter` to point to the row pointed to by @filter_iter.
+     * @param childIter - An uninitialized `GtkTreeIter`
+     * @param filterIter - A valid `GtkTreeIter` pointing to a row on @filter.
+     */
     convertIterToChildIter(childIter: Ref<TreeIter>, filterIter: TreeIter): void;
+    /**
+     * Converts `filter_path` to a path on the child model of @filter. That is,
+     * `filter_path` points to a location in @filter. The returned path will
+     * point to the same location in the model not being filtered. If `filter_path` does not point to a location in the child model, %NULL is returned.
+     * @param filterPath - A `GtkTreePath` to convert.
+     */
     convertPathToChildPath(filterPath: TreePath): TreePath | null;
+    /**
+     * Returns a pointer to the child model of @filter.
+     */
     getModel(): TreeModel;
+    /**
+     * Emits ::row_changed for each row in the child model, which causes
+     * the filter to re-evaluate whether a row is visible or not.
+     */
     refilter(): void;
+    /**
+     * With the `n_columns` and `types` parameters, you give an array of column
+     * types for this model (which will be exposed to the parent model/view).
+     * The @func, `data` and `destroy` parameters are for specifying the modify
+     * function. The modify function will get called for each
+     * data access, the goal of the modify function is to return the data which
+     * should be displayed at the location specified using the parameters of the
+     * modify function.
+     *
+     * Note that gtk_tree_model_filter_set_modify_func()
+     * can only be called once for a given filter model.
+     * @param nColumns - The number of columns in the filter model.
+     * @param types - The `GType`s of the columns.
+     * @param func - A `GtkTreeModelFilterModifyFunc`
+     * @param data - User data to pass to the modify function
+     * @param destroy - Destroy notifier of @data
+     */
     setModifyFunc(nColumns: number, types: number[], func: (...args: unknown[]) => unknown, data?: number | null, destroy?: () => void | null): void;
+    /**
+     * Sets `column` of the child_model to be the column where `filter` should
+     * look for visibility information. `columns` should be a column of type
+     * %G_TYPE_BOOLEAN, where %TRUE means that a row is visible, and %FALSE
+     * if not.
+     *
+     * Note that gtk_tree_model_filter_set_visible_func() or
+     * gtk_tree_model_filter_set_visible_column() can only be called
+     * once for a given filter model.
+     * @param column - A `int` which is the column containing the visible information
+     */
     setVisibleColumn(column: number): void;
+    /**
+     * Sets the visible function used when filtering the `filter` to be @func.
+     * The function should return %TRUE if the given row should be visible and
+     * %FALSE otherwise.
+     *
+     * If the condition calculated by the function changes over time (e.g.
+     * because it depends on some global parameters), you must call
+     * gtk_tree_model_filter_refilter() to keep the visibility information
+     * of the model up-to-date.
+     *
+     * Note that `func` is called whenever a row is inserted, when it may still
+     * be empty. The visible function should therefore take special care of empty
+     * rows, like in the example below.
+     *
+     * ```c
+     * static gboolean
+     * visible_func (GtkTreeModel *model,
+     * GtkTreeIter  *iter,
+     * gpointer      data)
+     * {
+     * // Visible if row is non-empty and first column is “HI”
+     * char *str;
+     * gboolean visible = FALSE;
+     *
+     * gtk_tree_model_get (model, iter, 0, &str, -1);
+     * if (str && strcmp (str, "HI") == 0)
+     * visible = TRUE;
+     * g_free (str);
+     *
+     * return visible;
+     * }
+     * ```
+     *
+     * Note that gtk_tree_model_filter_set_visible_func() or
+     * gtk_tree_model_filter_set_visible_column() can only be called
+     * once for a given filter model.
+     * @param func - A `GtkTreeModelFilterVisibleFunc`, the visible function
+     * @param data - User data to pass to the visible function
+     * @param destroy - Destroy notifier of @data
+     */
     setVisibleFunc(func: (...args: unknown[]) => unknown, data?: number | null, destroy?: () => void | null): void;
+    /**
+     * Asks the `GtkTreeDragSource` to delete the row at @path, because
+     * it was moved somewhere else via drag-and-drop. Returns %FALSE
+     * if the deletion fails because `path` no longer exists, or for
+     * some model-specific reason. Should robustly handle a `path` no
+     * longer found in the model!
+     * @param path - row that was being dragged
+     */
     dragDataDelete(path: TreePath): boolean;
+    /**
+     * Asks the `GtkTreeDragSource` to return a `GdkContentProvider` representing
+     * the row at @path. Should robustly handle a `path` no
+     * longer found in the model!
+     * @param path - row that was dragged
+     */
     dragDataGet(path: TreePath): Gdk.ContentProvider | null;
+    /**
+     * Asks the `GtkTreeDragSource` whether a particular row can be used as
+     * the source of a DND operation. If the source doesn’t implement
+     * this interface, the row is assumed draggable.
+     * @param path - row on which user is initiating a drag
+     */
     rowDraggable(path: TreePath): boolean;
+    /**
+     * Creates a new `GtkTreeModel`, with `child_model` as the child_model
+     * and `root` as the virtual root.
+     * @param root - A `GtkTreePath`
+     */
     filterNew(root?: TreePath | null): TreeModel;
+    /**
+     * Calls `func` on each node in model in a depth-first fashion.
+     *
+     * If `func` returns %TRUE, then the tree ceases to be walked,
+     * and gtk_tree_model_foreach() returns.
+     * @param func - a function to be called on each row
+     * @param userData - user data to passed to @func
+     */
     foreach(func: (...args: unknown[]) => unknown, userData?: number | null): void;
+    /**
+     * Returns the type of the column.
+     * @param index_ - the column index
+     */
     getColumnType(index_: number): number;
+    /**
+     * Returns a set of flags supported by this interface.
+     *
+     * The flags are a bitwise combination of `GtkTreeModel`Flags.
+     * The flags supported should not change during the lifetime
+     * of the @tree_model.
+     */
     getFlags(): TreeModelFlags;
+    /**
+     * Sets `iter` to a valid iterator pointing to @path.
+     *
+     * If `path` does not exist, `iter` is set to an invalid
+     * iterator and %FALSE is returned.
+     * @param iter - the uninitialized `GtkTreeIter`
+     * @param path - the `GtkTreePath`
+     */
     getIter(iter: Ref<TreeIter>, path: TreePath): boolean;
+    /**
+     * Initializes `iter` with the first iterator in the tree
+     * (the one at the path "0").
+     *
+     * Returns %FALSE if the tree is empty, %TRUE otherwise.
+     * @param iter - the uninitialized `GtkTreeIter`
+     */
     getIterFirst(iter: Ref<TreeIter>): boolean;
+    /**
+     * Sets `iter` to a valid iterator pointing to @path_string, if it
+     * exists.
+     *
+     * Otherwise, `iter` is left invalid and %FALSE is returned.
+     * @param iter - an uninitialized `GtkTreeIter`
+     * @param pathString - a string representation of a `GtkTreePath`
+     */
     getIterFromString(iter: Ref<TreeIter>, pathString: string): boolean;
+    /**
+     * Returns the number of columns supported by @tree_model.
+     */
     getNColumns(): number;
+    /**
+     * Returns a newly-created `GtkTreePath` referenced by @iter.
+     *
+     * This path should be freed with gtk_tree_path_free().
+     * @param iter - the `GtkTreeIter`
+     */
     getPath(iter: TreeIter): TreePath;
+    /**
+     * Generates a string representation of the iter.
+     *
+     * This string is a “:” separated list of numbers.
+     * For example, “4:10:0:3” would be an acceptable
+     * return value for this string.
+     * @param iter - a `GtkTreeIter`
+     */
     getStringFromIter(iter: TreeIter): string | null;
+    /**
+     * Initializes and sets `value` to that at @column.
+     *
+     * When done with @value, g_value_unset() needs to be called
+     * to free any allocated memory.
+     * @param iter - the `GtkTreeIter`
+     * @param column - the column to lookup the value at
+     * @param value - an empty `GValue` to set
+     */
     getValue(iter: TreeIter, column: number, value: Ref<GObject.Value>): void;
+    /**
+     * Sets `iter` to point to the first child of @parent.
+     *
+     * If `parent` has no children, %FALSE is returned and `iter` is
+     * set to be invalid. `parent` will remain a valid node after this
+     * function has been called.
+     *
+     * If `parent` is %NULL returns the first node, equivalent to
+     * `gtk_tree_model_get_iter_first (tree_model, iter);`
+     * @param iter - the new `GtkTreeIter` to be set to the child
+     * @param parent - the `GtkTreeIter`
+     */
     iterChildren(iter: Ref<TreeIter>, parent?: TreeIter | null): boolean;
+    /**
+     * Returns %TRUE if `iter` has children, %FALSE otherwise.
+     * @param iter - the `GtkTreeIter` to test for children
+     */
     iterHasChild(iter: TreeIter): boolean;
+    /**
+     * Returns the number of children that `iter` has.
+     *
+     * As a special case, if `iter` is %NULL, then the number
+     * of toplevel nodes is returned.
+     * @param iter - the `GtkTreeIter`
+     */
     iterNChildren(iter?: TreeIter | null): number;
+    /**
+     * Sets `iter` to point to the node following it at the current level.
+     *
+     * If there is no next @iter, %FALSE is returned and `iter` is set
+     * to be invalid.
+     * @param iter - the `GtkTreeIter`
+     */
     iterNext(iter: TreeIter): boolean;
+    /**
+     * Sets `iter` to be the child of @parent, using the given index.
+     *
+     * The first index is 0. If `n` is too big, or `parent` has no children,
+     * `iter` is set to an invalid iterator and %FALSE is returned. `parent` will remain a valid node after this function has been called. As a
+     * special case, if `parent` is %NULL, then the @n-th root node
+     * is set.
+     * @param iter - the `GtkTreeIter` to set to the nth child
+     * @param parent - the `GtkTreeIter` to get the child from
+     * @param n - the index of the desired child
+     */
     iterNthChild(iter: Ref<TreeIter>, n: number, parent?: TreeIter | null): boolean;
+    /**
+     * Sets `iter` to be the parent of @child.
+     *
+     * If `child` is at the toplevel, and doesn’t have a parent, then
+     * `iter` is set to an invalid iterator and %FALSE is returned.
+     * `child` will remain a valid node after this function has been
+     * called.
+     *
+     * `iter` will be initialized before the lookup is performed, so `child` and `iter` cannot point to the same memory location.
+     * @param iter - the new `GtkTreeIter` to set to the parent
+     * @param child - the `GtkTreeIter`
+     */
     iterParent(iter: Ref<TreeIter>, child: TreeIter): boolean;
+    /**
+     * Sets `iter` to point to the previous node at the current level.
+     *
+     * If there is no previous @iter, %FALSE is returned and `iter` is
+     * set to be invalid.
+     * @param iter - the `GtkTreeIter`
+     */
     iterPrevious(iter: TreeIter): boolean;
+    /**
+     * Lets the tree ref the node.
+     *
+     * This is an optional method for models to implement.
+     * To be more specific, models may ignore this call as it exists
+     * primarily for performance reasons.
+     *
+     * This function is primarily meant as a way for views to let
+     * caching models know when nodes are being displayed (and hence,
+     * whether or not to cache that node). Being displayed means a node
+     * is in an expanded branch, regardless of whether the node is currently
+     * visible in the viewport. For example, a file-system based model
+     * would not want to keep the entire file-hierarchy in memory,
+     * just the sections that are currently being displayed by
+     * every current view.
+     *
+     * A model should be expected to be able to get an iter independent
+     * of its reffed state.
+     * @param iter - the `GtkTreeIter`
+     */
     refNode(iter: TreeIter): void;
+    /**
+     * Emits the ::row-changed signal on @tree_model.
+     *
+     * See [signal@Gtk.TreeModel::row-changed].
+     * @param path - a `GtkTreePath` pointing to the changed row
+     * @param iter - a valid `GtkTreeIter` pointing to the changed row
+     */
     rowChanged(path: TreePath, iter: TreeIter): void;
+    /**
+     * Emits the ::row-deleted signal on @tree_model.
+     *
+     * See [signal@Gtk.TreeModel::row-deleted].
+     *
+     * This should be called by models after a row has been removed.
+     * The location pointed to by `path` should be the location that
+     * the row previously was at. It may not be a valid location anymore.
+     *
+     * Nodes that are deleted are not unreffed, this means that any
+     * outstanding references on the deleted node should not be released.
+     * @param path - a `GtkTreePath` pointing to the previous location of
+     */
     rowDeleted(path: TreePath): void;
+    /**
+     * Emits the ::row-has-child-toggled signal on @tree_model.
+     *
+     * See [signal@Gtk.TreeModel::row-has-child-toggled].
+     *
+     * This should be called by models after the child
+     * state of a node changes.
+     * @param path - a `GtkTreePath` pointing to the changed row
+     * @param iter - a valid `GtkTreeIter` pointing to the changed row
+     */
     rowHasChildToggled(path: TreePath, iter: TreeIter): void;
+    /**
+     * Emits the ::row-inserted signal on @tree_model.
+     *
+     * See [signal@Gtk.TreeModel::row-inserted].
+     * @param path - a `GtkTreePath` pointing to the inserted row
+     * @param iter - a valid `GtkTreeIter` pointing to the inserted row
+     */
     rowInserted(path: TreePath, iter: TreeIter): void;
+    /**
+     * Emits the ::rows-reordered signal on @tree_model.
+     *
+     * See [signal@Gtk.TreeModel::rows-reordered].
+     *
+     * This should be called by models when their rows have been
+     * reordered.
+     * @param path - a `GtkTreePath` pointing to the tree node whose children
+     * @param iter - a valid `GtkTreeIter` pointing to the node
+     * @param newOrder - an array of integers
+     * @param length - length of `new_order` array
+     */
     rowsReorderedWithLength(path: TreePath, newOrder: number[], length: number, iter?: TreeIter | null): void;
+    /**
+     * Lets the tree unref the node.
+     *
+     * This is an optional method for models to implement.
+     * To be more specific, models may ignore this call as it exists
+     * primarily for performance reasons. For more information on what
+     * this means, see gtk_tree_model_ref_node().
+     *
+     * Please note that nodes that are deleted are not unreffed.
+     * @param iter - the `GtkTreeIter`
+     */
     unrefNode(iter: TreeIter): void;
     connect(signal: "notify", handler: (self: TreeModelFilter, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;