@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/password-entry.js

@@ -3,10 +3,47 @@ import { getObject } from "@gtkx/ffi";
 import { Editable } from "./editable.js";
 import * as Gio from "../gio/index.js";
 import { Widget } from "./widget.js";
+/**
+ * A single-line text entry widget for entering passwords and other secrets.
+ *
+ *
+ *
+ * It does not show its contents in clear text, does not allow to copy it
+ * to the clipboard, and it shows a warning when Caps Lock is engaged. If
+ * the underlying platform allows it, `GtkPasswordEntry` will also place
+ * the text in a non-pageable memory area, to avoid it being written out
+ * to disk by the operating system.
+ *
+ * Optionally, it can offer a way to reveal the contents in clear text.
+ *
+ * `GtkPasswordEntry` provides only minimal API and should be used with
+ * the [iface@Gtk.Editable] API.
+ *
+ * # CSS Nodes
+ *
+ * ```
+ * entry.password
+ * ╰── text
+ * ├── image.caps-lock-indicator
+ * ┊
+ * ```
+ *
+ * `GtkPasswordEntry` has a single CSS node with name entry that carries
+ * a .passwordstyle class. The text Css node below it has a child with
+ * name image and style class .caps-lock-indicator for the Caps Lock
+ * icon, and possibly other children.
+ *
+ * # Accessibility
+ *
+ * `GtkPasswordEntry` uses the [enum@Gtk.AccessibleRole.text_box] role.
+ */
 const SIGNAL_META = {
     activate: { params: [], returnType: { type: "undefined" } },
 };
 export class PasswordEntry extends Widget {
+    /**
+     * Creates a `GtkPasswordEntry`.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -16,6 +53,9 @@ export class PasswordEntry extends Widget {
             borrowed: true,
         });
     }
+    /**
+     * Gets the menu model set with gtk_password_entry_set_extra_menu().
+     */
     getExtraMenu() {
         const ptr = call("libgtk-4.so.1", "gtk_password_entry_get_extra_menu", [
             {
@@ -27,6 +67,10 @@ export class PasswordEntry extends Widget {
             return null;
         return getObject(ptr, Gio.MenuModel);
     }
+    /**
+     * Returns whether the entry is showing an icon to
+     * reveal the contents.
+     */
     getShowPeekIcon() {
         return call("libgtk-4.so.1", "gtk_password_entry_get_show_peek_icon", [
             {
@@ -35,6 +79,11 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Sets a menu model to add when constructing
+     * the context menu for @entry.
+     * @param model - a `GMenuModel`
+     */
     setExtraMenu(model) {
         call("libgtk-4.so.1", "gtk_password_entry_set_extra_menu", [
             {
@@ -48,6 +97,13 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the entry should have a clickable icon
+     * to reveal the contents.
+     *
+     * Setting this to %FALSE also hides the text again.
+     * @param showPeekIcon - whether to show the peek icon
+     */
     setShowPeekIcon(showPeekIcon) {
         call("libgtk-4.so.1", "gtk_password_entry_set_show_peek_icon", [
             {
@@ -60,6 +116,41 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Retrieves the accessible platform state from the editable delegate.
+     *
+     * This is an helper function to retrieve the accessible state for
+     * `GtkEditable` interface implementations using a delegate pattern.
+     *
+     * You should call this function in your editable widget implementation
+     * of the [vfunc@Gtk.Accessible.get_platform_state] virtual function, for
+     * instance:
+     *
+     * ```c
+     * static void
+     * accessible_interface_init (GtkAccessibleInterface *iface)
+     * {
+     * iface->get_platform_state = your_editable_get_accessible_platform_state;
+     * }
+     *
+     * static gboolean
+     * your_editable_get_accessible_platform_state (GtkAccessible *accessible,
+     * GtkAccessiblePlatformState state)
+     * {
+     * return gtk_editable_delegate_get_accessible_platform_state (GTK_EDITABLE (accessible), state);
+     * }
+     * ```
+     *
+     * Note that the widget which is the delegate *must* be a direct child of
+     * this widget, otherwise your implementation of [vfunc@Gtk.Accessible.get_platform_state]
+     * might not even be called, as the platform change will originate from
+     * the parent of the delegate, and, as a result, will not work properly.
+     *
+     * So, if you can't ensure the direct child condition, you should give the
+     * delegate the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role, or you can
+     * change your tree to allow this function to work.
+     * @param state - what kind of accessible state to retrieve
+     */
     delegateGetAccessiblePlatformState(state) {
         return call("libgtk-4.so.1", "gtk_editable_delegate_get_accessible_platform_state", [
             {
@@ -72,6 +163,11 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Deletes the currently selected text of the editable.
+     *
+     * This call doesn’t do anything if there is no selected text.
+     */
     deleteSelection() {
         call("libgtk-4.so.1", "gtk_editable_delete_selection", [
             {
@@ -80,6 +176,18 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Deletes a sequence of characters.
+     *
+     * The characters that are deleted are those characters at positions
+     * from `start_pos` up to, but not including @end_pos. If `end_pos` is
+     * negative, then the characters deleted are those from `start_pos` to
+     * the end of the text.
+     *
+     * Note that the positions are specified in characters, not bytes.
+     * @param startPos - start position
+     * @param endPos - end position
+     */
     deleteText(startPos, endPos) {
         call("libgtk-4.so.1", "gtk_editable_delete_text", [
             {
@@ -96,6 +204,12 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Undoes the setup done by [method@Gtk.Editable.init_delegate].
+     *
+     * This is a helper function that should be called from dispose,
+     * before removing the delegate object.
+     */
     finishDelegate() {
         call("libgtk-4.so.1", "gtk_editable_finish_delegate", [
             {
@@ -104,6 +218,9 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the alignment of the editable.
+     */
     getAlignment() {
         return call("libgtk-4.so.1", "gtk_editable_get_alignment", [
             {
@@ -112,6 +229,18 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "float", size: 32 });
     }
+    /**
+     * Retrieves a sequence of characters.
+     *
+     * The characters that are retrieved are those characters at positions
+     * from `start_pos` up to, but not including @end_pos. If `end_pos` is negative,
+     * then the characters retrieved are those characters from `start_pos` to
+     * the end of the text.
+     *
+     * Note that positions are specified in characters, not bytes.
+     * @param startPos - start of text
+     * @param endPos - end of text
+     */
     getChars(startPos, endPos) {
         return call("libgtk-4.so.1", "gtk_editable_get_chars", [
             {
@@ -128,6 +257,12 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "string" });
     }
+    /**
+     * Gets the `GtkEditable` that `editable` is delegating its
+     * implementation to.
+     *
+     * Typically, the delegate is a [class@Gtk.Text] widget.
+     */
     getDelegate() {
         const ptr = call("libgtk-4.so.1", "gtk_editable_get_delegate", [
             {
@@ -139,6 +274,9 @@ export class PasswordEntry extends Widget {
             return null;
         return getObject(ptr, Editable);
     }
+    /**
+     * Retrieves whether `editable` is editable.
+     */
     getEditable() {
         return call("libgtk-4.so.1", "gtk_editable_get_editable", [
             {
@@ -147,6 +285,9 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets if undo/redo actions are enabled for @editable
+     */
     getEnableUndo() {
         return call("libgtk-4.so.1", "gtk_editable_get_enable_undo", [
             {
@@ -155,6 +296,9 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Retrieves the desired maximum width of @editable, in characters.
+     */
     getMaxWidthChars() {
         return call("libgtk-4.so.1", "gtk_editable_get_max_width_chars", [
             {
@@ -163,6 +307,12 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Retrieves the current position of the cursor relative
+     * to the start of the content of the editable.
+     *
+     * Note that this position is in characters, not in bytes.
+     */
     getPosition() {
         return call("libgtk-4.so.1", "gtk_editable_get_position", [
             {
@@ -171,6 +321,17 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Retrieves the selection bound of the editable.
+     *
+     * `start_pos` will be filled with the start of the selection and
+     * `end_pos` with end. If no text was selected both will be identical
+     * and %FALSE will be returned.
+     *
+     * Note that positions are specified in characters, not bytes.
+     * @param startPos - location to store the starting position
+     * @param endPos - location to store the end position
+     */
     getSelectionBounds(startPos, endPos) {
         return call("libgtk-4.so.1", "gtk_editable_get_selection_bounds", [
             {
@@ -195,6 +356,11 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Retrieves the contents of @editable.
+     *
+     * The returned string is owned by GTK and must not be modified or freed.
+     */
     getText() {
         return call("libgtk-4.so.1", "gtk_editable_get_text", [
             {
@@ -203,6 +369,10 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the number of characters of space reserved
+     * for the contents of the editable.
+     */
     getWidthChars() {
         return call("libgtk-4.so.1", "gtk_editable_get_width_chars", [
             {
@@ -211,6 +381,15 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Sets up a delegate for `GtkEditable`.
+     *
+     * This is assuming that the get_delegate vfunc in the `GtkEditable`
+     * interface has been set up for the @editable's type.
+     *
+     * This is a helper function that should be called in instance init,
+     * after creating the delegate object.
+     */
     initDelegate() {
         call("libgtk-4.so.1", "gtk_editable_init_delegate", [
             {
@@ -219,6 +398,17 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Inserts `length` bytes of `text` into the contents of the
+     * widget, at position @position.
+     *
+     * Note that the position is in characters, not in bytes.
+     * The function updates `position` to point after the newly
+     * inserted text.
+     * @param text - the text to insert
+     * @param length - the length of the text in bytes, or -1
+     * @param position - location of the position text will be inserted at
+     */
     insertText(text, length, position) {
         call("libgtk-4.so.1", "gtk_editable_insert_text", [
             {
@@ -242,6 +432,18 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Selects a region of text.
+     *
+     * The characters that are selected are those characters at positions
+     * from `start_pos` up to, but not including @end_pos. If `end_pos` is
+     * negative, then the characters selected are those characters from
+     * `start_pos` to  the end of the text.
+     *
+     * Note that positions are specified in characters, not bytes.
+     * @param startPos - start of region
+     * @param endPos - end of region
+     */
     selectRegion(startPos, endPos) {
         call("libgtk-4.so.1", "gtk_editable_select_region", [
             {
@@ -258,6 +460,13 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the alignment for the contents of the editable.
+     *
+     * This controls the horizontal positioning of the contents when
+     * the displayed text is shorter than the width of the editable.
+     * @param xalign - The horizontal alignment, from 0 (left) to 1 (right).
+     */
     setAlignment(xalign) {
         call("libgtk-4.so.1", "gtk_editable_set_alignment", [
             {
@@ -270,6 +479,10 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Determines if the user can edit the text in the editable widget.
+     * @param isEditable - %TRUE if the user is allowed to edit the text
+     */
     setEditable(isEditable) {
         call("libgtk-4.so.1", "gtk_editable_set_editable", [
             {
@@ -282,6 +495,15 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * If enabled, changes to `editable` will be saved for undo/redo
+     * actions.
+     *
+     * This results in an additional copy of text changes and are not
+     * stored in secure memory. As such, undo is forcefully disabled
+     * when [property@Gtk.Text:visibility] is set to %FALSE.
+     * @param enableUndo - if undo/redo should be enabled
+     */
     setEnableUndo(enableUndo) {
         call("libgtk-4.so.1", "gtk_editable_set_enable_undo", [
             {
@@ -294,6 +516,10 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the desired maximum width in characters of @editable.
+     * @param nChars - the new desired maximum width, in characters
+     */
     setMaxWidthChars(nChars) {
         call("libgtk-4.so.1", "gtk_editable_set_max_width_chars", [
             {
@@ -306,6 +532,16 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the cursor position in the editable to the given value.
+     *
+     * The cursor is displayed before the character with the given (base 0)
+     * index in the contents of the editable. The value must be less than
+     * or equal to the number of characters in the editable. A value of -1
+     * indicates that the position should be set after the last character
+     * of the editable. Note that `position` is in characters, not in bytes.
+     * @param position - the position of the cursor
+     */
     setPosition(position) {
         call("libgtk-4.so.1", "gtk_editable_set_position", [
             {
@@ -318,6 +554,12 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the text in the editable to the given value.
+     *
+     * This is replacing the current contents.
+     * @param text - the text to set
+     */
     setText(text) {
         call("libgtk-4.so.1", "gtk_editable_set_text", [
             {
@@ -330,6 +572,15 @@ export class PasswordEntry extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Changes the size request of the editable to be about the
+     * right size for `n_chars` characters.
+     *
+     * Note that it changes the size request, the size can still
+     * be affected by how you pack the widget into containers.
+     * If `n_chars` is -1, the size reverts to the default size.
+     * @param nChars - width in chars
+     */
     setWidthChars(nChars) {
         call("libgtk-4.so.1", "gtk_editable_set_width_chars", [
             {

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

@@ -4,28 +4,232 @@ import * as Gdk from "../gdk/index.js";
 import * as GdkPixbuf from "../gdkpixbuf/index.js";
 import * as Gio from "../gio/index.js";
 import { Widget } from "./widget.js";
+/**
+ * Displays a `GdkPaintable`.
+ *
+ *
+ *
+ * Many convenience functions are provided to make pictures simple to use.
+ * For example, if you want to load an image from a file, and then display
+ * it, there’s a convenience function to do this:
+ *
+ * ```c
+ * GtkWidget *widget = gtk_picture_new_for_filename ("myfile.png");
+ * ```
+ *
+ * If the file isn’t loaded successfully, the picture will contain a
+ * “broken image” icon similar to that used in many web browsers.
+ * If you want to handle errors in loading the file yourself,
+ * for example by displaying an error message, then load the image with
+ * and image loading framework such as libglycin, then create the `GtkPicture`
+ * with [ctor@Gtk.Picture.new_for_paintable].
+ *
+ * Sometimes an application will want to avoid depending on external data
+ * files, such as image files. See the documentation of `GResource` for details.
+ * In this case, [ctor@Gtk.Picture.new_for_resource] and
+ * [method@Gtk.Picture.set_resource] should be used.
+ *
+ * `GtkPicture` displays an image at its natural size. See [class@Gtk.Image]
+ * if you want to display a fixed-size image, such as an icon.
+ *
+ * ## Sizing the paintable
+ *
+ * You can influence how the paintable is displayed inside the `GtkPicture`
+ * by changing [property@Gtk.Picture:content-fit]. See [enum@Gtk.ContentFit]
+ * for details. [property@Gtk.Picture:can-shrink] can be unset to make sure
+ * that paintables are never made smaller than their ideal size - but
+ * be careful if you do not know the size of the paintable in use (like
+ * when displaying user-loaded images). This can easily cause the picture to
+ * grow larger than the screen. And [property@Gtk.Widget:halign] and
+ * [property@Gtk.Widget:valign] can be used to make sure the paintable doesn't
+ * fill all available space but is instead displayed at its original size.
+ *
+ * ## CSS nodes
+ *
+ * `GtkPicture` has a single CSS node with the name `picture`.
+ *
+ * ## Accessibility
+ *
+ * `GtkPicture` uses the [enum@Gtk.AccessibleRole.img] role.
+ */
 export declare class Picture extends Widget {
+    /**
+     * Creates a new empty `GtkPicture` widget.
+     */
     constructor(...args: unknown[]);
+    /**
+     * Creates a new `GtkPicture` displaying the given @file.
+     *
+     * If the file isn’t found or can’t be loaded, the resulting
+     * `GtkPicture` is empty.
+     *
+     * If you need to detect failures to load the file, use an
+     * image loading framework such as libglycin to load the file
+     * yourself, then create the `GtkPicture` from the texture.
+     * @param file - a `GFile`
+     */
     static newForFile(file?: Gio.File | null): Picture;
+    /**
+     * Creates a new `GtkPicture` displaying the file @filename.
+     *
+     * This is a utility function that calls [ctor@Gtk.Picture.new_for_file].
+     * See that function for details.
+     * @param filename - a filename
+     */
     static newForFilename(filename?: string | null): Picture;
+    /**
+     * Creates a new `GtkPicture` displaying @paintable.
+     *
+     * The `GtkPicture` will track changes to the `paintable` and update
+     * its size and contents in response to it.
+     * @param paintable - a `GdkPaintable`
+     */
     static newForPaintable(paintable?: Gdk.Paintable | null): Picture;
+    /**
+     * Creates a new `GtkPicture` displaying @pixbuf.
+     *
+     * This is a utility function that calls [ctor@Gtk.Picture.new_for_paintable],
+     * See that function for details.
+     *
+     * The pixbuf must not be modified after passing it to this function.
+     * @param pixbuf - a `GdkPixbuf`
+     */
     static newForPixbuf(pixbuf?: GdkPixbuf.Pixbuf | null): Picture;
+    /**
+     * Creates a new `GtkPicture` displaying the resource at @resource_path.
+     *
+     * This is a utility function that calls [ctor@Gtk.Picture.new_for_file].
+     * See that function for details.
+     * @param resourcePath - resource path to play back
+     */
     static newForResource(resourcePath?: string | null): Picture;
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the alternative textual description of the picture.
+     *
+     * The returned string will be %NULL if the picture cannot be described textually.
+     */
     getAlternativeText(): string | null;
+    /**
+     * Returns whether the `GtkPicture` respects its contents size.
+     */
     getCanShrink(): boolean;
+    /**
+     * Returns the fit mode for the content of the `GtkPicture`.
+     *
+     * See [enum@Gtk.ContentFit] for details.
+     */
     getContentFit(): ContentFit;
+    /**
+     * Gets the `GFile` currently displayed if `self` is displaying a file.
+     *
+     * If `self` is not displaying a file, for example when
+     * [method@Gtk.Picture.set_paintable] was used, then %NULL is returned.
+     */
     getFile(): Gio.File | null;
+    /**
+     * Returns whether the `GtkPicture` preserves its contents aspect ratio.
+     */
     getKeepAspectRatio(): boolean;
+    /**
+     * Gets the `GdkPaintable` being displayed by the `GtkPicture`.
+     */
     getPaintable(): Gdk.Paintable | null;
+    /**
+     * Sets an alternative textual description for the picture contents.
+     *
+     * It is equivalent to the "alt" attribute for images on websites.
+     *
+     * This text will be made available to accessibility tools.
+     *
+     * If the picture cannot be described textually, set this property to %NULL.
+     * @param alternativeText - a textual description of the contents
+     */
     setAlternativeText(alternativeText?: string | null): void;
+    /**
+     * If set to %TRUE, the `self` can be made smaller than its contents.
+     *
+     * The contents will then be scaled down when rendering.
+     *
+     * If you want to still force a minimum size manually, consider using
+     * [method@Gtk.Widget.set_size_request].
+     *
+     * Also of note is that a similar function for growing does not exist
+     * because the grow behavior can be controlled via
+     * [method@Gtk.Widget.set_halign] and [method@Gtk.Widget.set_valign].
+     * @param canShrink - if `self` can be made smaller than its contents
+     */
     setCanShrink(canShrink: boolean): void;
+    /**
+     * Sets how the content should be resized to fit the `GtkPicture`.
+     *
+     * See [enum@Gtk.ContentFit] for details.
+     * @param contentFit - the content fit mode
+     */
     setContentFit(contentFit: ContentFit): void;
+    /**
+     * Makes `self` load and display @file.
+     *
+     * See [ctor@Gtk.Picture.new_for_file] for details.
+     *
+     * ::: warning
+     * Note that this function should not be used with untrusted data.
+     * Use a proper image loading framework such as libglycin, which can
+     * load many image formats into a `GdkTexture`, and then use
+     * [method@Gtk.Image.set_from_paintable].
+     * @param file - a `GFile`
+     */
     setFile(file?: Gio.File | null): void;
+    /**
+     * Makes `self` load and display the given @filename.
+     *
+     * This is a utility function that calls [method@Gtk.Picture.set_file].
+     *
+     * ::: warning
+     * Note that this function should not be used with untrusted data.
+     * Use a proper image loading framework such as libglycin, which can
+     * load many image formats into a `GdkTexture`, and then use
+     * [method@Gtk.Image.set_from_paintable].
+     * @param filename - the filename to play
+     */
     setFilename(filename?: string | null): void;
+    /**
+     * If set to %TRUE, the `self` will render its contents according to
+     * their aspect ratio.
+     *
+     * That means that empty space may show up at the top/bottom or
+     * left/right of @self.
+     *
+     * If set to %FALSE or if the contents provide no aspect ratio,
+     * the contents will be stretched over the picture's whole area.
+     * @param keepAspectRatio - whether to keep aspect ratio
+     */
     setKeepAspectRatio(keepAspectRatio: boolean): void;
+    /**
+     * Makes `self` display the given @paintable.
+     *
+     * If `paintable` is `NULL`, nothing will be displayed.
+     *
+     * See [ctor@Gtk.Picture.new_for_paintable] for details.
+     * @param paintable - a `GdkPaintable`
+     */
     setPaintable(paintable?: Gdk.Paintable | null): void;
+    /**
+     * Sets a `GtkPicture` to show a `GdkPixbuf`.
+     *
+     * See [ctor@Gtk.Picture.new_for_pixbuf] for details.
+     *
+     * This is a utility function that calls [method@Gtk.Picture.set_paintable].
+     * @param pixbuf - a `GdkPixbuf`
+     */
     setPixbuf(pixbuf?: GdkPixbuf.Pixbuf | null): void;
+    /**
+     * Makes `self` load and display the resource at the given
+     * @resource_path.
+     *
+     * This is a utility function that calls [method@Gtk.Picture.set_file].
+     * @param resourcePath - the resource to set
+     */
     setResource(resourcePath?: string | null): void;
     connect(signal: "notify", handler: (self: Picture, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;