@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/imcontext-simple.js

@@ -1,7 +1,50 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { IMContext } from "./imcontext.js";
+/**
+ * Supports compose sequences, dead keys and numeric Unicode input.
+ *
+ * ## Compose sequences
+ *
+ * `GtkIMContextSimple` reads compose sequences from the first of the
+ * following files that is found: ~/.config/gtk-4.0/Compose, ~/.XCompose,
+ * /usr/share/X11/locale/$locale/Compose (for locales that have a nontrivial
+ * Compose file). A subset of the file syntax described in the Compose(5)
+ * manual page is supported. Additionally, `include "%L"` loads GTK’s built-in
+ * table of compose sequences rather than the locale-specific one from X11.
+ *
+ * If none of these files is found, `GtkIMContextSimple` uses a built-in table
+ * of compose sequences that is derived from the X11 Compose files.
+ *
+ * Note that compose sequences typically start with the Compose_key, which is
+ * often not available as a dedicated key on keyboards. Keyboard layouts may
+ * map this keysym to other keys, such as the right Control key.
+ *
+ * ## Unicode characters
+ *
+ * `GtkIMContextSimple` also supports numeric entry of Unicode characters
+ * by typing `Ctrl`-`Shift`-`u`, followed by a
+ * hexadecimal Unicode codepoint.
+ *
+ * For example,
+ *
+ * Ctrl-Shift-u 1 2 3 Enter
+ *
+ * yields U+0123 LATIN SMALL LETTER G WITH CEDILLA, i.e. ģ.
+ *
+ * ## Dead keys
+ *
+ * `GtkIMContextSimple` supports dead keys. For example, typing
+ *
+ * dead_acute a
+ *
+ * yields U+00E! LATIN SMALL LETTER_A WITH ACUTE, i.e. á. Note that this
+ * depends on the keyboard layout including dead keys.
+ */
 export class IMContextSimple extends IMContext {
+    /**
+     * Creates a new `GtkIMContextSimple`.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -11,6 +54,10 @@ export class IMContextSimple extends IMContext {
             borrowed: false,
         });
     }
+    /**
+     * Adds an additional table from the X11 compose file.
+     * @param composeFile - The path of compose file
+     */
     addComposeFile(composeFile) {
         call("libgtk-4.so.1", "gtk_im_context_simple_add_compose_file", [
             {

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

@@ -6,20 +6,182 @@ import * as Pango from "../pango/index.js";
 export declare class IMContext extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Requests the platform to show an on-screen keyboard for user input.
+     *
+     * This method will return %TRUE if this request was actually performed
+     * to the platform, other environmental factors may result in an on-screen
+     * keyboard effectively not showing up.
+     * @param event - a [class@Gdk.Event]
+     */
     activateOsk(event?: Gdk.Event | null): boolean;
+    /**
+     * Asks the widget that the input context is attached to delete
+     * characters around the cursor position by emitting the
+     * `::delete_surrounding` signal.
+     *
+     * Note that `offset` and `n_chars` are in characters not in bytes
+     * which differs from the usage other places in `GtkIMContext`.
+     *
+     * In order to use this function, you should first call
+     * [method@Gtk.IMContext.get_surrounding] to get the current context,
+     * and call this function immediately afterwards to make sure that you
+     * know what you are deleting. You should also account for the fact
+     * that even if the signal was handled, the input context might not
+     * have deleted all the characters that were requested to be deleted.
+     *
+     * This function is used by an input method that wants to make
+     * substitutions in the existing text in response to new input.
+     * It is not useful for applications.
+     * @param offset - offset from cursor position in chars;
+     * @param nChars - number of characters to delete.
+     */
     deleteSurrounding(offset: number, nChars: number): boolean;
+    /**
+     * Allow an input method to forward key press and release events
+     * to another input method without necessarily having a `GdkEvent`
+     * available.
+     * @param press - whether to forward a key press or release event
+     * @param surface - the surface the event is for
+     * @param device - the device that the event is for
+     * @param time - the timestamp for the event
+     * @param keycode - the keycode for the event
+     * @param state - modifier state for the event
+     * @param group - the active keyboard group for the event
+     */
     filterKey(press: boolean, surface: Gdk.Surface, device: Gdk.Device, time: number, keycode: number, state: Gdk.ModifierType, group: number): boolean;
+    /**
+     * Allow an input method to internally handle key press and release
+     * events.
+     *
+     * If this function returns %TRUE, then no further processing
+     * should be done for this key event.
+     * @param event - the key event
+     */
     filterKeypress(event: Gdk.Event): boolean;
+    /**
+     * Notify the input method that the widget to which this
+     * input context corresponds has gained focus.
+     *
+     * The input method may, for example, change the displayed
+     * feedback to reflect this change.
+     */
     focusIn(): void;
+    /**
+     * Notify the input method that the widget to which this
+     * input context corresponds has lost focus.
+     *
+     * The input method may, for example, change the displayed
+     * feedback or reset the contexts state to reflect this change.
+     */
     focusOut(): void;
+    /**
+     * Retrieve the current preedit string for the input context,
+     * and a list of attributes to apply to the string.
+     *
+     * This string should be displayed inserted at the insertion point.
+     * @param str - location to store the retrieved
+     * @param attrs - location to store the retrieved
+     * @param cursorPos - location to store position of cursor
+     */
     getPreeditString(str: Ref<string>, attrs: Ref<Pango.AttrList>, cursorPos: Ref<number>): void;
+    /**
+     * Retrieves context around the insertion point.
+     *
+     * Input methods typically want context in order to constrain input text
+     * based on existing text; this is important for languages such as Thai
+     * where only some sequences of characters are allowed.
+     *
+     * This function is implemented by emitting the
+     * [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method;
+     * in response to this signal, a widget should provide as much context as
+     * is available, up to an entire paragraph, by calling
+     * [method@Gtk.IMContext.set_surrounding].
+     *
+     * Note that there is no obligation for a widget to respond to the
+     * `::retrieve-surrounding` signal, so input methods must be prepared to
+     * function without context.
+     * @param text - location to store a UTF-8 encoded
+     * @param cursorIndex - location to store byte index of the insertion
+     */
     getSurrounding(text: Ref<string>, cursorIndex: Ref<number>): boolean;
+    /**
+     * Retrieves context around the insertion point.
+     *
+     * Input methods typically want context in order to constrain input
+     * text based on existing text; this is important for languages such
+     * as Thai where only some sequences of characters are allowed.
+     *
+     * This function is implemented by emitting the
+     * [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method;
+     * in response to this signal, a widget should provide as much context as
+     * is available, up to an entire paragraph, by calling
+     * [method@Gtk.IMContext.set_surrounding_with_selection].
+     *
+     * Note that there is no obligation for a widget to respond to the
+     * `::retrieve-surrounding` signal, so input methods must be prepared to
+     * function without context.
+     * @param text - location to store a UTF-8 encoded
+     * @param cursorIndex - location to store byte index of the insertion
+     * @param anchorIndex - location to store byte index of the selection
+     */
     getSurroundingWithSelection(text: Ref<string>, cursorIndex: Ref<number>, anchorIndex: Ref<number>): boolean;
+    /**
+     * Notify the input method that a change such as a change in cursor
+     * position has been made.
+     *
+     * This will typically cause the input method to clear the preedit state.
+     */
     reset(): void;
+    /**
+     * Set the client widget for the input context.
+     *
+     * This is the `GtkWidget` holding the input focus. This widget is
+     * used in order to correctly position status windows, and may
+     * also be used for purposes internal to the input method.
+     * @param widget - the client widget. This may be %NULL to indicate
+     */
     setClientWidget(widget?: Widget | null): void;
+    /**
+     * Notify the input method that a change in cursor
+     * position has been made.
+     *
+     * The location is relative to the client widget.
+     * @param area - new location
+     */
     setCursorLocation(area: Gdk.Rectangle): void;
+    /**
+     * Sets surrounding context around the insertion point and preedit
+     * string.
+     *
+     * This function is expected to be called in response to the
+     * [signal@Gtk.IMContext::retrieve-surrounding] signal, and will
+     * likely have no effect if called at other times.
+     * @param text - text surrounding the insertion point, as UTF-8.
+     * @param len - the length of @text, or -1 if `text` is nul-terminated
+     * @param cursorIndex - the byte index of the insertion cursor within @text.
+     */
     setSurrounding(text: string, len: number, cursorIndex: number): void;
+    /**
+     * Sets surrounding context around the insertion point and preedit
+     * string. This function is expected to be called in response to the
+     * [signal@Gtk.IMContext::retrieve_surrounding] signal, and will likely
+     * have no effect if called at other times.
+     * @param text - text surrounding the insertion point, as UTF-8.
+     * @param len - the length of @text, or -1 if `text` is nul-terminated
+     * @param cursorIndex - the byte index of the insertion cursor within @text
+     * @param anchorIndex - the byte index of the selection bound within @text
+     */
     setSurroundingWithSelection(text: string, len: number, cursorIndex: number, anchorIndex: number): void;
+    /**
+     * Sets whether the IM context should use the preedit string
+     * to display feedback.
+     *
+     * If `use_preedit` is %FALSE (default is %TRUE), then the IM context
+     * may use some other method to display feedback, such as displaying
+     * it in a child of the root window.
+     * @param usePreedit - whether the IM context should use the preedit string.
+     */
     setUsePreedit(usePreedit: boolean): void;
     connect(signal: "commit", handler: (self: IMContext, str: string) => void, after?: boolean): number;
     connect(signal: "delete-surrounding", handler: (self: IMContext, offset: number, nChars: number) => boolean, after?: boolean): number;

package/dist/generated/gtk/imcontext.js

@@ -1,6 +1,37 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * The interface for GTK input methods.
+ *
+ * `GtkIMContext` is used by GTK text input widgets like `GtkText`
+ * to map from key events to Unicode character strings.
+ *
+ * An input method may consume multiple key events in sequence before finally
+ * outputting the composed result. This is called *preediting*, and an input
+ * method may provide feedback about this process by displaying the intermediate
+ * composition states as preedit text. To do so, the `GtkIMContext` will emit
+ * [signal@Gtk.IMContext::preedit-start], [signal@Gtk.IMContext::preedit-changed]
+ * and [signal@Gtk.IMContext::preedit-end] signals.
+ *
+ * For instance, the built-in GTK input method [class@Gtk.IMContextSimple]
+ * implements the input of arbitrary Unicode code points by holding down the
+ * `Control` and `Shift` keys and then typing `u`
+ * followed by the hexadecimal digits of the code point. When releasing the
+ * `Control` and `Shift` keys, preediting ends and the
+ * character is inserted as text. For example,
+ *
+ * Ctrl+Shift+u 2 0 A C
+ *
+ * results in the € sign.
+ *
+ * Additional input methods can be made available for use by GTK widgets as
+ * loadable modules. An input method module is a small shared library which
+ * provides a `GIOExtension` for the extension point named "gtk-im-module".
+ *
+ * To connect a widget to the users preferred input method, you should use
+ * [class@Gtk.IMMulticontext].
+ */
 const SIGNAL_META = {
     commit: {
         params: [{ type: { type: "string", borrowed: false } }],
@@ -33,6 +64,14 @@ export class IMContext extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Requests the platform to show an on-screen keyboard for user input.
+     *
+     * This method will return %TRUE if this request was actually performed
+     * to the platform, other environmental factors may result in an on-screen
+     * keyboard effectively not showing up.
+     * @param event - a [class@Gdk.Event]
+     */
     activateOsk(event) {
         return call("libgtk-4.so.1", "gtk_im_context_activate_osk", [
             {
@@ -46,6 +85,27 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Asks the widget that the input context is attached to delete
+     * characters around the cursor position by emitting the
+     * `::delete_surrounding` signal.
+     *
+     * Note that `offset` and `n_chars` are in characters not in bytes
+     * which differs from the usage other places in `GtkIMContext`.
+     *
+     * In order to use this function, you should first call
+     * [method@Gtk.IMContext.get_surrounding] to get the current context,
+     * and call this function immediately afterwards to make sure that you
+     * know what you are deleting. You should also account for the fact
+     * that even if the signal was handled, the input context might not
+     * have deleted all the characters that were requested to be deleted.
+     *
+     * This function is used by an input method that wants to make
+     * substitutions in the existing text in response to new input.
+     * It is not useful for applications.
+     * @param offset - offset from cursor position in chars;
+     * @param nChars - number of characters to delete.
+     */
     deleteSurrounding(offset, nChars) {
         return call("libgtk-4.so.1", "gtk_im_context_delete_surrounding", [
             {
@@ -62,6 +122,18 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Allow an input method to forward key press and release events
+     * to another input method without necessarily having a `GdkEvent`
+     * available.
+     * @param press - whether to forward a key press or release event
+     * @param surface - the surface the event is for
+     * @param device - the device that the event is for
+     * @param time - the timestamp for the event
+     * @param keycode - the keycode for the event
+     * @param state - modifier state for the event
+     * @param group - the active keyboard group for the event
+     */
     filterKey(press, surface, device, time, keycode, state, group) {
         return call("libgtk-4.so.1", "gtk_im_context_filter_key", [
             {
@@ -98,6 +170,14 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Allow an input method to internally handle key press and release
+     * events.
+     *
+     * If this function returns %TRUE, then no further processing
+     * should be done for this key event.
+     * @param event - the key event
+     */
     filterKeypress(event) {
         return call("libgtk-4.so.1", "gtk_im_context_filter_keypress", [
             {
@@ -110,6 +190,13 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Notify the input method that the widget to which this
+     * input context corresponds has gained focus.
+     *
+     * The input method may, for example, change the displayed
+     * feedback to reflect this change.
+     */
     focusIn() {
         call("libgtk-4.so.1", "gtk_im_context_focus_in", [
             {
@@ -118,6 +205,13 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Notify the input method that the widget to which this
+     * input context corresponds has lost focus.
+     *
+     * The input method may, for example, change the displayed
+     * feedback or reset the contexts state to reflect this change.
+     */
     focusOut() {
         call("libgtk-4.so.1", "gtk_im_context_focus_out", [
             {
@@ -126,6 +220,15 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Retrieve the current preedit string for the input context,
+     * and a list of attributes to apply to the string.
+     *
+     * This string should be displayed inserted at the insertion point.
+     * @param str - location to store the retrieved
+     * @param attrs - location to store the retrieved
+     * @param cursorPos - location to store position of cursor
+     */
     getPreeditString(str, attrs, cursorPos) {
         call("libgtk-4.so.1", "gtk_im_context_get_preedit_string", [
             {
@@ -156,6 +259,25 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Retrieves context around the insertion point.
+     *
+     * Input methods typically want context in order to constrain input text
+     * based on existing text; this is important for languages such as Thai
+     * where only some sequences of characters are allowed.
+     *
+     * This function is implemented by emitting the
+     * [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method;
+     * in response to this signal, a widget should provide as much context as
+     * is available, up to an entire paragraph, by calling
+     * [method@Gtk.IMContext.set_surrounding].
+     *
+     * Note that there is no obligation for a widget to respond to the
+     * `::retrieve-surrounding` signal, so input methods must be prepared to
+     * function without context.
+     * @param text - location to store a UTF-8 encoded
+     * @param cursorIndex - location to store byte index of the insertion
+     */
     getSurrounding(text, cursorIndex) {
         return call("libgtk-4.so.1", "gtk_im_context_get_surrounding", [
             {
@@ -175,6 +297,26 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Retrieves context around the insertion point.
+     *
+     * Input methods typically want context in order to constrain input
+     * text based on existing text; this is important for languages such
+     * as Thai where only some sequences of characters are allowed.
+     *
+     * This function is implemented by emitting the
+     * [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method;
+     * in response to this signal, a widget should provide as much context as
+     * is available, up to an entire paragraph, by calling
+     * [method@Gtk.IMContext.set_surrounding_with_selection].
+     *
+     * Note that there is no obligation for a widget to respond to the
+     * `::retrieve-surrounding` signal, so input methods must be prepared to
+     * function without context.
+     * @param text - location to store a UTF-8 encoded
+     * @param cursorIndex - location to store byte index of the insertion
+     * @param anchorIndex - location to store byte index of the selection
+     */
     getSurroundingWithSelection(text, cursorIndex, anchorIndex) {
         return call("libgtk-4.so.1", "gtk_im_context_get_surrounding_with_selection", [
             {
@@ -201,6 +343,12 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Notify the input method that a change such as a change in cursor
+     * position has been made.
+     *
+     * This will typically cause the input method to clear the preedit state.
+     */
     reset() {
         call("libgtk-4.so.1", "gtk_im_context_reset", [
             {
@@ -209,6 +357,14 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Set the client widget for the input context.
+     *
+     * This is the `GtkWidget` holding the input focus. This widget is
+     * used in order to correctly position status windows, and may
+     * also be used for purposes internal to the input method.
+     * @param widget - the client widget. This may be %NULL to indicate
+     */
     setClientWidget(widget) {
         call("libgtk-4.so.1", "gtk_im_context_set_client_widget", [
             {
@@ -222,6 +378,13 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Notify the input method that a change in cursor
+     * position has been made.
+     *
+     * The location is relative to the client widget.
+     * @param area - new location
+     */
     setCursorLocation(area) {
         call("libgtk-4.so.1", "gtk_im_context_set_cursor_location", [
             {
@@ -239,6 +402,17 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets surrounding context around the insertion point and preedit
+     * string.
+     *
+     * This function is expected to be called in response to the
+     * [signal@Gtk.IMContext::retrieve-surrounding] signal, and will
+     * likely have no effect if called at other times.
+     * @param text - text surrounding the insertion point, as UTF-8.
+     * @param len - the length of @text, or -1 if `text` is nul-terminated
+     * @param cursorIndex - the byte index of the insertion cursor within @text.
+     */
     setSurrounding(text, len, cursorIndex) {
         call("libgtk-4.so.1", "gtk_im_context_set_surrounding", [
             {
@@ -259,6 +433,16 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets surrounding context around the insertion point and preedit
+     * string. This function is expected to be called in response to the
+     * [signal@Gtk.IMContext::retrieve_surrounding] signal, and will likely
+     * have no effect if called at other times.
+     * @param text - text surrounding the insertion point, as UTF-8.
+     * @param len - the length of @text, or -1 if `text` is nul-terminated
+     * @param cursorIndex - the byte index of the insertion cursor within @text
+     * @param anchorIndex - the byte index of the selection bound within @text
+     */
     setSurroundingWithSelection(text, len, cursorIndex, anchorIndex) {
         call("libgtk-4.so.1", "gtk_im_context_set_surrounding_with_selection", [
             {
@@ -283,6 +467,15 @@ export class IMContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the IM context should use the preedit string
+     * to display feedback.
+     *
+     * If `use_preedit` is %FALSE (default is %TRUE), then the IM context
+     * may use some other method to display feedback, such as displaying
+     * it in a child of the root window.
+     * @param usePreedit - whether the IM context should use the preedit string.
+     */
     setUsePreedit(usePreedit) {
         call("libgtk-4.so.1", "gtk_im_context_set_use_preedit", [
             {

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

@@ -1,9 +1,33 @@
 import * as GObject from "../gobject/index.js";
 import { IMContext } from "./imcontext.js";
+/**
+ * Supports switching between multiple input methods.
+ *
+ * Text widgets such as `GtkText` or `GtkTextView` use a `GtkIMMultiContext`
+ * to implement their `im-module` property for switching between different
+ * input methods.
+ */
 export declare class IMMulticontext extends IMContext {
+    /**
+     * Creates a new `GtkIMMulticontext`.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the id of the currently active delegate of the @context.
+     */
     getContextId(): string;
+    /**
+     * Sets the context id for @context.
+     *
+     * This causes the currently active delegate of `context` to be
+     * replaced by the delegate corresponding to the new context id.
+     *
+     * Setting this to a non-%NULL value overrides the system-wide
+     * IM module setting. See the [property@Gtk.Settings:gtk-im-module]
+     * property.
+     * @param contextId - the id to use
+     */
     setContextId(contextId?: string | null): void;
     connect(signal: "notify", handler: (self: IMMulticontext, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtk/immulticontext.js

@@ -1,7 +1,17 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { IMContext } from "./imcontext.js";
+/**
+ * Supports switching between multiple input methods.
+ *
+ * Text widgets such as `GtkText` or `GtkTextView` use a `GtkIMMultiContext`
+ * to implement their `im-module` property for switching between different
+ * input methods.
+ */
 export class IMMulticontext extends IMContext {
+    /**
+     * Creates a new `GtkIMMulticontext`.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -11,6 +21,9 @@ export class IMMulticontext extends IMContext {
             borrowed: false,
         });
     }
+    /**
+     * Gets the id of the currently active delegate of the @context.
+     */
     getContextId() {
         return call("libgtk-4.so.1", "gtk_im_multicontext_get_context_id", [
             {
@@ -19,6 +32,17 @@ export class IMMulticontext extends IMContext {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Sets the context id for @context.
+     *
+     * This causes the currently active delegate of `context` to be
+     * replaced by the delegate corresponding to the new context id.
+     *
+     * Setting this to a non-%NULL value overrides the system-wide
+     * IM module setting. See the [property@Gtk.Settings:gtk-im-module]
+     * property.
+     * @param contextId - the id to use
+     */
     setContextId(contextId) {
         call("libgtk-4.so.1", "gtk_im_multicontext_set_context_id", [
             {