@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -4,16 +4,85 @@ import { Widget } from "./widget.js";
 import * as GObject from "../gobject/index.js";
 import { Window } from "./window.js";
 export declare class Dialog extends Window {
+    /**
+     * Creates a new dialog box.
+     *
+     * Widgets should not be packed into the `GtkWindow`
+     * directly, but into the `content_area` and @action_area,
+     * as described above.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Adds an activatable widget to the action area of a `GtkDialog`.
+     *
+     * GTK connects a signal handler that will emit the
+     * [signal@Gtk.Dialog::response] signal on the dialog when the widget
+     * is activated. The widget is appended to the end of the dialog’s action
+     * area.
+     *
+     * If you want to add a non-activatable widget, simply pack it into
+     * the `action_area` field of the `GtkDialog` struct.
+     * @param child - an activatable widget
+     * @param responseId - response ID for @child
+     */
     addActionWidget(child: Widget, responseId: number): void;
+    /**
+     * Adds a button with the given text.
+     *
+     * GTK arranges things so that clicking the button will emit the
+     * [signal@Gtk.Dialog::response] signal with the given @response_id.
+     * The button is appended to the end of the dialog’s action area.
+     * The button widget is returned, but usually you don’t need it.
+     * @param buttonText - text of button
+     * @param responseId - response ID for the button
+     */
     addButton(buttonText: string, responseId: number): Widget;
+    /**
+     * Returns the content area of @dialog.
+     */
     getContentArea(): Box;
+    /**
+     * Returns the header bar of @dialog.
+     *
+     * Note that the headerbar is only used by the dialog if the
+     * [property@Gtk.Dialog:use-header-bar] property is %TRUE.
+     */
     getHeaderBar(): HeaderBar;
+    /**
+     * Gets the response id of a widget in the action area
+     * of a dialog.
+     * @param widget - a widget in the action area of @dialog
+     */
     getResponseForWidget(widget: Widget): number;
+    /**
+     * Gets the widget button that uses the given response ID in the action area
+     * of a dialog.
+     * @param responseId - the response ID used by the `dialog` widget
+     */
     getWidgetForResponse(responseId: number): Widget | null;
+    /**
+     * Emits the ::response signal with the given response ID.
+     *
+     * Used to indicate that the user has responded to the dialog in some way.
+     * @param responseId - response ID
+     */
     response(responseId: number): void;
+    /**
+     * Sets the default widget for the dialog based on the response ID.
+     *
+     * Pressing “Enter” normally activates the default widget.
+     * @param responseId - a response ID
+     */
     setDefaultResponse(responseId: number): void;
+    /**
+     * A convenient way to sensitize/desensitize dialog buttons.
+     *
+     * Calls `gtk_widget_set_sensitive (widget, @setting)`
+     * for each widget in the dialog’s action area with the given @response_id.
+     * @param responseId - a response ID
+     * @param setting - %TRUE for sensitive
+     */
     setResponseSensitive(responseId: number, setting: boolean): void;
     connect(signal: "close", handler: (self: Dialog) => void, after?: boolean): number;
     connect(signal: "response", handler: (self: Dialog, responseId: number) => void, after?: boolean): number;

package/dist/generated/gtk/dialog.js

@@ -4,6 +4,129 @@ import { Box } from "./box.js";
 import { HeaderBar } from "./header-bar.js";
 import { Widget } from "./widget.js";
 import { Window } from "./window.js";
+/**
+ * Dialogs are a convenient way to prompt the user for a small amount
+ * of input.
+ *
+ *
+ *
+ * Typical uses are to display a message, ask a question, or anything else
+ * that does not require extensive effort on the user’s part.
+ *
+ * The main area of a `GtkDialog` is called the "content area", and is yours
+ * to populate with widgets such a `GtkLabel` or `GtkEntry`, to present
+ * your information, questions, or tasks to the user.
+ *
+ * In addition, dialogs allow you to add "action widgets". Most commonly,
+ * action widgets are buttons. Depending on the platform, action widgets may
+ * be presented in the header bar at the top of the window, or at the bottom
+ * of the window. To add action widgets, create your `GtkDialog` using
+ * [ctor@Gtk.Dialog.new_with_buttons], or use
+ * [method@Gtk.Dialog.add_button], [method@Gtk.Dialog.add_buttons],
+ * or [method@Gtk.Dialog.add_action_widget].
+ *
+ * `GtkDialogs` uses some heuristics to decide whether to add a close
+ * button to the window decorations. If any of the action buttons use
+ * the response ID %GTK_RESPONSE_CLOSE or %GTK_RESPONSE_CANCEL, the
+ * close button is omitted.
+ *
+ * Clicking a button that was added as an action widget will emit the
+ * [signal@Gtk.Dialog::response] signal with a response ID that you specified.
+ * GTK will never assign a meaning to positive response IDs; these are
+ * entirely user-defined. But for convenience, you can use the response
+ * IDs in the [enum@Gtk.ResponseType] enumeration (these all have values
+ * less than zero). If a dialog receives a delete event, the
+ * [signal@Gtk.Dialog::response] signal will be emitted with the
+ * %GTK_RESPONSE_DELETE_EVENT response ID.
+ *
+ * Dialogs are created with a call to [ctor@Gtk.Dialog.new] or
+ * [ctor@Gtk.Dialog.new_with_buttons]. The latter is recommended; it allows
+ * you to set the dialog title, some convenient flags, and add buttons.
+ *
+ * A “modal” dialog (that is, one which freezes the rest of the application
+ * from user input), can be created by calling [method@Gtk.Window.set_modal]
+ * on the dialog. When using [ctor@Gtk.Dialog.new_with_buttons], you can also
+ * pass the %GTK_DIALOG_MODAL flag to make a dialog modal.
+ *
+ * For the simple dialog in the following example, a [class@Gtk.MessageDialog]
+ * would save some effort. But you’d need to create the dialog contents manually
+ * if you had more than a simple message in the dialog.
+ *
+ * An example for simple `GtkDialog` usage:
+ *
+ * ```c
+ * // Function to open a dialog box with a message
+ * void
+ * quick_message (GtkWindow *parent, char *message)
+ * {
+ * GtkWidget *dialog, *label, *content_area;
+ * GtkDialogFlags flags;
+ *
+ * // Create the widgets
+ * flags = GTK_DIALOG_DESTROY_WITH_PARENT;
+ * dialog = gtk_dialog_new_with_buttons ("Message",
+ * parent,
+ * flags,
+ * _("_OK"),
+ * GTK_RESPONSE_NONE,
+ * NULL);
+ * content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog));
+ * label = gtk_label_new (message);
+ *
+ * // Ensure that the dialog box is destroyed when the user responds
+ *
+ * g_signal_connect_swapped (dialog,
+ * "response",
+ * G_CALLBACK (gtk_window_destroy),
+ * dialog);
+ *
+ * // Add the label, and show everything we’ve added
+ *
+ * gtk_box_append (GTK_BOX (content_area), label);
+ * gtk_widget_show (dialog);
+ * }
+ * ```
+ *
+ * # GtkDialog as GtkBuildable
+ *
+ * The `GtkDialog` implementation of the `GtkBuildable` interface exposes the
+ * `content_area` as an internal child with the name “content_area”.
+ *
+ * `GtkDialog` supports a custom `<action-widgets>` element, which can contain
+ * multiple `<action-widget>` elements. The “response” attribute specifies a
+ * numeric response, and the content of the element is the id of widget
+ * (which should be a child of the dialogs @action_area). To mark a response
+ * as default, set the “default” attribute of the `<action-widget>` element
+ * to true.
+ *
+ * `GtkDialog` supports adding action widgets by specifying “action” as
+ * the “type” attribute of a `<child>` element. The widget will be added
+ * either to the action area or the headerbar of the dialog, depending
+ * on the “use-header-bar” property. The response id has to be associated
+ * with the action widget using the `<action-widgets>` element.
+ *
+ * An example of a `GtkDialog` UI definition fragment:
+ *
+ * ```xml
+ * <object class="GtkDialog" id="dialog1">
+ * <child type="action">
+ * <object class="GtkButton" id="button_cancel"/>
+ * </child>
+ * <child type="action">
+ * <object class="GtkButton" id="button_ok">
+ * </object>
+ * </child>
+ * <action-widgets>
+ * <action-widget response="cancel">button_cancel</action-widget>
+ * <action-widget response="ok" default="true">button_ok</action-widget>
+ * </action-widgets>
+ * </object>
+ * ```
+ *
+ * # Accessibility
+ *
+ * `GtkDialog` uses the %GTK_ACCESSIBLE_ROLE_DIALOG role.
+ */
 const SIGNAL_META = {
     close: { params: [], returnType: { type: "undefined" } },
     response: {
@@ -20,6 +143,13 @@ const SIGNAL_META = {
     "keys-changed": { params: [], returnType: { type: "undefined" } },
 };
 export class Dialog extends Window {
+    /**
+     * Creates a new dialog box.
+     *
+     * Widgets should not be packed into the `GtkWindow`
+     * directly, but into the `content_area` and @action_area,
+     * as described above.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -29,6 +159,19 @@ export class Dialog extends Window {
             borrowed: true,
         });
     }
+    /**
+     * Adds an activatable widget to the action area of a `GtkDialog`.
+     *
+     * GTK connects a signal handler that will emit the
+     * [signal@Gtk.Dialog::response] signal on the dialog when the widget
+     * is activated. The widget is appended to the end of the dialog’s action
+     * area.
+     *
+     * If you want to add a non-activatable widget, simply pack it into
+     * the `action_area` field of the `GtkDialog` struct.
+     * @param child - an activatable widget
+     * @param responseId - response ID for @child
+     */
     addActionWidget(child, responseId) {
         call("libgtk-4.so.1", "gtk_dialog_add_action_widget", [
             {
@@ -45,6 +188,16 @@ export class Dialog extends Window {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds a button with the given text.
+     *
+     * GTK arranges things so that clicking the button will emit the
+     * [signal@Gtk.Dialog::response] signal with the given @response_id.
+     * The button is appended to the end of the dialog’s action area.
+     * The button widget is returned, but usually you don’t need it.
+     * @param buttonText - text of button
+     * @param responseId - response ID for the button
+     */
     addButton(buttonText, responseId) {
         const ptr = call("libgtk-4.so.1", "gtk_dialog_add_button", [
             {
@@ -62,6 +215,9 @@ export class Dialog extends Window {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Widget);
     }
+    /**
+     * Returns the content area of @dialog.
+     */
     getContentArea() {
         const ptr = call("libgtk-4.so.1", "gtk_dialog_get_content_area", [
             {
@@ -71,6 +227,12 @@ export class Dialog extends Window {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Box);
     }
+    /**
+     * Returns the header bar of @dialog.
+     *
+     * Note that the headerbar is only used by the dialog if the
+     * [property@Gtk.Dialog:use-header-bar] property is %TRUE.
+     */
     getHeaderBar() {
         const ptr = call("libgtk-4.so.1", "gtk_dialog_get_header_bar", [
             {
@@ -80,6 +242,11 @@ export class Dialog extends Window {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, HeaderBar);
     }
+    /**
+     * Gets the response id of a widget in the action area
+     * of a dialog.
+     * @param widget - a widget in the action area of @dialog
+     */
     getResponseForWidget(widget) {
         return call("libgtk-4.so.1", "gtk_dialog_get_response_for_widget", [
             {
@@ -92,6 +259,11 @@ export class Dialog extends Window {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the widget button that uses the given response ID in the action area
+     * of a dialog.
+     * @param responseId - the response ID used by the `dialog` widget
+     */
     getWidgetForResponse(responseId) {
         const ptr = call("libgtk-4.so.1", "gtk_dialog_get_widget_for_response", [
             {
@@ -107,6 +279,12 @@ export class Dialog extends Window {
             return null;
         return getObject(ptr, Widget);
     }
+    /**
+     * Emits the ::response signal with the given response ID.
+     *
+     * Used to indicate that the user has responded to the dialog in some way.
+     * @param responseId - response ID
+     */
     response(responseId) {
         call("libgtk-4.so.1", "gtk_dialog_response", [
             {
@@ -119,6 +297,12 @@ export class Dialog extends Window {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the default widget for the dialog based on the response ID.
+     *
+     * Pressing “Enter” normally activates the default widget.
+     * @param responseId - a response ID
+     */
     setDefaultResponse(responseId) {
         call("libgtk-4.so.1", "gtk_dialog_set_default_response", [
             {
@@ -131,6 +315,14 @@ export class Dialog extends Window {
             },
         ], { type: "undefined" });
     }
+    /**
+     * A convenient way to sensitize/desensitize dialog buttons.
+     *
+     * Calls `gtk_widget_set_sensitive (widget, @setting)`
+     * for each widget in the dialog’s action area with the given @response_id.
+     * @param responseId - a response ID
+     * @param setting - %TRUE for sensitive
+     */
     setResponseSensitive(responseId, setting) {
         call("libgtk-4.so.1", "gtk_dialog_set_response_sensitive", [
             {

package/dist/generated/gtk/directory-list.d.ts

@@ -1,19 +1,120 @@
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * A list model that wraps [method@Gio.File.enumerate_children_async].
+ *
+ * It presents a `GListModel` and fills it asynchronously with the `GFileInfo`s
+ * returned from that function.
+ *
+ * Enumeration will start automatically when the
+ * [property@Gtk.DirectoryList:file] property is set.
+ *
+ * While the `GtkDirectoryList` is being filled, the
+ * [property@Gtk.DirectoryList:loading] property will be set to %TRUE. You can
+ * listen to that property if you want to show information like a `GtkSpinner`
+ * or a "Loading..." text.
+ *
+ * If loading fails at any point, the [property@Gtk.DirectoryList:error]
+ * property will be set to give more indication about the failure.
+ *
+ * The `GFileInfo`s returned from a `GtkDirectoryList` have the "standard::file"
+ * attribute set to the `GFile` they refer to. This way you can get at the file
+ * that is referred to in the same way you would via g_file_enumerator_get_child().
+ * This means you do not need access to the `GtkDirectoryList`, but can access
+ * the `GFile` directly from the `GFileInfo` when operating with a `GtkListView`
+ * or similar.
+ */
 export declare class DirectoryList extends GObject.GObject {
+    /**
+     * Creates a new `GtkDirectoryList`.
+     *
+     * The `GtkDirectoryList` is querying the given `file` with the given @attributes.
+     * @param attributes - The attributes to query with
+     * @param file - The file to query
+     */
     constructor(attributes?: string | null, file?: Gio.File | null);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Gets the attributes queried on the children.
+     */
     getAttributes(): string | null;
+    /**
+     * Gets the loading error, if any.
+     *
+     * If an error occurs during the loading process, the loading process
+     * will finish and this property allows querying the error that happened.
+     * This error will persist until a file is loaded again.
+     *
+     * An error being set does not mean that no files were loaded, and all
+     * successfully queried files will remain in the list.
+     */
     getError(): GLib.GError | null;
+    /**
+     * Gets the file whose children are currently enumerated.
+     */
     getFile(): Gio.File | null;
+    /**
+     * Gets the IO priority set via gtk_directory_list_set_io_priority().
+     */
     getIoPriority(): number;
+    /**
+     * Returns whether the directory list is monitoring
+     * the directory for changes.
+     */
     getMonitored(): boolean;
+    /**
+     * Returns %TRUE if the children enumeration is currently in
+     * progress.
+     *
+     * Files will be added to `self` from time to time while loading is
+     * going on. The order in which are added is undefined and may change
+     * in between runs.
+     */
     isLoading(): boolean;
+    /**
+     * Sets the `attributes` to be enumerated and starts the enumeration.
+     *
+     * If `attributes` is %NULL, the list of file infos will still be created, it will just
+     * not contain any extra attributes.
+     * @param attributes - the attributes to enumerate
+     */
     setAttributes(attributes?: string | null): void;
+    /**
+     * Sets the `file` to be enumerated and starts the enumeration.
+     *
+     * If `file` is %NULL, the result will be an empty list.
+     * @param file - the `GFile` to be enumerated
+     */
     setFile(file?: Gio.File | null): void;
+    /**
+     * Sets the IO priority to use while loading directories.
+     *
+     * Setting the priority while `self` is loading will reprioritize the
+     * ongoing load as soon as possible.
+     *
+     * The default IO priority is %G_PRIORITY_DEFAULT, which is higher than
+     * the GTK redraw priority. If you are loading a lot of directories in
+     * parallel, lowering it to something like %G_PRIORITY_DEFAULT_IDLE
+     * may increase responsiveness.
+     * @param ioPriority - IO priority to use
+     */
     setIoPriority(ioPriority: number): void;
+    /**
+     * Sets whether the directory list will monitor the directory
+     * for changes.
+     *
+     * If monitoring is enabled, the ::items-changed signal will
+     * be emitted when the directory contents change.
+     *
+     *
+     * When monitoring is turned on after the initial creation
+     * of the directory list, the directory is reloaded to avoid
+     * missing files that appeared between the initial loading
+     * and when monitoring was turned on.
+     * @param monitored - %TRUE to monitor the directory for changes
+     */
     setMonitored(monitored: boolean): void;
     connect(signal: "notify", handler: (self: DirectoryList, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtk/directory-list.js

@@ -3,6 +3,30 @@ import { getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * A list model that wraps [method@Gio.File.enumerate_children_async].
+ *
+ * It presents a `GListModel` and fills it asynchronously with the `GFileInfo`s
+ * returned from that function.
+ *
+ * Enumeration will start automatically when the
+ * [property@Gtk.DirectoryList:file] property is set.
+ *
+ * While the `GtkDirectoryList` is being filled, the
+ * [property@Gtk.DirectoryList:loading] property will be set to %TRUE. You can
+ * listen to that property if you want to show information like a `GtkSpinner`
+ * or a "Loading..." text.
+ *
+ * If loading fails at any point, the [property@Gtk.DirectoryList:error]
+ * property will be set to give more indication about the failure.
+ *
+ * The `GFileInfo`s returned from a `GtkDirectoryList` have the "standard::file"
+ * attribute set to the `GFile` they refer to. This way you can get at the file
+ * that is referred to in the same way you would via g_file_enumerator_get_child().
+ * This means you do not need access to the `GtkDirectoryList`, but can access
+ * the `GFile` directly from the `GFileInfo` when operating with a `GtkListView`
+ * or similar.
+ */
 export class DirectoryList extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -22,6 +46,9 @@ export class DirectoryList extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets the attributes queried on the children.
+     */
     getAttributes() {
         return call("libgtk-4.so.1", "gtk_directory_list_get_attributes", [
             {
@@ -30,6 +57,16 @@ export class DirectoryList extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the loading error, if any.
+     *
+     * If an error occurs during the loading process, the loading process
+     * will finish and this property allows querying the error that happened.
+     * This error will persist until a file is loaded again.
+     *
+     * An error being set does not mean that no files were loaded, and all
+     * successfully queried files will remain in the list.
+     */
     getError() {
         const ptr = call("libgtk-4.so.1", "gtk_directory_list_get_error", [
             {
@@ -46,6 +83,9 @@ export class DirectoryList extends GObject.GObject {
             return null;
         return getObject(ptr, GLib.GError);
     }
+    /**
+     * Gets the file whose children are currently enumerated.
+     */
     getFile() {
         const ptr = call("libgtk-4.so.1", "gtk_directory_list_get_file", [
             {
@@ -57,6 +97,9 @@ export class DirectoryList extends GObject.GObject {
             return null;
         return getObject(ptr, Gio.File);
     }
+    /**
+     * Gets the IO priority set via gtk_directory_list_set_io_priority().
+     */
     getIoPriority() {
         return call("libgtk-4.so.1", "gtk_directory_list_get_io_priority", [
             {
@@ -65,6 +108,10 @@ export class DirectoryList extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns whether the directory list is monitoring
+     * the directory for changes.
+     */
     getMonitored() {
         return call("libgtk-4.so.1", "gtk_directory_list_get_monitored", [
             {
@@ -73,6 +120,14 @@ export class DirectoryList extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns %TRUE if the children enumeration is currently in
+     * progress.
+     *
+     * Files will be added to `self` from time to time while loading is
+     * going on. The order in which are added is undefined and may change
+     * in between runs.
+     */
     isLoading() {
         return call("libgtk-4.so.1", "gtk_directory_list_is_loading", [
             {
@@ -81,6 +136,13 @@ export class DirectoryList extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Sets the `attributes` to be enumerated and starts the enumeration.
+     *
+     * If `attributes` is %NULL, the list of file infos will still be created, it will just
+     * not contain any extra attributes.
+     * @param attributes - the attributes to enumerate
+     */
     setAttributes(attributes) {
         call("libgtk-4.so.1", "gtk_directory_list_set_attributes", [
             {
@@ -94,6 +156,12 @@ export class DirectoryList extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the `file` to be enumerated and starts the enumeration.
+     *
+     * If `file` is %NULL, the result will be an empty list.
+     * @param file - the `GFile` to be enumerated
+     */
     setFile(file) {
         call("libgtk-4.so.1", "gtk_directory_list_set_file", [
             {
@@ -107,6 +175,18 @@ export class DirectoryList extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the IO priority to use while loading directories.
+     *
+     * Setting the priority while `self` is loading will reprioritize the
+     * ongoing load as soon as possible.
+     *
+     * The default IO priority is %G_PRIORITY_DEFAULT, which is higher than
+     * the GTK redraw priority. If you are loading a lot of directories in
+     * parallel, lowering it to something like %G_PRIORITY_DEFAULT_IDLE
+     * may increase responsiveness.
+     * @param ioPriority - IO priority to use
+     */
     setIoPriority(ioPriority) {
         call("libgtk-4.so.1", "gtk_directory_list_set_io_priority", [
             {
@@ -119,6 +199,20 @@ export class DirectoryList extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the directory list will monitor the directory
+     * for changes.
+     *
+     * If monitoring is enabled, the ::items-changed signal will
+     * be emitted when the directory contents change.
+     *
+     *
+     * When monitoring is turned on after the initial creation
+     * of the directory list, the directory is reloaded to avoid
+     * missing files that appeared between the initial loading
+     * and when monitoring was turned on.
+     * @param monitored - %TRUE to monitor the directory for changes
+     */
     setMonitored(monitored) {
         call("libgtk-4.so.1", "gtk_directory_list_set_monitored", [
             {