@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/header-bar.d.ts

@@ -1,18 +1,175 @@
 import * as GObject from "../gobject/index.js";
 import { Widget } from "./widget.js";
+/**
+ * Creates a custom titlebar for a window.
+ *
+ *
+ *
+ * `GtkHeaderBar` is similar to a horizontal `GtkCenterBox`. It allows
+ * children to be placed at the start or the end. In addition, it allows
+ * the window title to be displayed. The title will be centered with respect
+ * to the width of the box, even if the children at either side take up
+ * different amounts of space.
+ *
+ * `GtkHeaderBar` can add typical window frame controls, such as minimize,
+ * maximize and close buttons, or the window icon.
+ *
+ * For these reasons, `GtkHeaderBar` is the natural choice for use as the
+ * custom titlebar widget of a `GtkWindow` (see [method@Gtk.Window.set_titlebar]),
+ * as it gives features typical of titlebars while allowing the addition of
+ * child widgets.
+ *
+ * ## GtkHeaderBar as GtkBuildable
+ *
+ * The `GtkHeaderBar` implementation of the `GtkBuildable` interface supports
+ * adding children at the start or end sides by specifying “start” or “end” as
+ * the “type” attribute of a `<child>` element, or setting the title widget by
+ * specifying “title” value.
+ *
+ * By default the `GtkHeaderBar` uses a `GtkLabel` displaying the title of the
+ * window it is contained in as the title widget, equivalent to the following
+ * UI definition:
+ *
+ * ```xml
+ * <object class="GtkHeaderBar">
+ * <property name="title-widget">
+ * <object class="GtkLabel">
+ * <property name="label" translatable="yes">Label</property>
+ * <property name="single-line-mode">True</property>
+ * <property name="ellipsize">end</property>
+ * <property name="width-chars">5</property>
+ * <style>
+ * <class name="title"/>
+ * </style>
+ * </object>
+ * </property>
+ * </object>
+ * ```
+ *
+ * # CSS nodes
+ *
+ * ```
+ * headerbar
+ * ╰── windowhandle
+ * ╰── box
+ * ├── box.start
+ * │   ├── windowcontrols.start
+ * │   ╰── [other children]
+ * ├── [Title Widget]
+ * ╰── box.end
+ * ├── [other children]
+ * ╰── windowcontrols.end
+ * ```
+ *
+ * A `GtkHeaderBar`'s CSS node is called `headerbar`. It contains a `windowhandle`
+ * subnode, which contains a `box` subnode, which contains two `box` subnodes at
+ * the start and end of the header bar, as well as a center node that represents
+ * the title.
+ *
+ * Each of the boxes contains a `windowcontrols` subnode, see
+ * [class@Gtk.WindowControls] for details, as well as other children.
+ *
+ * # Accessibility
+ *
+ * `GtkHeaderBar` uses the [enum@Gtk.AccessibleRole.group] role.
+ */
 export declare class HeaderBar extends Widget {
+    /**
+     * Creates a new `GtkHeaderBar` widget.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the decoration layout of the header bar.
+     */
     getDecorationLayout(): string | null;
+    /**
+     * Returns whether this header bar shows the standard window
+     * title buttons.
+     */
     getShowTitleButtons(): boolean;
+    /**
+     * Retrieves the title widget of the header bar.
+     *
+     * See [method@Gtk.HeaderBar.set_title_widget].
+     */
     getTitleWidget(): Widget | null;
+    /**
+     * Returns whether this header bar shows platform
+     * native window controls.
+     */
     getUseNativeControls(): boolean;
+    /**
+     * Adds a child to the header bar, packed with reference to the end.
+     * @param child - the widget to be added to @bar
+     */
     packEnd(child: Widget): void;
+    /**
+     * Adds a child to the header bar, packed with reference to the start.
+     * @param child - the widget to be added to @bar
+     */
     packStart(child: Widget): void;
+    /**
+     * Removes a child from the header bar.
+     *
+     * The child must have been added with
+     * [method@Gtk.HeaderBar.pack_start],
+     * [method@Gtk.HeaderBar.pack_end] or
+     * [method@Gtk.HeaderBar.set_title_widget].
+     * @param child - the child to remove
+     */
     remove(child: Widget): void;
+    /**
+     * Sets the decoration layout for this header bar.
+     *
+     * This property overrides the
+     * [property@Gtk.Settings:gtk-decoration-layout] setting.
+     *
+     * There can be valid reasons for overriding the setting, such
+     * as a header bar design that does not allow for buttons to take
+     * room on the right, or only offers room for a single close button.
+     * Split header bars are another example for overriding the setting.
+     *
+     * The format of the string is button names, separated by commas.
+     * A colon separates the buttons that should appear on the left
+     * from those on the right. Recognized button names are minimize,
+     * maximize, close and icon (the window icon).
+     *
+     * For example, “icon:minimize,maximize,close” specifies an icon
+     * on the left, and minimize, maximize and close buttons on the right.
+     * @param layout - a decoration layout
+     */
     setDecorationLayout(layout?: string | null): void;
+    /**
+     * Sets whether this header bar shows the standard window
+     * title buttons.
+     * @param setting - true to show standard title buttons
+     */
     setShowTitleButtons(setting: boolean): void;
+    /**
+     * Sets the title for the header bar.
+     *
+     * When set to `NULL`, the headerbar will display the title of
+     * the window it is contained in.
+     *
+     * The title should help a user identify the current view.
+     * To achieve the same style as the builtin title, use the
+     * “title” style class.
+     *
+     * You should set the title widget to `NULL`, for the window
+     * title label to be visible again.
+     * @param titleWidget - a widget to use for a title
+     */
     setTitleWidget(titleWidget?: Widget | null): void;
+    /**
+     * Sets whether this header bar shows native window controls.
+     *
+     * This option shows the "stoplight" buttons on macOS.
+     * For Linux, this option has no effect.
+     *
+     * See also Using GTK on Apple macOS.
+     * @param setting - true to show native window controls
+     */
     setUseNativeControls(setting: boolean): void;
     connect(signal: "notify", handler: (self: HeaderBar, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtk/header-bar.js

@@ -1,7 +1,83 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Widget } from "./widget.js";
+/**
+ * Creates a custom titlebar for a window.
+ *
+ *
+ *
+ * `GtkHeaderBar` is similar to a horizontal `GtkCenterBox`. It allows
+ * children to be placed at the start or the end. In addition, it allows
+ * the window title to be displayed. The title will be centered with respect
+ * to the width of the box, even if the children at either side take up
+ * different amounts of space.
+ *
+ * `GtkHeaderBar` can add typical window frame controls, such as minimize,
+ * maximize and close buttons, or the window icon.
+ *
+ * For these reasons, `GtkHeaderBar` is the natural choice for use as the
+ * custom titlebar widget of a `GtkWindow` (see [method@Gtk.Window.set_titlebar]),
+ * as it gives features typical of titlebars while allowing the addition of
+ * child widgets.
+ *
+ * ## GtkHeaderBar as GtkBuildable
+ *
+ * The `GtkHeaderBar` implementation of the `GtkBuildable` interface supports
+ * adding children at the start or end sides by specifying “start” or “end” as
+ * the “type” attribute of a `<child>` element, or setting the title widget by
+ * specifying “title” value.
+ *
+ * By default the `GtkHeaderBar` uses a `GtkLabel` displaying the title of the
+ * window it is contained in as the title widget, equivalent to the following
+ * UI definition:
+ *
+ * ```xml
+ * <object class="GtkHeaderBar">
+ * <property name="title-widget">
+ * <object class="GtkLabel">
+ * <property name="label" translatable="yes">Label</property>
+ * <property name="single-line-mode">True</property>
+ * <property name="ellipsize">end</property>
+ * <property name="width-chars">5</property>
+ * <style>
+ * <class name="title"/>
+ * </style>
+ * </object>
+ * </property>
+ * </object>
+ * ```
+ *
+ * # CSS nodes
+ *
+ * ```
+ * headerbar
+ * ╰── windowhandle
+ * ╰── box
+ * ├── box.start
+ * │   ├── windowcontrols.start
+ * │   ╰── [other children]
+ * ├── [Title Widget]
+ * ╰── box.end
+ * ├── [other children]
+ * ╰── windowcontrols.end
+ * ```
+ *
+ * A `GtkHeaderBar`'s CSS node is called `headerbar`. It contains a `windowhandle`
+ * subnode, which contains a `box` subnode, which contains two `box` subnodes at
+ * the start and end of the header bar, as well as a center node that represents
+ * the title.
+ *
+ * Each of the boxes contains a `windowcontrols` subnode, see
+ * [class@Gtk.WindowControls] for details, as well as other children.
+ *
+ * # Accessibility
+ *
+ * `GtkHeaderBar` uses the [enum@Gtk.AccessibleRole.group] role.
+ */
 export class HeaderBar extends Widget {
+    /**
+     * Creates a new `GtkHeaderBar` widget.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -11,6 +87,9 @@ export class HeaderBar extends Widget {
             borrowed: true,
         });
     }
+    /**
+     * Gets the decoration layout of the header bar.
+     */
     getDecorationLayout() {
         return call("libgtk-4.so.1", "gtk_header_bar_get_decoration_layout", [
             {
@@ -19,6 +98,10 @@ export class HeaderBar extends Widget {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Returns whether this header bar shows the standard window
+     * title buttons.
+     */
     getShowTitleButtons() {
         return call("libgtk-4.so.1", "gtk_header_bar_get_show_title_buttons", [
             {
@@ -27,6 +110,11 @@ export class HeaderBar extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Retrieves the title widget of the header bar.
+     *
+     * See [method@Gtk.HeaderBar.set_title_widget].
+     */
     getTitleWidget() {
         const ptr = call("libgtk-4.so.1", "gtk_header_bar_get_title_widget", [
             {
@@ -38,6 +126,10 @@ export class HeaderBar extends Widget {
             return null;
         return getObject(ptr, Widget);
     }
+    /**
+     * Returns whether this header bar shows platform
+     * native window controls.
+     */
     getUseNativeControls() {
         return call("libgtk-4.so.1", "gtk_header_bar_get_use_native_controls", [
             {
@@ -46,6 +138,10 @@ export class HeaderBar extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Adds a child to the header bar, packed with reference to the end.
+     * @param child - the widget to be added to @bar
+     */
     packEnd(child) {
         call("libgtk-4.so.1", "gtk_header_bar_pack_end", [
             {
@@ -58,6 +154,10 @@ export class HeaderBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds a child to the header bar, packed with reference to the start.
+     * @param child - the widget to be added to @bar
+     */
     packStart(child) {
         call("libgtk-4.so.1", "gtk_header_bar_pack_start", [
             {
@@ -70,6 +170,15 @@ export class HeaderBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Removes a child from the header bar.
+     *
+     * The child must have been added with
+     * [method@Gtk.HeaderBar.pack_start],
+     * [method@Gtk.HeaderBar.pack_end] or
+     * [method@Gtk.HeaderBar.set_title_widget].
+     * @param child - the child to remove
+     */
     remove(child) {
         call("libgtk-4.so.1", "gtk_header_bar_remove", [
             {
@@ -82,6 +191,26 @@ export class HeaderBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the decoration layout for this header bar.
+     *
+     * This property overrides the
+     * [property@Gtk.Settings:gtk-decoration-layout] setting.
+     *
+     * There can be valid reasons for overriding the setting, such
+     * as a header bar design that does not allow for buttons to take
+     * room on the right, or only offers room for a single close button.
+     * Split header bars are another example for overriding the setting.
+     *
+     * The format of the string is button names, separated by commas.
+     * A colon separates the buttons that should appear on the left
+     * from those on the right. Recognized button names are minimize,
+     * maximize, close and icon (the window icon).
+     *
+     * For example, “icon:minimize,maximize,close” specifies an icon
+     * on the left, and minimize, maximize and close buttons on the right.
+     * @param layout - a decoration layout
+     */
     setDecorationLayout(layout) {
         call("libgtk-4.so.1", "gtk_header_bar_set_decoration_layout", [
             {
@@ -95,6 +224,11 @@ export class HeaderBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether this header bar shows the standard window
+     * title buttons.
+     * @param setting - true to show standard title buttons
+     */
     setShowTitleButtons(setting) {
         call("libgtk-4.so.1", "gtk_header_bar_set_show_title_buttons", [
             {
@@ -107,6 +241,20 @@ export class HeaderBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the title for the header bar.
+     *
+     * When set to `NULL`, the headerbar will display the title of
+     * the window it is contained in.
+     *
+     * The title should help a user identify the current view.
+     * To achieve the same style as the builtin title, use the
+     * “title” style class.
+     *
+     * You should set the title widget to `NULL`, for the window
+     * title label to be visible again.
+     * @param titleWidget - a widget to use for a title
+     */
     setTitleWidget(titleWidget) {
         call("libgtk-4.so.1", "gtk_header_bar_set_title_widget", [
             {
@@ -120,6 +268,15 @@ export class HeaderBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether this header bar shows native window controls.
+     *
+     * This option shows the "stoplight" buttons on macOS.
+     * For Linux, this option has no effect.
+     *
+     * See also Using GTK on Apple macOS.
+     * @param setting - true to show native window controls
+     */
     setUseNativeControls(setting) {
         call("libgtk-4.so.1", "gtk_header_bar_set_use_native_controls", [
             {

package/dist/generated/gtk/icon-paintable.d.ts

@@ -1,13 +1,60 @@
 import * as GObject from "../gobject/index.js";
 import * as Gdk from "../gdk/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * Contains information found when looking up an icon in `GtkIconTheme`
+ * or loading it from a file.
+ *
+ * `GtkIconPaintable` implements `GdkPaintable` and `GtkSymbolicPaintable`.
+ */
 export declare class IconPaintable extends GObject.GObject {
+    /**
+     * Creates a `GtkIconPaintable` for a file with a given size and scale.
+     *
+     * The icon can then be rendered by using it as a `GdkPaintable`.
+     * @param file - a `GFile`
+     * @param size - desired icon size, in application pixels
+     * @param scale - the desired scale
+     */
     constructor(file: Gio.File, size: number, scale: number);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Gets the `GFile` that was used to load the icon.
+     *
+     * Returns %NULL if the icon was not loaded from a file.
+     */
     getFile(): Gio.File | null;
+    /**
+     * Get the icon name being used for this icon.
+     *
+     * When an icon looked up in the icon theme was not available, the
+     * icon theme may use fallback icons - either those specified to
+     * gtk_icon_theme_lookup_icon() or the always-available
+     * "image-missing". The icon chosen is returned by this function.
+     *
+     * If the icon was created without an icon theme, this function
+     * returns %NULL.
+     */
     getIconName(): string | null;
+    /**
+     * Checks if the icon is symbolic or not.
+     *
+     * This currently uses only the file name and not the file contents
+     * for determining this. This behaviour may change in the future.
+     */
     isSymbolic(): boolean;
+    /**
+     * Snapshots the paintable with the given colors.
+     *
+     * If less than 4 colors are provided, GTK will pad the array with default
+     * colors.
+     * @param snapshot - a `GdkSnapshot` to snapshot to
+     * @param width - width to snapshot in
+     * @param height - height to snapshot in
+     * @param colors - a pointer to an array of colors
+     * @param nColors - The number of colors
+     */
     snapshotSymbolic(snapshot: Gdk.Snapshot, width: number, height: number, colors: Gdk.RGBA[], nColors: number): void;
     connect(signal: "notify", handler: (self: IconPaintable, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtk/icon-paintable.js

@@ -2,6 +2,12 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * Contains information found when looking up an icon in `GtkIconTheme`
+ * or loading it from a file.
+ *
+ * `GtkIconPaintable` implements `GdkPaintable` and `GtkSymbolicPaintable`.
+ */
 export class IconPaintable extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -23,6 +29,11 @@ export class IconPaintable extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets the `GFile` that was used to load the icon.
+     *
+     * Returns %NULL if the icon was not loaded from a file.
+     */
     getFile() {
         const ptr = call("libgtk-4.so.1", "gtk_icon_paintable_get_file", [
             {
@@ -34,6 +45,17 @@ export class IconPaintable extends GObject.GObject {
             return null;
         return getObject(ptr, Gio.File);
     }
+    /**
+     * Get the icon name being used for this icon.
+     *
+     * When an icon looked up in the icon theme was not available, the
+     * icon theme may use fallback icons - either those specified to
+     * gtk_icon_theme_lookup_icon() or the always-available
+     * "image-missing". The icon chosen is returned by this function.
+     *
+     * If the icon was created without an icon theme, this function
+     * returns %NULL.
+     */
     getIconName() {
         return call("libgtk-4.so.1", "gtk_icon_paintable_get_icon_name", [
             {
@@ -42,6 +64,12 @@ export class IconPaintable extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Checks if the icon is symbolic or not.
+     *
+     * This currently uses only the file name and not the file contents
+     * for determining this. This behaviour may change in the future.
+     */
     isSymbolic() {
         return call("libgtk-4.so.1", "gtk_icon_paintable_is_symbolic", [
             {
@@ -50,6 +78,17 @@ export class IconPaintable extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Snapshots the paintable with the given colors.
+     *
+     * If less than 4 colors are provided, GTK will pad the array with default
+     * colors.
+     * @param snapshot - a `GdkSnapshot` to snapshot to
+     * @param width - width to snapshot in
+     * @param height - height to snapshot in
+     * @param colors - a pointer to an array of colors
+     * @param nColors - The number of colors
+     */
     snapshotSymbolic(snapshot, width, height, colors, nColors) {
         call("libgtk-4.so.1", "gtk_symbolic_paintable_snapshot_symbolic", [
             {