@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -1,17 +1,127 @@
 import { Editable } from "./editable.js";
 import * as GObject from "../gobject/index.js";
 import { Widget } from "./widget.js";
+/**
+ * Reveals a search entry when search is started.
+ *
+ *
+ *
+ * It can also contain additional widgets, such as drop-down menus,
+ * or buttons.  The search bar would appear when a search is started
+ * through typing on the keyboard, or the application’s search mode
+ * is toggled on.
+ *
+ * For keyboard presses to start a search, the search bar must be told
+ * of a widget to capture key events from through
+ * [method@Gtk.SearchBar.set_key_capture_widget]. This widget will
+ * typically be the top-level window, or a parent container of the
+ * search bar. Common shortcuts such as Ctrl+F should be handled as an
+ * application action, or through the menu items.
+ *
+ * You will also need to tell the search bar about which entry you
+ * are using as your search entry using [method@Gtk.SearchBar.connect_entry].
+ *
+ * ## Creating a search bar
+ *
+ * The following example shows you how to create a more complex search
+ * entry.
+ *
+ * [A simple example](https://gitlab.gnome.org/GNOME/gtk/tree/main/examples/search-bar.c)
+ *
+ * # Shortcuts and Gestures
+ *
+ * `GtkSearchBar` supports the following keyboard shortcuts:
+ *
+ * - `Escape` hides the search bar.
+ *
+ * # CSS nodes
+ *
+ * ```
+ * searchbar
+ * ╰── revealer
+ * ╰── box
+ * ├── [child]
+ * ╰── [button.close]
+ * ```
+ *
+ * `GtkSearchBar` has a main CSS node with name searchbar. It has a child
+ * node with name revealer that contains a node with name box. The box node
+ * contains both the CSS node of the child widget as well as an optional button
+ * node which gets the .close style class applied.
+ *
+ * # Accessibility
+ *
+ * `GtkSearchBar` uses the [enum@Gtk.AccessibleRole.search] role.
+ */
 export declare class SearchBar extends Widget {
+    /**
+     * Creates a `GtkSearchBar`.
+     *
+     * You will need to tell it about which widget is going to be your text
+     * entry using [method@Gtk.SearchBar.connect_entry].
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Connects the `GtkEditable` widget passed as the one to be used in
+     * this search bar.
+     *
+     * The entry should be a descendant of the search bar. Calling this
+     * function manually is only required if the entry isn’t the direct
+     * child of the search bar (as in our main example).
+     * @param entry - a `GtkEditable`
+     */
     connectEntry(entry: Editable): void;
+    /**
+     * Gets the child widget of @bar.
+     */
     getChild(): Widget | null;
+    /**
+     * Gets the widget that `bar` is capturing key events from.
+     */
     getKeyCaptureWidget(): Widget | null;
+    /**
+     * Returns whether the search mode is on or off.
+     */
     getSearchMode(): boolean;
+    /**
+     * Returns whether the close button is shown.
+     */
     getShowCloseButton(): boolean;
+    /**
+     * Sets the child widget of @bar.
+     * @param child - the child widget
+     */
     setChild(child?: Widget | null): void;
+    /**
+     * Sets `widget` as the widget that `bar` will capture key events
+     * from.
+     *
+     * If key events are handled by the search bar, the bar will
+     * be shown, and the entry populated with the entered text.
+     *
+     * Note that despite the name of this function, the events
+     * are only 'captured' in the bubble phase, which means that
+     * editable child widgets of `widget` will receive text input
+     * before it gets captured. If that is not desired, you can
+     * capture and forward the events yourself with
+     * [method@Gtk.EventControllerKey.forward].
+     * @param widget - a `GtkWidget`
+     */
     setKeyCaptureWidget(widget?: Widget | null): void;
+    /**
+     * Switches the search mode on or off.
+     * @param searchMode - the new state of the search mode
+     */
     setSearchMode(searchMode: boolean): void;
+    /**
+     * Shows or hides the close button.
+     *
+     * Applications that already have a “search” toggle button should not
+     * show a close button in their search bar, as it duplicates the role
+     * of the toggle button.
+     * @param visible - whether the close button will be shown or not
+     */
     setShowCloseButton(visible: boolean): void;
     connect(signal: "notify", handler: (self: SearchBar, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

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

@@ -1,7 +1,65 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Widget } from "./widget.js";
+/**
+ * Reveals a search entry when search is started.
+ *
+ *
+ *
+ * It can also contain additional widgets, such as drop-down menus,
+ * or buttons.  The search bar would appear when a search is started
+ * through typing on the keyboard, or the application’s search mode
+ * is toggled on.
+ *
+ * For keyboard presses to start a search, the search bar must be told
+ * of a widget to capture key events from through
+ * [method@Gtk.SearchBar.set_key_capture_widget]. This widget will
+ * typically be the top-level window, or a parent container of the
+ * search bar. Common shortcuts such as Ctrl+F should be handled as an
+ * application action, or through the menu items.
+ *
+ * You will also need to tell the search bar about which entry you
+ * are using as your search entry using [method@Gtk.SearchBar.connect_entry].
+ *
+ * ## Creating a search bar
+ *
+ * The following example shows you how to create a more complex search
+ * entry.
+ *
+ * [A simple example](https://gitlab.gnome.org/GNOME/gtk/tree/main/examples/search-bar.c)
+ *
+ * # Shortcuts and Gestures
+ *
+ * `GtkSearchBar` supports the following keyboard shortcuts:
+ *
+ * - `Escape` hides the search bar.
+ *
+ * # CSS nodes
+ *
+ * ```
+ * searchbar
+ * ╰── revealer
+ * ╰── box
+ * ├── [child]
+ * ╰── [button.close]
+ * ```
+ *
+ * `GtkSearchBar` has a main CSS node with name searchbar. It has a child
+ * node with name revealer that contains a node with name box. The box node
+ * contains both the CSS node of the child widget as well as an optional button
+ * node which gets the .close style class applied.
+ *
+ * # Accessibility
+ *
+ * `GtkSearchBar` uses the [enum@Gtk.AccessibleRole.search] role.
+ */
 export class SearchBar extends Widget {
+    /**
+     * Creates a `GtkSearchBar`.
+     *
+     * You will need to tell it about which widget is going to be your text
+     * entry using [method@Gtk.SearchBar.connect_entry].
+     */
     constructor(...args) {
         super(...args);
     }
@@ -11,6 +69,15 @@ export class SearchBar extends Widget {
             borrowed: true,
         });
     }
+    /**
+     * Connects the `GtkEditable` widget passed as the one to be used in
+     * this search bar.
+     *
+     * The entry should be a descendant of the search bar. Calling this
+     * function manually is only required if the entry isn’t the direct
+     * child of the search bar (as in our main example).
+     * @param entry - a `GtkEditable`
+     */
     connectEntry(entry) {
         call("libgtk-4.so.1", "gtk_search_bar_connect_entry", [
             {
@@ -23,6 +90,9 @@ export class SearchBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the child widget of @bar.
+     */
     getChild() {
         const ptr = call("libgtk-4.so.1", "gtk_search_bar_get_child", [
             {
@@ -34,6 +104,9 @@ export class SearchBar extends Widget {
             return null;
         return getObject(ptr, Widget);
     }
+    /**
+     * Gets the widget that `bar` is capturing key events from.
+     */
     getKeyCaptureWidget() {
         const ptr = call("libgtk-4.so.1", "gtk_search_bar_get_key_capture_widget", [
             {
@@ -45,6 +118,9 @@ export class SearchBar extends Widget {
             return null;
         return getObject(ptr, Widget);
     }
+    /**
+     * Returns whether the search mode is on or off.
+     */
     getSearchMode() {
         return call("libgtk-4.so.1", "gtk_search_bar_get_search_mode", [
             {
@@ -53,6 +129,9 @@ export class SearchBar extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether the close button is shown.
+     */
     getShowCloseButton() {
         return call("libgtk-4.so.1", "gtk_search_bar_get_show_close_button", [
             {
@@ -61,6 +140,10 @@ export class SearchBar extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Sets the child widget of @bar.
+     * @param child - the child widget
+     */
     setChild(child) {
         call("libgtk-4.so.1", "gtk_search_bar_set_child", [
             {
@@ -74,6 +157,21 @@ export class SearchBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets `widget` as the widget that `bar` will capture key events
+     * from.
+     *
+     * If key events are handled by the search bar, the bar will
+     * be shown, and the entry populated with the entered text.
+     *
+     * Note that despite the name of this function, the events
+     * are only 'captured' in the bubble phase, which means that
+     * editable child widgets of `widget` will receive text input
+     * before it gets captured. If that is not desired, you can
+     * capture and forward the events yourself with
+     * [method@Gtk.EventControllerKey.forward].
+     * @param widget - a `GtkWidget`
+     */
     setKeyCaptureWidget(widget) {
         call("libgtk-4.so.1", "gtk_search_bar_set_key_capture_widget", [
             {
@@ -87,6 +185,10 @@ export class SearchBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Switches the search mode on or off.
+     * @param searchMode - the new state of the search mode
+     */
     setSearchMode(searchMode) {
         call("libgtk-4.so.1", "gtk_search_bar_set_search_mode", [
             {
@@ -99,6 +201,14 @@ export class SearchBar extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Shows or hides the close button.
+     *
+     * Applications that already have a “search” toggle button should not
+     * show a close button in their search bar, as it duplicates the role
+     * of the toggle button.
+     * @param visible - whether the close button will be shown or not
+     */
     setShowCloseButton(visible) {
         call("libgtk-4.so.1", "gtk_search_bar_set_show_close_button", [
             {

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

@@ -4,41 +4,292 @@ import { Editable } from "./editable.js";
 import * as GObject from "../gobject/index.js";
 import { Widget } from "./widget.js";
 export declare class SearchEntry extends Widget {
+    /**
+     * Creates a `GtkSearchEntry`.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the input purpose for @entry.
+     */
     getInputHints(): InputHints;
+    /**
+     * Gets the input purpose of @entry.
+     */
     getInputPurpose(): InputPurpose;
+    /**
+     * Gets the widget that `entry` is capturing key events from.
+     */
     getKeyCaptureWidget(): Widget | null;
+    /**
+     * Gets the placeholder text associated with @entry.
+     */
     getPlaceholderText(): string | null;
+    /**
+     * Get the delay to be used between the last keypress and the
+     * [signal@Gtk.SearchEntry::search-changed] signal being emitted.
+     */
     getSearchDelay(): number;
+    /**
+     * Sets the input hints for @entry.
+     * @param hints - the new input hints
+     */
     setInputHints(hints: InputHints): void;
+    /**
+     * Sets the input purpose of @entry.
+     * @param purpose - the new input purpose
+     */
     setInputPurpose(purpose: InputPurpose): void;
+    /**
+     * Sets `widget` as the widget that `entry` will capture key
+     * events from.
+     *
+     * Key events are consumed by the search entry to start or
+     * continue a search.
+     *
+     * If the entry is part of a `GtkSearchBar`, it is preferable
+     * to call [method@Gtk.SearchBar.set_key_capture_widget] instead,
+     * which will reveal the entry in addition to triggering the
+     * search entry.
+     *
+     * Note that despite the name of this function, the events
+     * are only 'captured' in the bubble phase, which means that
+     * editable child widgets of `widget` will receive text input
+     * before it gets captured. If that is not desired, you can
+     * capture and forward the events yourself with
+     * [method@Gtk.EventControllerKey.forward].
+     * @param widget - a `GtkWidget`
+     */
     setKeyCaptureWidget(widget?: Widget | null): void;
+    /**
+     * Sets the placeholder text associated with @entry.
+     * @param text - the text to set as a placeholder
+     */
     setPlaceholderText(text?: string | null): void;
+    /**
+     * Set the delay to be used between the last keypress and the
+     * [signal@Gtk.SearchEntry::search-changed] signal being emitted.
+     * @param delay - a delay in milliseconds
+     */
     setSearchDelay(delay: number): void;
+    /**
+     * 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: AccessiblePlatformState): boolean;
+    /**
+     * Deletes the currently selected text of the editable.
+     *
+     * This call doesn’t do anything if there is no selected text.
+     */
     deleteSelection(): void;
+    /**
+     * 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: number, endPos: number): void;
+    /**
+     * 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(): void;
+    /**
+     * Gets the alignment of the editable.
+     */
     getAlignment(): number;
+    /**
+     * 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: number, endPos: number): string;
+    /**
+     * Gets the `GtkEditable` that `editable` is delegating its
+     * implementation to.
+     *
+     * Typically, the delegate is a [class@Gtk.Text] widget.
+     */
     getDelegate(): Editable | null;
+    /**
+     * Retrieves whether `editable` is editable.
+     */
     getEditable(): boolean;
+    /**
+     * Gets if undo/redo actions are enabled for @editable
+     */
     getEnableUndo(): boolean;
+    /**
+     * Retrieves the desired maximum width of @editable, in characters.
+     */
     getMaxWidthChars(): number;
+    /**
+     * 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(): number;
+    /**
+     * 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?: Ref<number> | null, endPos?: Ref<number> | null): boolean;
+    /**
+     * Retrieves the contents of @editable.
+     *
+     * The returned string is owned by GTK and must not be modified or freed.
+     */
     getText(): string;
+    /**
+     * Gets the number of characters of space reserved
+     * for the contents of the editable.
+     */
     getWidthChars(): number;
+    /**
+     * 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(): void;
+    /**
+     * 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: string, length: number, position: Ref<number>): void;
+    /**
+     * 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: number, endPos: number): void;
+    /**
+     * 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: number): void;
+    /**
+     * 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: boolean): void;
+    /**
+     * 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: boolean): void;
+    /**
+     * Sets the desired maximum width in characters of @editable.
+     * @param nChars - the new desired maximum width, in characters
+     */
     setMaxWidthChars(nChars: number): void;
+    /**
+     * 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: number): void;
+    /**
+     * Sets the text in the editable to the given value.
+     *
+     * This is replacing the current contents.
+     * @param text - the text to set
+     */
     setText(text: string): void;
+    /**
+     * 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: number): void;
     connect(signal: "activate", handler: (self: SearchEntry) => void, after?: boolean): number;
     connect(signal: "next-match", handler: (self: SearchEntry) => void, after?: boolean): number;