@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/string-sorter.js

@@ -2,6 +2,16 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Expression } from "./expression.js";
 import { Sorter } from "./sorter.js";
+/**
+ * Sorts items by comparing strings.
+ *
+ * To obtain the strings to compare, this sorter evaluates a
+ * [class@Gtk.Expression].
+ *
+ * It does the comparison in a linguistically correct way using the
+ * current locale by normalizing Unicode strings and possibly case-folding
+ * them before performing the comparison.
+ */
 export class StringSorter extends Sorter {
     constructor(...args) {
         super(...args);
@@ -16,6 +26,9 @@ export class StringSorter extends Sorter {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets which collation method the sorter uses.
+     */
     getCollation() {
         return call("libgtk-4.so.1", "gtk_string_sorter_get_collation", [
             {
@@ -24,6 +37,9 @@ export class StringSorter extends Sorter {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the expression that is evaluated to obtain strings from items.
+     */
     getExpression() {
         const ptr = call("libgtk-4.so.1", "gtk_string_sorter_get_expression", [
             {
@@ -35,6 +51,9 @@ export class StringSorter extends Sorter {
             return null;
         return getObject(ptr, Expression);
     }
+    /**
+     * Gets whether the sorter ignores case differences.
+     */
     getIgnoreCase() {
         return call("libgtk-4.so.1", "gtk_string_sorter_get_ignore_case", [
             {
@@ -43,6 +62,10 @@ export class StringSorter extends Sorter {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Sets the collation method to use for sorting.
+     * @param collation - the collation method
+     */
     setCollation(collation) {
         call("libgtk-4.so.1", "gtk_string_sorter_set_collation", [
             {
@@ -55,6 +78,12 @@ export class StringSorter extends Sorter {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the expression that is evaluated to obtain strings from items.
+     *
+     * The expression must have the type %G_TYPE_STRING.
+     * @param expression - a `GtkExpression`
+     */
     setExpression(expression) {
         call("libgtk-4.so.1", "gtk_string_sorter_set_expression", [
             {
@@ -68,6 +97,10 @@ export class StringSorter extends Sorter {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the sorter will ignore case differences.
+     * @param ignoreCase - %TRUE to ignore case differences
+     */
     setIgnoreCase(ignoreCase) {
         call("libgtk-4.so.1", "gtk_string_sorter_set_ignore_case", [
             {

package/dist/generated/gtk/style-context.d.ts

@@ -4,29 +4,217 @@ import { Border } from "./border.js";
 import { StyleProvider } from "./style-provider.js";
 import * as GObject from "../gobject/index.js";
 import * as Gdk from "../gdk/index.js";
+/**
+ * `GtkStyleContext` stores styling information affecting a widget.
+ *
+ * In order to construct the final style information, `GtkStyleContext`
+ * queries information from all attached `GtkStyleProviders`. Style
+ * providers can be either attached explicitly to the context through
+ * [method@Gtk.StyleContext.add_provider], or to the display through
+ * [func@Gtk.StyleContext.add_provider_for_display]. The resulting
+ * style is a combination of all providers’ information in priority order.
+ *
+ * For GTK widgets, any `GtkStyleContext` returned by
+ * [method@Gtk.Widget.get_style_context] will already have a `GdkDisplay`
+ * and RTL/LTR information set. The style context will also be updated
+ * automatically if any of these settings change on the widget.
+ *
+ * ## Style Classes
+ *
+ * Widgets can add style classes to their context, which can be used to associate
+ * different styles by class. The documentation for individual widgets lists
+ * which style classes it uses itself, and which style classes may be added by
+ * applications to affect their appearance.
+ *
+ * # Custom styling in UI libraries and applications
+ *
+ * If you are developing a library with custom widgets that render differently
+ * than standard components, you may need to add a `GtkStyleProvider` yourself
+ * with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK priority, either a
+ * `GtkCssProvider` or a custom object implementing the `GtkStyleProvider`
+ * interface. This way themes may still attempt to style your UI elements in
+ * a different way if needed so.
+ *
+ * If you are using custom styling on an applications, you probably want then
+ * to make your style information prevail to the theme’s, so you must use
+ * a `GtkStyleProvider` with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION
+ * priority, keep in mind that the user settings in
+ * `XDG_CONFIG_HOME/gtk-4.0/gtk.css` will
+ * still take precedence over your changes, as it uses the
+ * %GTK_STYLE_PROVIDER_PRIORITY_USER priority.
+ */
 export declare class StyleContext extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Adds a global style provider to @display, which will be used
+     * in style construction for all `GtkStyleContexts` under @display.
+     *
+     * GTK uses this to make styling information from `GtkSettings`
+     * available.
+     *
+     * Note: If both priorities are the same, A `GtkStyleProvider`
+     * added through [method@Gtk.StyleContext.add_provider] takes
+     * precedence over another added through this function.
+     * @param display - a `GdkDisplay`
+     * @param provider - a `GtkStyleProvider`
+     * @param priority - the priority of the style provider. The lower
+     */
     static addProviderForDisplay(display: Gdk.Display, provider: StyleProvider, priority: number): void;
+    /**
+     * Removes `provider` from the global style providers list in @display.
+     * @param display - a `GdkDisplay`
+     * @param provider - a `GtkStyleProvider`
+     */
     static removeProviderForDisplay(display: Gdk.Display, provider: StyleProvider): void;
+    /**
+     * Adds a style class to @context, so later uses of the
+     * style context will make use of this new class for styling.
+     *
+     * In the CSS file format, a `GtkEntry` defining a “search”
+     * class, would be matched by:
+     *
+     * ```css
+     * entry.search { ... }
+     * ```
+     *
+     * While any widget defining a “search” class would be
+     * matched by:
+     * ```css
+     * .search { ... }
+     * ```
+     * @param className - class name to use in styling
+     */
     addClass(className: string): void;
+    /**
+     * Adds a style provider to @context, to be used in style construction.
+     *
+     * Note that a style provider added by this function only affects
+     * the style of the widget to which `context` belongs. If you want
+     * to affect the style of all widgets, use
+     * [func@Gtk.StyleContext.add_provider_for_display].
+     *
+     * Note: If both priorities are the same, a `GtkStyleProvider`
+     * added through this function takes precedence over another added
+     * through [func@Gtk.StyleContext.add_provider_for_display].
+     * @param provider - a `GtkStyleProvider`
+     * @param priority - the priority of the style provider. The lower
+     */
     addProvider(provider: StyleProvider, priority: number): void;
+    /**
+     * Gets the border for a given state as a `GtkBorder`.
+     * @param border - return value for the border settings
+     */
     getBorder(border: Ref<Border>): void;
+    /**
+     * Gets the foreground color for a given state.
+     * @param color - return value for the foreground color
+     */
     getColor(color: Ref<Gdk.RGBA>): void;
+    /**
+     * Returns the `GdkDisplay` to which `context` is attached.
+     */
     getDisplay(): Gdk.Display;
+    /**
+     * Gets the margin for a given state as a `GtkBorder`.
+     * @param margin - return value for the margin settings
+     */
     getMargin(margin: Ref<Border>): void;
+    /**
+     * Gets the padding for a given state as a `GtkBorder`.
+     * @param padding - return value for the padding settings
+     */
     getPadding(padding: Ref<Border>): void;
+    /**
+     * Returns the scale used for assets.
+     */
     getScale(): number;
+    /**
+     * Returns the state used for style matching.
+     *
+     * This method should only be used to retrieve the `GtkStateFlags`
+     * to pass to `GtkStyleContext` methods, like
+     * [method@Gtk.StyleContext.get_padding].
+     * If you need to retrieve the current state of a `GtkWidget`, use
+     * [method@Gtk.Widget.get_state_flags].
+     */
     getState(): StateFlags;
+    /**
+     * Returns %TRUE if `context` currently has defined the
+     * given class name.
+     * @param className - a class name
+     */
     hasClass(className: string): boolean;
+    /**
+     * Looks up and resolves a color name in the `context` color map.
+     * @param colorName - color name to lookup
+     * @param color - Return location for the looked up color
+     */
     lookupColor(colorName: string, color: Ref<Gdk.RGBA>): boolean;
+    /**
+     * Removes `class_name` from @context.
+     * @param className - class name to remove
+     */
     removeClass(className: string): void;
+    /**
+     * Removes `provider` from the style providers list in @context.
+     * @param provider - a `GtkStyleProvider`
+     */
     removeProvider(provider: StyleProvider): void;
+    /**
+     * Restores `context` state to a previous stage.
+     *
+     * See [method@Gtk.StyleContext.save].
+     */
     restore(): void;
+    /**
+     * Saves the `context` state.
+     *
+     * This allows temporary modifications done through
+     * [method@Gtk.StyleContext.add_class],
+     * [method@Gtk.StyleContext.remove_class],
+     * [method@Gtk.StyleContext.set_state] to be quickly
+     * reverted in one go through [method@Gtk.StyleContext.restore].
+     *
+     * The matching call to [method@Gtk.StyleContext.restore]
+     * must be done before GTK returns to the main loop.
+     */
     save(): void;
+    /**
+     * Attaches `context` to the given display.
+     *
+     * The display is used to add style information from “global”
+     * style providers, such as the display's `GtkSettings` instance.
+     *
+     * If you are using a `GtkStyleContext` returned from
+     * [method@Gtk.Widget.get_style_context], you do not need to
+     * call this yourself.
+     * @param display - a `GdkDisplay`
+     */
     setDisplay(display: Gdk.Display): void;
+    /**
+     * Sets the scale to use when getting image assets for the style.
+     * @param scale - scale
+     */
     setScale(scale: number): void;
+    /**
+     * Sets the state to be used for style matching.
+     * @param flags - state to represent
+     */
     setState(flags: StateFlags): void;
+    /**
+     * Converts the style context into a string representation.
+     *
+     * The string representation always includes information about
+     * the name, state, id, visibility and style classes of the CSS
+     * node that is backing @context. Depending on the flags, more
+     * information may be included.
+     *
+     * This function is intended for testing and debugging of the
+     * CSS implementation in GTK. There are no guarantees about
+     * the format of the returned string, it may change.
+     * @param flags - Flags that determine what to print
+     */
     toString(flags: StyleContextPrintFlags): string;
     connect(signal: "notify", handler: (self: StyleContext, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtk/style-context.js

@@ -2,6 +2,45 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
 import * as Gdk from "../gdk/index.js";
+/**
+ * `GtkStyleContext` stores styling information affecting a widget.
+ *
+ * In order to construct the final style information, `GtkStyleContext`
+ * queries information from all attached `GtkStyleProviders`. Style
+ * providers can be either attached explicitly to the context through
+ * [method@Gtk.StyleContext.add_provider], or to the display through
+ * [func@Gtk.StyleContext.add_provider_for_display]. The resulting
+ * style is a combination of all providers’ information in priority order.
+ *
+ * For GTK widgets, any `GtkStyleContext` returned by
+ * [method@Gtk.Widget.get_style_context] will already have a `GdkDisplay`
+ * and RTL/LTR information set. The style context will also be updated
+ * automatically if any of these settings change on the widget.
+ *
+ * ## Style Classes
+ *
+ * Widgets can add style classes to their context, which can be used to associate
+ * different styles by class. The documentation for individual widgets lists
+ * which style classes it uses itself, and which style classes may be added by
+ * applications to affect their appearance.
+ *
+ * # Custom styling in UI libraries and applications
+ *
+ * If you are developing a library with custom widgets that render differently
+ * than standard components, you may need to add a `GtkStyleProvider` yourself
+ * with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK priority, either a
+ * `GtkCssProvider` or a custom object implementing the `GtkStyleProvider`
+ * interface. This way themes may still attempt to style your UI elements in
+ * a different way if needed so.
+ *
+ * If you are using custom styling on an applications, you probably want then
+ * to make your style information prevail to the theme’s, so you must use
+ * a `GtkStyleProvider` with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION
+ * priority, keep in mind that the user settings in
+ * `XDG_CONFIG_HOME/gtk-4.0/gtk.css` will
+ * still take precedence over your changes, as it uses the
+ * %GTK_STYLE_PROVIDER_PRIORITY_USER priority.
+ */
 export class StyleContext extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -17,6 +56,20 @@ export class StyleContext extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Adds a global style provider to @display, which will be used
+     * in style construction for all `GtkStyleContexts` under @display.
+     *
+     * GTK uses this to make styling information from `GtkSettings`
+     * available.
+     *
+     * Note: If both priorities are the same, A `GtkStyleProvider`
+     * added through [method@Gtk.StyleContext.add_provider] takes
+     * precedence over another added through this function.
+     * @param display - a `GdkDisplay`
+     * @param provider - a `GtkStyleProvider`
+     * @param priority - the priority of the style provider. The lower
+     */
     static addProviderForDisplay(display, provider, priority) {
         call("libgtk-4.so.1", "gtk_style_context_add_provider_for_display", [
             {
@@ -33,6 +86,11 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Removes `provider` from the global style providers list in @display.
+     * @param display - a `GdkDisplay`
+     * @param provider - a `GtkStyleProvider`
+     */
     static removeProviderForDisplay(display, provider) {
         call("libgtk-4.so.1", "gtk_style_context_remove_provider_for_display", [
             {
@@ -45,6 +103,24 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds a style class to @context, so later uses of the
+     * style context will make use of this new class for styling.
+     *
+     * In the CSS file format, a `GtkEntry` defining a “search”
+     * class, would be matched by:
+     *
+     * ```css
+     * entry.search { ... }
+     * ```
+     *
+     * While any widget defining a “search” class would be
+     * matched by:
+     * ```css
+     * .search { ... }
+     * ```
+     * @param className - class name to use in styling
+     */
     addClass(className) {
         call("libgtk-4.so.1", "gtk_style_context_add_class", [
             {
@@ -57,6 +133,20 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds a style provider to @context, to be used in style construction.
+     *
+     * Note that a style provider added by this function only affects
+     * the style of the widget to which `context` belongs. If you want
+     * to affect the style of all widgets, use
+     * [func@Gtk.StyleContext.add_provider_for_display].
+     *
+     * Note: If both priorities are the same, a `GtkStyleProvider`
+     * added through this function takes precedence over another added
+     * through [func@Gtk.StyleContext.add_provider_for_display].
+     * @param provider - a `GtkStyleProvider`
+     * @param priority - the priority of the style provider. The lower
+     */
     addProvider(provider, priority) {
         call("libgtk-4.so.1", "gtk_style_context_add_provider", [
             {
@@ -73,6 +163,10 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the border for a given state as a `GtkBorder`.
+     * @param border - return value for the border settings
+     */
     getBorder(border) {
         call("libgtk-4.so.1", "gtk_style_context_get_border", [
             {
@@ -92,6 +186,10 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the foreground color for a given state.
+     * @param color - return value for the foreground color
+     */
     getColor(color) {
         call("libgtk-4.so.1", "gtk_style_context_get_color", [
             {
@@ -111,6 +209,9 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns the `GdkDisplay` to which `context` is attached.
+     */
     getDisplay() {
         const ptr = call("libgtk-4.so.1", "gtk_style_context_get_display", [
             {
@@ -120,6 +221,10 @@ export class StyleContext extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Gdk.Display);
     }
+    /**
+     * Gets the margin for a given state as a `GtkBorder`.
+     * @param margin - return value for the margin settings
+     */
     getMargin(margin) {
         call("libgtk-4.so.1", "gtk_style_context_get_margin", [
             {
@@ -139,6 +244,10 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the padding for a given state as a `GtkBorder`.
+     * @param padding - return value for the padding settings
+     */
     getPadding(padding) {
         call("libgtk-4.so.1", "gtk_style_context_get_padding", [
             {
@@ -158,6 +267,9 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns the scale used for assets.
+     */
     getScale() {
         return call("libgtk-4.so.1", "gtk_style_context_get_scale", [
             {
@@ -166,6 +278,15 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns the state used for style matching.
+     *
+     * This method should only be used to retrieve the `GtkStateFlags`
+     * to pass to `GtkStyleContext` methods, like
+     * [method@Gtk.StyleContext.get_padding].
+     * If you need to retrieve the current state of a `GtkWidget`, use
+     * [method@Gtk.Widget.get_state_flags].
+     */
     getState() {
         return call("libgtk-4.so.1", "gtk_style_context_get_state", [
             {
@@ -174,6 +295,11 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns %TRUE if `context` currently has defined the
+     * given class name.
+     * @param className - a class name
+     */
     hasClass(className) {
         return call("libgtk-4.so.1", "gtk_style_context_has_class", [
             {
@@ -186,6 +312,11 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Looks up and resolves a color name in the `context` color map.
+     * @param colorName - color name to lookup
+     * @param color - Return location for the looked up color
+     */
     lookupColor(colorName, color) {
         return call("libgtk-4.so.1", "gtk_style_context_lookup_color", [
             {
@@ -209,6 +340,10 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Removes `class_name` from @context.
+     * @param className - class name to remove
+     */
     removeClass(className) {
         call("libgtk-4.so.1", "gtk_style_context_remove_class", [
             {
@@ -221,6 +356,10 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Removes `provider` from the style providers list in @context.
+     * @param provider - a `GtkStyleProvider`
+     */
     removeProvider(provider) {
         call("libgtk-4.so.1", "gtk_style_context_remove_provider", [
             {
@@ -233,6 +372,11 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Restores `context` state to a previous stage.
+     *
+     * See [method@Gtk.StyleContext.save].
+     */
     restore() {
         call("libgtk-4.so.1", "gtk_style_context_restore", [
             {
@@ -241,6 +385,18 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Saves the `context` state.
+     *
+     * This allows temporary modifications done through
+     * [method@Gtk.StyleContext.add_class],
+     * [method@Gtk.StyleContext.remove_class],
+     * [method@Gtk.StyleContext.set_state] to be quickly
+     * reverted in one go through [method@Gtk.StyleContext.restore].
+     *
+     * The matching call to [method@Gtk.StyleContext.restore]
+     * must be done before GTK returns to the main loop.
+     */
     save() {
         call("libgtk-4.so.1", "gtk_style_context_save", [
             {
@@ -249,6 +405,17 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Attaches `context` to the given display.
+     *
+     * The display is used to add style information from “global”
+     * style providers, such as the display's `GtkSettings` instance.
+     *
+     * If you are using a `GtkStyleContext` returned from
+     * [method@Gtk.Widget.get_style_context], you do not need to
+     * call this yourself.
+     * @param display - a `GdkDisplay`
+     */
     setDisplay(display) {
         call("libgtk-4.so.1", "gtk_style_context_set_display", [
             {
@@ -261,6 +428,10 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the scale to use when getting image assets for the style.
+     * @param scale - scale
+     */
     setScale(scale) {
         call("libgtk-4.so.1", "gtk_style_context_set_scale", [
             {
@@ -273,6 +444,10 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the state to be used for style matching.
+     * @param flags - state to represent
+     */
     setState(flags) {
         call("libgtk-4.so.1", "gtk_style_context_set_state", [
             {
@@ -285,6 +460,19 @@ export class StyleContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Converts the style context into a string representation.
+     *
+     * The string representation always includes information about
+     * the name, state, id, visibility and style classes of the CSS
+     * node that is backing @context. Depending on the flags, more
+     * information may be included.
+     *
+     * This function is intended for testing and debugging of the
+     * CSS implementation in GTK. There are no guarantees about
+     * the format of the returned string, it may change.
+     * @param flags - Flags that determine what to print
+     */
     toString(flags) {
         return call("libgtk-4.so.1", "gtk_style_context_to_string", [
             {

package/dist/generated/gtk/style-provider.d.ts

@@ -1,3 +1,13 @@
+/**
+ * An interface for style information used by [class@Gtk.StyleContext].
+ *
+ * See [method@Gtk.StyleContext.add_provider] and
+ * [func@Gtk.StyleContext.add_provider_for_display] for
+ * adding `GtkStyleProviders`.
+ *
+ * GTK uses the `GtkStyleProvider` implementation for CSS in
+ * [class@Gtk.CssProvider].
+ */
 export declare class StyleProvider {
     ptr: unknown;
     protected constructor(ptr: unknown);

package/dist/generated/gtk/style-provider.js

@@ -1,3 +1,13 @@
+/**
+ * An interface for style information used by [class@Gtk.StyleContext].
+ *
+ * See [method@Gtk.StyleContext.add_provider] and
+ * [func@Gtk.StyleContext.add_provider_for_display] for
+ * adding `GtkStyleProviders`.
+ *
+ * GTK uses the `GtkStyleProvider` implementation for CSS in
+ * [class@Gtk.CssProvider].
+ */
 export class StyleProvider {
     ptr;
     constructor(ptr) {