@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/sort-list-model.d.ts

@@ -2,20 +2,151 @@ import { Ref } from "@gtkx/native";
 import { Sorter } from "./sorter.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * A list model that sorts the elements of another model.
+ *
+ * The elements are sorted according to a `GtkSorter`.
+ *
+ * The model is a stable sort. If two items compare equal according
+ * to the sorter, the one that appears first in the original model will
+ * also appear first after sorting.
+ *
+ * Note that if you change the sorter, the previous order will have no
+ * influence on the new order. If you want that, consider using a
+ * `GtkMultiSorter` and appending the previous sorter to it.
+ *
+ * The model can be set up to do incremental sorting, so that
+ * sorting long lists doesn't block the UI. See
+ * [method@Gtk.SortListModel.set_incremental] for details.
+ *
+ * `GtkSortListModel` is a generic model and because of that it
+ * cannot take advantage of any external knowledge when sorting.
+ * If you run into performance issues with `GtkSortListModel`,
+ * it is strongly recommended that you write your own sorting list
+ * model.
+ *
+ * `GtkSortListModel` allows sorting the items into sections. It
+ * implements `GtkSectionModel` and when [property@Gtk.SortListModel:section-sorter]
+ * is set, it will sort all items with that sorter and items comparing
+ * equal with it will be put into the same section.
+ * The [property@Gtk.SortListModel:sorter] will then be used to sort items
+ * inside their sections.
+ */
 export declare class SortListModel extends GObject.GObject {
+    /**
+     * Creates a new sort list model that uses the `sorter` to sort @model.
+     * @param model - the model to sort
+     * @param sorter - the `GtkSorter` to sort `model` with,
+     */
     constructor(model?: Gio.ListModel | null, sorter?: Sorter | null);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Returns whether incremental sorting is enabled.
+     *
+     * See [method@Gtk.SortListModel.set_incremental].
+     */
     getIncremental(): boolean;
+    /**
+     * Gets the model currently sorted or %NULL if none.
+     */
     getModel(): Gio.ListModel | null;
+    /**
+     * Estimates progress of an ongoing sorting operation.
+     *
+     * The estimate is the number of items that would still need to be
+     * sorted to finish the sorting operation if this was a linear
+     * algorithm. So this number is not related to how many items are
+     * already correctly sorted.
+     *
+     * If you want to estimate the progress, you can use code like this:
+     * ```c
+     * pending = gtk_sort_list_model_get_pending (self);
+     * model = gtk_sort_list_model_get_model (self);
+     * progress = 1.0 - pending / (double) MAX (1, g_list_model_get_n_items (model));
+     * ```
+     *
+     * If no sort operation is ongoing - in particular when
+     * [property@Gtk.SortListModel:incremental] is %FALSE - this
+     * function returns 0.
+     */
     getPending(): number;
+    /**
+     * Gets the section sorter that is used to sort items of `self` into
+     * sections.
+     */
     getSectionSorter(): Sorter | null;
+    /**
+     * Gets the sorter that is used to sort @self.
+     */
     getSorter(): Sorter | null;
+    /**
+     * Sets the sort model to do an incremental sort.
+     *
+     * When incremental sorting is enabled, the `GtkSortListModel` will not do
+     * a complete sort immediately, but will instead queue an idle handler that
+     * incrementally sorts the items towards their correct position. This of
+     * course means that items do not instantly appear in the right place. It
+     * also means that the total sorting time is a lot slower.
+     *
+     * When your filter blocks the UI while sorting, you might consider
+     * turning this on. Depending on your model and sorters, this may become
+     * interesting around 10,000 to 100,000 items.
+     *
+     * By default, incremental sorting is disabled.
+     *
+     * See [method@Gtk.SortListModel.get_pending] for progress information
+     * about an ongoing incremental sorting operation.
+     * @param incremental - %TRUE to sort incrementally
+     */
     setIncremental(incremental: boolean): void;
+    /**
+     * Sets the model to be sorted.
+     *
+     * The @model's item type must conform to the item type of @self.
+     * @param model - The model to be sorted
+     */
     setModel(model?: Gio.ListModel | null): void;
+    /**
+     * Sets a new section sorter on @self.
+     * @param sorter - the `GtkSorter` to sort `model` with
+     */
     setSectionSorter(sorter?: Sorter | null): void;
+    /**
+     * Sets a new sorter on @self.
+     * @param sorter - the `GtkSorter` to sort `model` with
+     */
     setSorter(sorter?: Sorter | null): void;
+    /**
+     * Query the section that covers the given position. The number of
+     * items in the section can be computed by `out_end - out_start`.
+     *
+     * If the position is larger than the number of items, a single
+     * range from n_items to G_MAXUINT will be returned.
+     * @param position - the position of the item to query
+     * @param outStart - the position of the first item in the section
+     * @param outEnd - the position of the first item not part of the section
+     */
     getSection(position: number, outStart: Ref<number>, outEnd: Ref<number>): void;
+    /**
+     * This function emits the [signal@Gtk.SectionModel::sections-changed]
+     * signal to notify about changes to sections.
+     *
+     * It must cover all positions that used to be a section start or that
+     * are now a section start. It does not have to cover all positions for
+     * which the section has changed.
+     *
+     * The [signal@Gio.ListModel::items-changed] implies the effect of the
+     * [signal@Gtk.SectionModel::sections-changed] signal for all the items
+     * it covers.
+     *
+     * It is recommended that when changes to the items cause section changes
+     * in a larger range, that the larger range is included in the emission
+     * of the [signal@Gio.ListModel::items-changed] instead of emitting
+     * two signals.
+     * @param position - the first changed item
+     * @param nItems - the number of changed items
+     */
     sectionsChanged(position: number, nItems: number): void;
     connect(signal: "notify", handler: (self: SortListModel, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtk/sort-list-model.js

@@ -3,6 +3,36 @@ import { getObject } from "@gtkx/ffi";
 import { Sorter } from "./sorter.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * A list model that sorts the elements of another model.
+ *
+ * The elements are sorted according to a `GtkSorter`.
+ *
+ * The model is a stable sort. If two items compare equal according
+ * to the sorter, the one that appears first in the original model will
+ * also appear first after sorting.
+ *
+ * Note that if you change the sorter, the previous order will have no
+ * influence on the new order. If you want that, consider using a
+ * `GtkMultiSorter` and appending the previous sorter to it.
+ *
+ * The model can be set up to do incremental sorting, so that
+ * sorting long lists doesn't block the UI. See
+ * [method@Gtk.SortListModel.set_incremental] for details.
+ *
+ * `GtkSortListModel` is a generic model and because of that it
+ * cannot take advantage of any external knowledge when sorting.
+ * If you run into performance issues with `GtkSortListModel`,
+ * it is strongly recommended that you write your own sorting list
+ * model.
+ *
+ * `GtkSortListModel` allows sorting the items into sections. It
+ * implements `GtkSectionModel` and when [property@Gtk.SortListModel:section-sorter]
+ * is set, it will sort all items with that sorter and items comparing
+ * equal with it will be put into the same section.
+ * The [property@Gtk.SortListModel:sorter] will then be used to sort items
+ * inside their sections.
+ */
 export class SortListModel extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -22,6 +52,11 @@ export class SortListModel extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Returns whether incremental sorting is enabled.
+     *
+     * See [method@Gtk.SortListModel.set_incremental].
+     */
     getIncremental() {
         return call("libgtk-4.so.1", "gtk_sort_list_model_get_incremental", [
             {
@@ -30,6 +65,9 @@ export class SortListModel extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the model currently sorted or %NULL if none.
+     */
     getModel() {
         const ptr = call("libgtk-4.so.1", "gtk_sort_list_model_get_model", [
             {
@@ -41,6 +79,25 @@ export class SortListModel extends GObject.GObject {
             return null;
         return getObject(ptr, Gio.ListModel);
     }
+    /**
+     * Estimates progress of an ongoing sorting operation.
+     *
+     * The estimate is the number of items that would still need to be
+     * sorted to finish the sorting operation if this was a linear
+     * algorithm. So this number is not related to how many items are
+     * already correctly sorted.
+     *
+     * If you want to estimate the progress, you can use code like this:
+     * ```c
+     * pending = gtk_sort_list_model_get_pending (self);
+     * model = gtk_sort_list_model_get_model (self);
+     * progress = 1.0 - pending / (double) MAX (1, g_list_model_get_n_items (model));
+     * ```
+     *
+     * If no sort operation is ongoing - in particular when
+     * [property@Gtk.SortListModel:incremental] is %FALSE - this
+     * function returns 0.
+     */
     getPending() {
         return call("libgtk-4.so.1", "gtk_sort_list_model_get_pending", [
             {
@@ -49,6 +106,10 @@ export class SortListModel extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Gets the section sorter that is used to sort items of `self` into
+     * sections.
+     */
     getSectionSorter() {
         const ptr = call("libgtk-4.so.1", "gtk_sort_list_model_get_section_sorter", [
             {
@@ -60,6 +121,9 @@ export class SortListModel extends GObject.GObject {
             return null;
         return getObject(ptr, Sorter);
     }
+    /**
+     * Gets the sorter that is used to sort @self.
+     */
     getSorter() {
         const ptr = call("libgtk-4.so.1", "gtk_sort_list_model_get_sorter", [
             {
@@ -71,6 +135,25 @@ export class SortListModel extends GObject.GObject {
             return null;
         return getObject(ptr, Sorter);
     }
+    /**
+     * Sets the sort model to do an incremental sort.
+     *
+     * When incremental sorting is enabled, the `GtkSortListModel` will not do
+     * a complete sort immediately, but will instead queue an idle handler that
+     * incrementally sorts the items towards their correct position. This of
+     * course means that items do not instantly appear in the right place. It
+     * also means that the total sorting time is a lot slower.
+     *
+     * When your filter blocks the UI while sorting, you might consider
+     * turning this on. Depending on your model and sorters, this may become
+     * interesting around 10,000 to 100,000 items.
+     *
+     * By default, incremental sorting is disabled.
+     *
+     * See [method@Gtk.SortListModel.get_pending] for progress information
+     * about an ongoing incremental sorting operation.
+     * @param incremental - %TRUE to sort incrementally
+     */
     setIncremental(incremental) {
         call("libgtk-4.so.1", "gtk_sort_list_model_set_incremental", [
             {
@@ -83,6 +166,12 @@ export class SortListModel extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the model to be sorted.
+     *
+     * The @model's item type must conform to the item type of @self.
+     * @param model - The model to be sorted
+     */
     setModel(model) {
         call("libgtk-4.so.1", "gtk_sort_list_model_set_model", [
             {
@@ -96,6 +185,10 @@ export class SortListModel extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets a new section sorter on @self.
+     * @param sorter - the `GtkSorter` to sort `model` with
+     */
     setSectionSorter(sorter) {
         call("libgtk-4.so.1", "gtk_sort_list_model_set_section_sorter", [
             {
@@ -109,6 +202,10 @@ export class SortListModel extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets a new sorter on @self.
+     * @param sorter - the `GtkSorter` to sort `model` with
+     */
     setSorter(sorter) {
         call("libgtk-4.so.1", "gtk_sort_list_model_set_sorter", [
             {
@@ -122,6 +219,16 @@ export class SortListModel extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Query the section that covers the given position. The number of
+     * items in the section can be computed by `out_end - out_start`.
+     *
+     * If the position is larger than the number of items, a single
+     * range from n_items to G_MAXUINT will be returned.
+     * @param position - the position of the item to query
+     * @param outStart - the position of the first item in the section
+     * @param outEnd - the position of the first item not part of the section
+     */
     getSection(position, outStart, outEnd) {
         call("libgtk-4.so.1", "gtk_section_model_get_section", [
             {
@@ -148,6 +255,25 @@ export class SortListModel extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * This function emits the [signal@Gtk.SectionModel::sections-changed]
+     * signal to notify about changes to sections.
+     *
+     * It must cover all positions that used to be a section start or that
+     * are now a section start. It does not have to cover all positions for
+     * which the section has changed.
+     *
+     * The [signal@Gio.ListModel::items-changed] implies the effect of the
+     * [signal@Gtk.SectionModel::sections-changed] signal for all the items
+     * it covers.
+     *
+     * It is recommended that when changes to the items cause section changes
+     * in a larger range, that the larger range is included in the emission
+     * of the [signal@Gio.ListModel::items-changed] instead of emitting
+     * two signals.
+     * @param position - the first changed item
+     * @param nItems - the number of changed items
+     */
     sectionsChanged(position, nItems) {
         call("libgtk-4.so.1", "gtk_section_model_sections_changed", [
             {

package/dist/generated/gtk/sorter.d.ts

@@ -3,8 +3,47 @@ import * as GObject from "../gobject/index.js";
 export declare class Sorter extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Notifies all users of the sorter that it has changed.
+     *
+     * This emits the [signal@Gtk.Sorter::changed] signal. Users
+     * of the sorter should then update the sort order via
+     * [method@Gtk.Sorter.compare].
+     *
+     * Depending on the `change` parameter, it may be possible to
+     * update the sort order without a full resorting. Refer to
+     * the [enum@Gtk.SorterChange] documentation for details.
+     *
+     * This function is intended for implementers of `GtkSorter`
+     * subclasses and should not be called from other functions.
+     * @param change - How the sorter changed
+     */
     changed(change: SorterChange): void;
+    /**
+     * Compares two given items according to the sort order implemented
+     * by the sorter.
+     *
+     * Sorters implement a partial order:
+     *
+     * * It is reflexive, ie a = a
+     * * It is antisymmetric, ie if a < b and b < a, then a = b
+     * * It is transitive, ie given any 3 items with a ≤ b and b ≤ c,
+     * then a ≤ c
+     *
+     * The sorter may signal it conforms to additional constraints
+     * via the return value of [method@Gtk.Sorter.get_order].
+     * @param item1 - first item to compare
+     * @param item2 - second item to compare
+     */
     compare(item1: GObject.GObject, item2: GObject.GObject): Ordering;
+    /**
+     * Gets the order that `self` conforms to.
+     *
+     * See [enum@Gtk.SorterOrder] for details
+     * of the possible return values.
+     *
+     * This function is intended to allow optimizations.
+     */
     getOrder(): SorterOrder;
     connect(signal: "changed", handler: (self: Sorter, change: SorterChange) => void, after?: boolean): number;
     connect(signal: "notify", handler: (self: Sorter, pspec: GObject.ParamSpec) => void, after?: boolean): number;

package/dist/generated/gtk/sorter.js

@@ -1,6 +1,28 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * Describes sorting criteria for a [class@Gtk.SortListModel].
+ *
+ * Its primary user is [class@Gtk.SortListModel]
+ *
+ * The model will use a sorter to determine the order in which
+ * its items should appear by calling [method@Gtk.Sorter.compare]
+ * for pairs of items.
+ *
+ * Sorters may change their sorting behavior through their lifetime.
+ * In that case, they will emit the [signal@Gtk.Sorter::changed] signal
+ * to notify that the sort order is no longer valid and should be updated
+ * by calling gtk_sorter_compare() again.
+ *
+ * GTK provides various pre-made sorter implementations for common sorting
+ * operations. [class@Gtk.ColumnView] has built-in support for sorting lists
+ * via the [property@Gtk.ColumnViewColumn:sorter] property, where the user can
+ * change the sorting by clicking on list headers.
+ *
+ * Of course, in particular for large lists, it is also possible to subclass
+ * `GtkSorter` and provide one's own sorter.
+ */
 const SIGNAL_META = {
     changed: {
         params: [{ type: { type: "int", size: 32, unsigned: false } }],
@@ -22,6 +44,21 @@ export class Sorter extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Notifies all users of the sorter that it has changed.
+     *
+     * This emits the [signal@Gtk.Sorter::changed] signal. Users
+     * of the sorter should then update the sort order via
+     * [method@Gtk.Sorter.compare].
+     *
+     * Depending on the `change` parameter, it may be possible to
+     * update the sort order without a full resorting. Refer to
+     * the [enum@Gtk.SorterChange] documentation for details.
+     *
+     * This function is intended for implementers of `GtkSorter`
+     * subclasses and should not be called from other functions.
+     * @param change - How the sorter changed
+     */
     changed(change) {
         call("libgtk-4.so.1", "gtk_sorter_changed", [
             {
@@ -34,6 +71,22 @@ export class Sorter extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Compares two given items according to the sort order implemented
+     * by the sorter.
+     *
+     * Sorters implement a partial order:
+     *
+     * * It is reflexive, ie a = a
+     * * It is antisymmetric, ie if a < b and b < a, then a = b
+     * * It is transitive, ie given any 3 items with a ≤ b and b ≤ c,
+     * then a ≤ c
+     *
+     * The sorter may signal it conforms to additional constraints
+     * via the return value of [method@Gtk.Sorter.get_order].
+     * @param item1 - first item to compare
+     * @param item2 - second item to compare
+     */
     compare(item1, item2) {
         return call("libgtk-4.so.1", "gtk_sorter_compare", [
             {
@@ -50,6 +103,14 @@ export class Sorter extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the order that `self` conforms to.
+     *
+     * See [enum@Gtk.SorterOrder] for details
+     * of the possible return values.
+     *
+     * This function is intended to allow optimizations.
+     */
     getOrder() {
         return call("libgtk-4.so.1", "gtk_sorter_get_order", [
             {