@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -8,69 +8,506 @@ import * as Graphene from "../graphene/index.js";
 import * as Pango from "../pango/index.js";
 import { Widget } from "./widget.js";
 export declare class Text extends Widget {
+    /**
+     * Creates a new `GtkText`.
+     */
     constructor(...args: unknown[]);
+    /**
+     * Creates a new `GtkText` with the specified buffer.
+     * @param buffer - the buffer to use
+     */
     static newWithBuffer(buffer: EntryBuffer): Text;
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Determines the positions of the strong and weak cursors for a
+     * given character position.
+     *
+     * The position of each cursor is stored as a zero-width rectangle.
+     * The strong cursor location is the location where characters of
+     * the directionality equal to the base direction are inserted.
+     * The weak cursor location is the location where characters of
+     * the directionality opposite to the base direction are inserted.
+     *
+     * The rectangle positions are in widget coordinates.
+     * @param position - the character position
+     * @param strong - location to store the strong cursor position
+     * @param weak - location to store the weak cursor position
+     */
     computeCursorExtents(position: number, strong?: Ref<Graphene.Rect> | null, weak?: Ref<Graphene.Rect> | null): void;
+    /**
+     * Returns whether pressing `Enter` will activate
+     * the default widget for the window containing the widget.
+     *
+     * See [method@Gtk.Text.set_activates_default].
+     */
     getActivatesDefault(): boolean;
+    /**
+     * Gets the attribute list that was set on the text widget.
+     *
+     * See [method@Gtk.Text.set_attributes].
+     */
     getAttributes(): Pango.AttrList | null;
+    /**
+     * Get the entry buffer object which holds the text for
+     * this widget.
+     */
     getBuffer(): EntryBuffer;
+    /**
+     * Returns whether Emoji completion is enabled.
+     */
     getEnableEmojiCompletion(): boolean;
+    /**
+     * Gets the extra menu model of the text widget.
+     *
+     * See [method@Gtk.Text.set_extra_menu].
+     */
     getExtraMenu(): Gio.MenuModel | null;
+    /**
+     * Gets the input hints of the text widget.
+     */
     getInputHints(): InputHints;
+    /**
+     * Gets the input purpose of the text widget.
+     */
     getInputPurpose(): InputPurpose;
+    /**
+     * Retrieves the character displayed when visibility is set to false.
+     *
+     * Note that GTK does not compute this value unless it needs it,
+     * so the value returned by this function is not very useful unless
+     * it has been explicitly set with [method@Gtk.Text.set_invisible_char].
+     */
     getInvisibleChar(): number;
+    /**
+     * Retrieves the maximum allowed length of the contents.
+     *
+     * See [method@Gtk.Text.set_max_length].
+     *
+     * This is equivalent to getting @self's `GtkEntryBuffer` and
+     * calling [method@Gtk.EntryBuffer.get_max_length] on it.
+     */
     getMaxLength(): number;
+    /**
+     * Gets whether text is overwritten when typing.
+     *
+     * See [method@Gtk.Text.set_overwrite_mode].
+     */
     getOverwriteMode(): boolean;
+    /**
+     * Retrieves the text that will be displayed when the text widget
+     * is empty and unfocused
+     *
+     * See [method@Gtk.Text.set_placeholder_text].
+     */
     getPlaceholderText(): string | null;
+    /**
+     * Returns whether the text widget will grow and shrink
+     * with the content.
+     */
     getPropagateTextWidth(): boolean;
+    /**
+     * Gets the tab stops for the text widget.
+     *
+     * See [method@Gtk.Text.set_tabs].
+     */
     getTabs(): Pango.TabArray | null;
+    /**
+     * Retrieves the length of the contents.
+     *
+     * This is equivalent to getting @self's `GtkEntryBuffer`
+     * and calling [method@Gtk.EntryBuffer.get_length] on it.
+     */
     getTextLength(): number;
+    /**
+     * Returns whether pasted text will be truncated to the first line.
+     */
     getTruncateMultiline(): boolean;
+    /**
+     * Retrieves whether the text is visible.
+     */
     getVisibility(): boolean;
+    /**
+     * Causes the text widget to have the keyboard focus.
+     *
+     * It behaves like [method@Gtk.Widget.grab_focus],
+     * except that it does not select the contents of @self.
+     *
+     * You only want to call this on some special entries
+     * which the user usually doesn't want to replace all
+     * text in, such as search-as-you-type entries.
+     */
     grabFocusWithoutSelecting(): boolean;
+    /**
+     * Sets whether pressing `Enter` will activate
+     * the default widget.
+     *
+     * This usually means that the dialog containing `self` will
+     * be closed, since the default widget is usually one of
+     * the dialog buttons.
+     * @param activates - true to activate window’s default widget on
+     */
     setActivatesDefault(activates: boolean): void;
+    /**
+     * Apply attributes to the contents of the text widget.
+     * @param attrs - a list of style attributes
+     */
     setAttributes(attrs?: Pango.AttrList | null): void;
+    /**
+     * Set the entry buffer object which holds the text for
+     * this widget.
+     * @param buffer - an entry buffer object
+     */
     setBuffer(buffer: EntryBuffer): void;
+    /**
+     * Sets whether Emoji completion is enabled.
+     *
+     * If it is, typing ':', followed by a recognized keyword,
+     * will pop up a window with suggested Emojis matching the
+     * keyword.
+     * @param enableEmojiCompletion - true to enable Emoji completion
+     */
     setEnableEmojiCompletion(enableEmojiCompletion: boolean): void;
+    /**
+     * Sets a menu model to add to the context menu of the text widget.
+     * @param model - a menu model
+     */
     setExtraMenu(model?: Gio.MenuModel | null): void;
+    /**
+     * Sets hints that allow input methods to fine-tune their behaviour.
+     * @param hints - input hints
+     */
     setInputHints(hints: InputHints): void;
+    /**
+     * Sets the input purpose of the text widget.
+     *
+     * The input purpose can be used by on-screen keyboards
+     * and other input methods to adjust their behaviour.
+     * @param purpose - the input purpose
+     */
     setInputPurpose(purpose: InputPurpose): void;
+    /**
+     * Sets the character to use when in “password mode”.
+     *
+     * By default, GTK picks the best invisible char available in the
+     * current font. If you set the invisible char to 0, then the user
+     * will get no feedback at all; there will be no text on the screen
+     * as they type.
+     * @param ch - a Unicode character
+     */
     setInvisibleChar(ch: number): void;
+    /**
+     * Sets the maximum allowed length of the contents.
+     *
+     * If the current contents are longer than the given length,
+     * they will be truncated to fit.
+     *
+     * This is equivalent to getting @self's `GtkEntryBuffer` and
+     * calling [method@Gtk.EntryBuffer.set_max_length] on it.
+     * @param length - the maximum length of the text, or 0 for no maximum.
+     */
     setMaxLength(length: number): void;
+    /**
+     * Sets whether the text is overwritten when typing.
+     * @param overwrite - new value
+     */
     setOverwriteMode(overwrite: boolean): void;
+    /**
+     * Sets the text to be displayed when the text widget is
+     * empty and unfocused.
+     *
+     * This can be used to give a visual hint of the expected
+     * contents of the text widget.
+     * @param text - a string to be displayed when `self`   is empty and unfocused
+     */
     setPlaceholderText(text?: string | null): void;
+    /**
+     * Sets whether the text widget should grow and shrink with the content.
+     * @param propagateTextWidth - true to propagate the text width
+     */
     setPropagateTextWidth(propagateTextWidth: boolean): void;
+    /**
+     * Sets tab stops for the text widget.
+     * @param tabs - tab stops
+     */
     setTabs(tabs?: Pango.TabArray | null): void;
+    /**
+     * Sets whether pasted text should be truncated to the first line.
+     * @param truncateMultiline - true to truncate multi-line text
+     */
     setTruncateMultiline(truncateMultiline: boolean): void;
+    /**
+     * Sets whether the contents of the text widget are visible or not.
+     *
+     * When visibility is set to false, characters are displayed
+     * as the invisible char, and it will also appear that way when
+     * the text in the widget is copied to the clipboard.
+     *
+     * By default, GTK picks the best invisible character available
+     * in the current font, but it can be changed with
+     * [method@Gtk.Text.set_invisible_char].
+     *
+     * Note that you probably want to set [property@Gtk.Text:input-purpose]
+     * to [enum@Gtk.InputPurpose.password] or [enum@Gtk.InputPurpose.pin]
+     * to inform input methods about the purpose of this widget, in addition
+     * to setting visibility to false.
+     * @param visible - true if the contents of the text widget are displayed
+     */
     setVisibility(visible: boolean): void;
+    /**
+     * Unsets the invisible char.
+     *
+     * After calling this, the default invisible char is used again.
+     */
     unsetInvisibleChar(): void;
+    /**
+     * Updates the position of the caret.
+     *
+     * Implementations of the `GtkAccessibleText` interface should call this
+     * function every time the caret has moved, in order to notify assistive
+     * technologies.
+     */
     updateCaretPosition(): void;
+    /**
+     * Notifies assistive technologies of a change in contents.
+     *
+     * Implementations of the `GtkAccessibleText` interface should call this
+     * function every time their contents change as the result of an operation,
+     * like an insertion or a removal.
+     *
+     * Note: If the change is a deletion, this function must be called *before*
+     * removing the contents, if it is an insertion, it must be called *after*
+     * inserting the new contents.
+     * @param change - the type of change in the contents
+     * @param start - the starting offset of the change, in characters
+     * @param end - the end offset of the change, in characters
+     */
     updateContents(change: AccessibleTextContentChange, start: number, end: number): void;
+    /**
+     * Updates the boundary of the selection.
+     *
+     * Implementations of the `GtkAccessibleText` interface should call this
+     * function every time the selection has moved, in order to notify assistive
+     * technologies.
+     */
     updateSelectionBound(): 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: Text) => void, after?: boolean): number;
     connect(signal: "backspace", handler: (self: Text) => void, after?: boolean): number;