@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/editable.js

@@ -1,5 +1,135 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * Interface for single-line text editing widgets.
+ *
+ * Typical examples of editable widgets are [class@Gtk.Entry] and
+ * [class@Gtk.SpinButton]. It contains functions for generically manipulating
+ * an editable widget, a large number of action signals used for key bindings,
+ * and several signals that an application can connect to modify the behavior
+ * of a widget.
+ *
+ * As an example of the latter usage, by connecting the following handler to
+ * [signal@Gtk.Editable::insert-text], an application can convert all entry
+ * into a widget into uppercase.
+ *
+ * ## Forcing entry to uppercase.
+ *
+ * ```c
+ * #include <ctype.h>
+ *
+ * void
+ * insert_text_handler (GtkEditable *editable,
+ * const char  *text,
+ * int          length,
+ * int         *position,
+ * gpointer     data)
+ * {
+ * char *result = g_utf8_strup (text, length);
+ *
+ * g_signal_handlers_block_by_func (editable,
+ * (gpointer) insert_text_handler, data);
+ * gtk_editable_insert_text (editable, result, length, position);
+ * g_signal_handlers_unblock_by_func (editable,
+ * (gpointer) insert_text_handler, data);
+ *
+ * g_signal_stop_emission_by_name (editable, "insert_text");
+ *
+ * g_free (result);
+ * }
+ * ```
+ *
+ * ## Implementing GtkEditable
+ *
+ * The most likely scenario for implementing `GtkEditable` on your own widget
+ * is that you will embed a `GtkText` inside a complex widget, and want to
+ * delegate the editable functionality to that text widget. `GtkEditable`
+ * provides some utility functions to make this easy.
+ *
+ * In your class_init function, call [func@Gtk.Editable.install_properties],
+ * passing the first available property ID:
+ *
+ * ```c
+ * static void
+ * my_class_init (MyClass *class)
+ * {
+ * ...
+ * g_object_class_install_properties (object_class, NUM_PROPERTIES, props);
+ * gtk_editable_install_properties (object_clas, NUM_PROPERTIES);
+ * ...
+ * }
+ * ```
+ *
+ * In your interface_init function for the `GtkEditable` interface, provide
+ * an implementation for the get_delegate vfunc that returns your text widget:
+ *
+ * ```c
+ * GtkEditable *
+ * get_editable_delegate (GtkEditable *editable)
+ * {
+ * return GTK_EDITABLE (MY_WIDGET (editable)->text_widget);
+ * }
+ *
+ * static void
+ * my_editable_init (GtkEditableInterface *iface)
+ * {
+ * iface->get_delegate = get_editable_delegate;
+ * }
+ * ```
+ *
+ * You don't need to provide any other vfuncs. The default implementations
+ * work by forwarding to the delegate that the GtkEditableInterface.get_delegate()
+ * vfunc returns.
+ *
+ * In your instance_init function, create your text widget, and then call
+ * [method@Gtk.Editable.init_delegate]:
+ *
+ * ```c
+ * static void
+ * my_widget_init (MyWidget *self)
+ * {
+ * ...
+ * self->text_widget = gtk_text_new ();
+ * gtk_editable_init_delegate (GTK_EDITABLE (self));
+ * ...
+ * }
+ * ```
+ *
+ * In your dispose function, call [method@Gtk.Editable.finish_delegate] before
+ * destroying your text widget:
+ *
+ * ```c
+ * static void
+ * my_widget_dispose (GObject *object)
+ * {
+ * ...
+ * gtk_editable_finish_delegate (GTK_EDITABLE (self));
+ * g_clear_pointer (&self->text_widget, gtk_widget_unparent);
+ * ...
+ * }
+ * ```
+ *
+ * Finally, use [func@Gtk.Editable.delegate_set_property] in your `set_property`
+ * function (and similar for `get_property`), to set the editable properties:
+ *
+ * ```c
+ * ...
+ * if (gtk_editable_delegate_set_property (object, prop_id, value, pspec))
+ * return;
+ *
+ * switch (prop_id)
+ * ...
+ * ```
+ *
+ * It is important to note that if you create a `GtkEditable` that uses
+ * a delegate, the low level [signal@Gtk.Editable::insert-text] and
+ * [signal@Gtk.Editable::delete-text] signals will be propagated from the
+ * "wrapper" editable to the delegate, but they will not be propagated from
+ * the delegate to the "wrapper" editable, as they would cause an infinite
+ * recursion. If you wish to connect to the [signal@Gtk.Editable::insert-text]
+ * and [signal@Gtk.Editable::delete-text] signals, you will need to connect
+ * to them on the delegate obtained via [method@Gtk.Editable.get_delegate].
+ */
 export class Editable {
     ptr;
     constructor(ptr) {
@@ -8,6 +138,41 @@ export class Editable {
     static fromPtr(ptr) {
         return new Editable(ptr);
     }
+    /**
+     * 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", [
             {
@@ -20,6 +185,11 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -28,6 +198,18 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -44,6 +226,12 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -52,6 +240,9 @@ export class Editable {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the alignment of the editable.
+     */
     getAlignment() {
         return call("libgtk-4.so.1", "gtk_editable_get_alignment", [
             {
@@ -60,6 +251,18 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -76,6 +279,12 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -87,6 +296,9 @@ export class Editable {
             return null;
         return getObject(ptr, Editable);
     }
+    /**
+     * Retrieves whether `editable` is editable.
+     */
     getEditable() {
         return call("libgtk-4.so.1", "gtk_editable_get_editable", [
             {
@@ -95,6 +307,9 @@ export class Editable {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets if undo/redo actions are enabled for @editable
+     */
     getEnableUndo() {
         return call("libgtk-4.so.1", "gtk_editable_get_enable_undo", [
             {
@@ -103,6 +318,9 @@ export class Editable {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Retrieves the desired maximum width of @editable, in characters.
+     */
     getMaxWidthChars() {
         return call("libgtk-4.so.1", "gtk_editable_get_max_width_chars", [
             {
@@ -111,6 +329,12 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -119,6 +343,17 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -143,6 +378,11 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -151,6 +391,10 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -159,6 +403,15 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -167,6 +420,17 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -190,6 +454,18 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -206,6 +482,13 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -218,6 +501,10 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -230,6 +517,15 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -242,6 +538,10 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -254,6 +554,16 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -266,6 +576,12 @@ export class Editable {
             },
         ], { 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", [
             {
@@ -278,6 +594,15 @@ export class Editable {
             },
         ], { 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/emoji-chooser.d.ts

@@ -1,6 +1,9 @@
 import * as GObject from "../gobject/index.js";
 import { Popover } from "./popover.js";
 export declare class EmojiChooser extends Popover {
+    /**
+     * Creates a new `GtkEmojiChooser`.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
     connect(signal: "emoji-picked", handler: (self: EmojiChooser, text: string) => void, after?: boolean): number;

package/dist/generated/gtk/emoji-chooser.js

@@ -1,6 +1,48 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Popover } from "./popover.js";
+/**
+ * Used by text widgets to let users insert Emoji characters.
+ *
+ *
+ *
+ * `GtkEmojiChooser` emits the [signal@Gtk.EmojiChooser::emoji-picked]
+ * signal when an Emoji is selected.
+ *
+ * # Shortcuts and Gestures
+ *
+ * `GtkEmojiChooser` supports the following keyboard shortcuts:
+ *
+ * - `Ctrl`+`N` scrolls th the next section.
+ * - `Ctrl`+`P` scrolls th the previous section.
+ *
+ * # Actions
+ *
+ * `GtkEmojiChooser` defines a set of built-in actions:
+ *
+ * - `scroll.section` scrolls to the next or previous section.
+ *
+ * # CSS nodes
+ *
+ * ```
+ * popover
+ * ├── box.emoji-searchbar
+ * │   ╰── entry.search
+ * ╰── box.emoji-toolbar
+ * ├── button.image-button.emoji-section
+ * ├── ...
+ * ╰── button.image-button.emoji-section
+ * ```
+ *
+ * Every `GtkEmojiChooser` consists of a main node called popover.
+ * The contents of the popover are largely implementation defined
+ * and supposed to inherit general styles.
+ * The top searchbar used to search emoji and gets the .emoji-searchbar
+ * style class itself.
+ * The bottom toolbar used to switch between different emoji categories
+ * consists of buttons with the .emoji-section style class and gets the
+ * .emoji-toolbar style class itself.
+ */
 const SIGNAL_META = {
     "emoji-picked": {
         params: [{ type: { type: "string", borrowed: false } }],
@@ -10,6 +52,9 @@ const SIGNAL_META = {
     closed: { params: [], returnType: { type: "undefined" } },
 };
 export class EmojiChooser extends Popover {
+    /**
+     * Creates a new `GtkEmojiChooser`.
+     */
     constructor(...args) {
         super(...args);
     }

package/dist/generated/gtk/entry-buffer.d.ts

@@ -1,17 +1,99 @@
 import * as GObject from "../gobject/index.js";
 export declare class EntryBuffer extends GObject.GObject {
+    /**
+     * Create a new `GtkEntryBuffer` object.
+     *
+     * Optionally, specify initial text to set in the buffer.
+     * @param initialChars - initial buffer text
+     * @param nInitialChars - number of characters in @initial_chars, or -1
+     */
     constructor(nInitialChars: number, initialChars?: string | null);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Deletes a sequence of characters from the buffer.
+     *
+     * `n_chars` characters are deleted starting at @position.
+     * If `n_chars` is negative, then all characters until the
+     * end of the text are deleted.
+     *
+     * If `position` or `n_chars` are out of bounds, then they
+     * are coerced to sane values.
+     *
+     * Note that the positions are specified in characters,
+     * not bytes.
+     * @param position - position at which to delete text
+     * @param nChars - number of characters to delete
+     */
     deleteText(position: number, nChars: number): number;
+    /**
+     * Used when subclassing `GtkEntryBuffer`.
+     * @param position - position at which text was deleted
+     * @param nChars - number of characters deleted
+     */
     emitDeletedText(position: number, nChars: number): void;
+    /**
+     * Used when subclassing `GtkEntryBuffer`.
+     * @param position - position at which text was inserted
+     * @param chars - text that was inserted
+     * @param nChars - number of characters inserted
+     */
     emitInsertedText(position: number, chars: string, nChars: number): void;
+    /**
+     * Retrieves the length in bytes of the buffer.
+     *
+     * See [method@Gtk.EntryBuffer.get_length].
+     */
     getBytes(): number;
+    /**
+     * Retrieves the length in characters of the buffer.
+     */
     getLength(): number;
+    /**
+     * Retrieves the maximum allowed length of the text in @buffer.
+     */
     getMaxLength(): number;
+    /**
+     * Retrieves the contents of the buffer.
+     *
+     * The memory pointer returned by this call will not change
+     * unless this object emits a signal, or is finalized.
+     */
     getText(): string;
+    /**
+     * Inserts `n_chars` characters of `chars` into the contents of the
+     * buffer, at position @position.
+     *
+     * If `n_chars` is negative, then characters from chars will be inserted
+     * until a null-terminator is found. If `position` or `n_chars` are out of
+     * bounds, or the maximum buffer text length is exceeded, then they are
+     * coerced to sane values.
+     *
+     * Note that the position and length are in characters, not in bytes.
+     * @param position - the position at which to insert text.
+     * @param chars - the text to insert into the buffer.
+     * @param nChars - the length of the text in characters, or -1
+     */
     insertText(position: number, chars: string, nChars: number): number;
+    /**
+     * Sets the maximum allowed length of the contents of the buffer.
+     *
+     * If the current contents are longer than the given length, then
+     * they will be truncated to fit.
+     * @param maxLength - the maximum length of the entry buffer, or 0 for no maximum.
+     */
     setMaxLength(maxLength: number): void;
+    /**
+     * Sets the text in the buffer.
+     *
+     * This is roughly equivalent to calling
+     * [method@Gtk.EntryBuffer.delete_text] and
+     * [method@Gtk.EntryBuffer.insert_text].
+     *
+     * Note that `n_chars` is in characters, not in bytes.
+     * @param chars - the new text
+     * @param nChars - the number of characters in @text, or -1
+     */
     setText(chars: string, nChars: number): void;
     connect(signal: "deleted-text", handler: (self: EntryBuffer, position: number, nChars: number) => void, after?: boolean): number;
     connect(signal: "inserted-text", handler: (self: EntryBuffer, position: number, chars: string, nChars: number) => void, after?: boolean): number;