@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -5,61 +5,479 @@ import * as Gio from "../gio/index.js";
 import * as Pango from "../pango/index.js";
 import { Widget } from "./widget.js";
 export declare class Label extends Widget {
+    /**
+     * Creates a new label with the given text inside it.
+     *
+     * You can pass `NULL` to get an empty label widget.
+     * @param str - the text of the label
+     */
     constructor(str?: string | null);
     constructor(...args: unknown[]);
+    /**
+     * Creates a new label with the given text inside it, and a mnemonic.
+     *
+     * If characters in `str` are preceded by an underscore, they are
+     * underlined. If you need a literal underscore character in a label, use
+     * '__' (two underscores). The first underlined character represents a
+     * keyboard accelerator called a mnemonic. The mnemonic key can be used
+     * to activate another widget, chosen automatically, or explicitly using
+     * [method@Gtk.Label.set_mnemonic_widget].
+     *
+     * If [method@Gtk.Label.set_mnemonic_widget] is not called, then the first
+     * activatable ancestor of the label will be chosen as the mnemonic
+     * widget. For instance, if the label is inside a button or menu item,
+     * the button or menu item will automatically become the mnemonic widget
+     * and be activated by the mnemonic.
+     * @param str - the text of the label, with an underscore in front of the
+     */
     static newWithMnemonic(str?: string | null): Label;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Gets the label's attribute list.
+     *
+     * This is the [struct@Pango.AttrList] that was set on the label using
+     * [method@Gtk.Label.set_attributes], if any. This function does not
+     * reflect attributes that come from the label's markup (see
+     * [method@Gtk.Label.set_markup]). If you want to get the effective
+     * attributes for the label, use
+     * `pango_layout_get_attributes (gtk_label_get_layout (self))`.
+     */
     getAttributes(): Pango.AttrList | null;
+    /**
+     * Returns the URI for the active link in the label.
+     *
+     * The active link is the one under the mouse pointer or, in a
+     * selectable label, the link in which the text cursor is currently
+     * positioned.
+     *
+     * This function is intended for use in a [signal@Gtk.Label::activate-link]
+     * handler or for use in a [signal@Gtk.Widget::query-tooltip] handler.
+     */
     getCurrentUri(): string | null;
+    /**
+     * Returns the ellipsization mode of the label.
+     *
+     * See [method@Gtk.Label.set_ellipsize].
+     */
     getEllipsize(): Pango.EllipsizeMode;
+    /**
+     * Gets the extra menu model of the label.
+     *
+     * See [method@Gtk.Label.set_extra_menu].
+     */
     getExtraMenu(): Gio.MenuModel | null;
+    /**
+     * Returns the justification of the label.
+     *
+     * See [method@Gtk.Label.set_justify].
+     */
     getJustify(): Justification;
+    /**
+     * Fetches the text from a label.
+     *
+     * The returned text includes any embedded underlines indicating
+     * mnemonics and Pango markup. (See [method@Gtk.Label.get_text]).
+     */
     getLabel(): string;
+    /**
+     * Gets the Pango layout used to display the label.
+     *
+     * The layout is useful to e.g. convert text positions to pixel
+     * positions, in combination with [method@Gtk.Label.get_layout_offsets].
+     * The returned layout is owned by the `label` so need not be
+     * freed by the caller. The `label` is free to recreate its layout
+     * at any time, so it should be considered read-only.
+     */
     getLayout(): Pango.Layout;
+    /**
+     * Obtains the coordinates where the label will draw its Pango layout.
+     *
+     * The coordinates are useful to convert mouse events into coordinates
+     * inside the [class@Pango.Layout], e.g. to take some action if some part
+     * of the label is clicked. Remember when using the [class@Pango.Layout]
+     * functions you need to convert to and from pixels using `PANGO_PIXELS()`
+     * or [const@Pango.SCALE].
+     * @param x - location to store X offset of layout
+     * @param y - location to store Y offset of layout
+     */
     getLayoutOffsets(x?: Ref<number> | null, y?: Ref<number> | null): void;
+    /**
+     * Gets the number of lines to which an ellipsized, wrapping
+     * label should be limited.
+     *
+     * See [method@Gtk.Label.set_lines].
+     */
     getLines(): number;
+    /**
+     * Retrieves the maximum width of the label in characters.
+     *
+     * See [method@Gtk.Label.set_width_chars].
+     */
     getMaxWidthChars(): number;
+    /**
+     * Return the mnemonic accelerator.
+     *
+     * If the label has been set so that it has a mnemonic key this function
+     * returns the keyval used for the mnemonic accelerator. If there is no
+     * mnemonic set up it returns `GDK_KEY_VoidSymbol`.
+     */
     getMnemonicKeyval(): number;
+    /**
+     * Retrieves the mnemonic target of this label.
+     *
+     * See [method@Gtk.Label.set_mnemonic_widget].
+     */
     getMnemonicWidget(): Widget | null;
+    /**
+     * Returns natural line wrap mode used by the label.
+     *
+     * See [method@Gtk.Label.set_natural_wrap_mode].
+     */
     getNaturalWrapMode(): NaturalWrapMode;
+    /**
+     * Returns whether the label is selectable.
+     */
     getSelectable(): boolean;
+    /**
+     * Gets the selected range of characters in the label.
+     *
+     * The returned `start` and `end` positions are in characters.
+     * @param start - return location for start of selection
+     * @param end - return location for end of selection
+     */
     getSelectionBounds(start?: Ref<number> | null, end?: Ref<number> | null): boolean;
+    /**
+     * Returns whether the label is in single line mode.
+     */
     getSingleLineMode(): boolean;
+    /**
+     * Gets the tab stops for the label.
+     *
+     * The returned array will be `NULL` if “standard” (8-space) tabs are used.
+     */
     getTabs(): Pango.TabArray | null;
+    /**
+     * Gets the text of the label.
+     *
+     * The returned text is as it appears on screen. This does not include
+     * any embedded underlines indicating mnemonics or Pango markup. (See
+     * [method@Gtk.Label.get_label])
+     */
     getText(): string;
+    /**
+     * Returns whether the label’s text is interpreted as Pango markup.
+     *
+     * See [method@Gtk.Label.set_use_markup].
+     */
     getUseMarkup(): boolean;
+    /**
+     * Returns whether underlines in the label indicate mnemonics.
+     *
+     * See [method@Gtk.Label.set_use_underline].
+     */
     getUseUnderline(): boolean;
+    /**
+     * Retrieves the desired width of the label in characters.
+     *
+     * See [method@Gtk.Label.set_width_chars].
+     */
     getWidthChars(): number;
+    /**
+     * Returns whether lines in the label are automatically wrapped.
+     *
+     * See [method@Gtk.Label.set_wrap].
+     */
     getWrap(): boolean;
+    /**
+     * Returns line wrap mode used by the label.
+     *
+     * See [method@Gtk.Label.set_wrap_mode].
+     */
     getWrapMode(): Pango.WrapMode;
+    /**
+     * Gets the `xalign` of the label.
+     *
+     * See the [property@Gtk.Label:xalign] property.
+     */
     getXalign(): number;
+    /**
+     * Gets the `yalign` of the label.
+     *
+     * See the [property@Gtk.Label:yalign] property.
+     */
     getYalign(): number;
+    /**
+     * Selects a range of characters in the label, if the label is selectable.
+     *
+     * See [method@Gtk.Label.set_selectable]. If the label is not selectable,
+     * this function has no effect. If `start_offset` or
+     * `end_offset` are -1, then the end of the label will be substituted.
+     * @param startOffset - start offset, in characters
+     * @param endOffset - end offset, in characters
+     */
     selectRegion(startOffset: number, endOffset: number): void;
+    /**
+     * Apply attributes to the label text.
+     *
+     * The attributes set with this function will be applied and merged with
+     * any other attributes previously effected by way of the
+     * [property@Gtk.Label:use-underline] or [property@Gtk.Label:use-markup]
+     * properties
+     *
+     * While it is not recommended to mix markup strings with manually set
+     * attributes, if you must; know that the attributes will be applied
+     * to the label after the markup string is parsed.
+     * @param attrs - a list of style attributes
+     */
     setAttributes(attrs?: Pango.AttrList | null): void;
+    /**
+     * Sets the mode used to ellipsize the text.
+     *
+     * The text will be ellipsized if there is not
+     * enough space to render the entire string.
+     * @param mode - the ellipsization mode
+     */
     setEllipsize(mode: Pango.EllipsizeMode): void;
+    /**
+     * Sets a menu model to add to the context menu of the label.
+     * @param model - a menu model
+     */
     setExtraMenu(model?: Gio.MenuModel | null): void;
+    /**
+     * Sets the alignment of lines in the label relative to each other.
+     *
+     * This function has no effect on labels containing only a single line.
+     *
+     * [enum@Gtk.Justification.left] is the default value when the widget
+     * is first created with [ctor@Gtk.Label.new].
+     *
+     * If you instead want to set the alignment of the label as a whole,
+     * use [method@Gtk.Widget.set_halign] instead.
+     * @param jtype - the new justification
+     */
     setJustify(jtype: Justification): void;
+    /**
+     * Sets the text of the label.
+     *
+     * The label is interpreted as including embedded underlines and/or Pango
+     * markup depending on the values of the [property@Gtk.Label:use-underline]
+     * and [property@Gtk.Label:use-markup] properties.
+     * @param str - the new text to set for the label
+     */
     setLabel(str: string): void;
+    /**
+     * Sets the number of lines to which an ellipsized, wrapping label
+     * should be limited.
+     *
+     * This has no effect if the label is not wrapping or ellipsized.
+     * Set this to -1 if you don’t want to limit the number of lines.
+     * @param lines - the desired number of lines, or -1
+     */
     setLines(lines: number): void;
+    /**
+     * Sets the labels text and attributes from markup.
+     *
+     * The string must be marked up with Pango markup
+     * (see [func@Pango.parse_markup]).
+     *
+     * If `str` is external data, you may need to escape it
+     * with [func@GLib.markup_escape_text] or [func@GLib.markup_printf_escaped]:
+     *
+     * ```c
+     * GtkWidget *self = gtk_label_new (NULL);
+     * const char *str = "...";
+     * const char *format = "<span style=\"italic\">\%s</span>";
+     * char *markup;
+     *
+     * markup = g_markup_printf_escaped (format, str);
+     * gtk_label_set_markup (GTK_LABEL (self), markup);
+     * g_free (markup);
+     * ```
+     *
+     * This function sets the [property@Gtk.Label:use-markup] property
+     * to true.
+     *
+     * Also see [method@Gtk.Label.set_text].
+     * @param str - the markup string
+     */
     setMarkup(str: string): void;
+    /**
+     * Sets the labels text, attributes and mnemonic from markup.
+     *
+     * Parses `str` which is marked up with Pango markup (see [func@Pango.parse_markup]),
+     * setting the label’s text and attribute list based on the parse results.
+     * If characters in `str` are preceded by an underscore, they are underlined
+     * indicating that they represent a keyboard accelerator called a mnemonic.
+     *
+     * The mnemonic key can be used to activate another widget, chosen
+     * automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget].
+     * @param str - the markup string
+     */
     setMarkupWithMnemonic(str: string): void;
+    /**
+     * Sets the maximum width of the label in characters.
+     * @param nChars - the new maximum width, in characters.
+     */
     setMaxWidthChars(nChars: number): void;
+    /**
+     * Associate the label with its mnemonic target.
+     *
+     * If the label has been set so that it has a mnemonic key (using
+     * i.e. [method@Gtk.Label.set_markup_with_mnemonic],
+     * [method@Gtk.Label.set_text_with_mnemonic],
+     * [ctor@Gtk.Label.new_with_mnemonic]
+     * or the [property@Gtk.Label:use_underline] property) the label can
+     * be associated with a widget that is the target of the mnemonic.
+     * When the label is inside a widget (like a [class@Gtk.Button] or a
+     * [class@Gtk.Notebook] tab) it is automatically associated with the
+     * correct widget, but sometimes (i.e. when the target is a [class@Gtk.Entry]
+     * next to the label) you need to set it explicitly using this function.
+     *
+     * The target widget will be accelerated by emitting the
+     * [signal@Gtk.Widget::mnemonic-activate] signal on it. The default handler
+     * for this signal will activate the widget if there are no mnemonic
+     * collisions and toggle focus between the colliding widgets otherwise.
+     * @param widget - the target widget
+     */
     setMnemonicWidget(widget?: Widget | null): void;
+    /**
+     * Selects the line wrapping for the natural size request.
+     *
+     * This only affects the natural size requested, for the actual wrapping used,
+     * see the [property@Gtk.Label:wrap-mode] property.
+     * @param wrapMode - the line wrapping mode
+     */
     setNaturalWrapMode(wrapMode: NaturalWrapMode): void;
+    /**
+     * Makes text in the label selectable.
+     *
+     * Selectable labels allow the user to select text from the label,
+     * for copy-and-paste.
+     * @param setting - true to allow selecting text in the label
+     */
     setSelectable(setting: boolean): void;
+    /**
+     * Sets whether the label is in single line mode.
+     * @param singleLineMode - true to enable single line mode
+     */
     setSingleLineMode(singleLineMode: boolean): void;
+    /**
+     * Sets tab stops for the label.
+     * @param tabs - tab stops
+     */
     setTabs(tabs?: Pango.TabArray | null): void;
+    /**
+     * Sets the text for the label.
+     *
+     * It overwrites any text that was there before and clears any
+     * previously set mnemonic accelerators, and sets the
+     * [property@Gtk.Label:use-underline] and
+     * [property@Gtk.Label:use-markup] properties to false.
+     *
+     * Also see [method@Gtk.Label.set_markup].
+     * @param str - the text to show in @self
+     */
     setText(str: string): void;
+    /**
+     * Sets the text for the label, with mnemonics.
+     *
+     * If characters in `str` are preceded by an underscore, they are underlined
+     * indicating that they represent a keyboard accelerator called a mnemonic.
+     * The mnemonic key can be used to activate another widget, chosen
+     * automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget].
+     * @param str - the text
+     */
     setTextWithMnemonic(str: string): void;
+    /**
+     * Sets whether the text of the label contains markup.
+     *
+     * See [method@Gtk.Label.set_markup].
+     * @param setting - true if the label’s text should be parsed for markup.
+     */
     setUseMarkup(setting: boolean): void;
+    /**
+     * Sets whether underlines in the text indicate mnemonics.
+     * @param setting - true if underlines in the text indicate mnemonics
+     */
     setUseUnderline(setting: boolean): void;
+    /**
+     * Sets the desired width in characters of the label.
+     * @param nChars - the new desired width, in characters.
+     */
     setWidthChars(nChars: number): void;
+    /**
+     * Toggles line wrapping within the label.
+     *
+     * True makes it break lines if text exceeds the widget’s size.
+     * false lets the text get cut off by the edge of the widget if
+     * it exceeds the widget size.
+     *
+     * Note that setting line wrapping to true does not make the label
+     * wrap at its parent widget’s width, because GTK widgets conceptually
+     * can’t make their requisition depend on the parent  widget’s size.
+     * For a label that wraps at a specific position, set the label’s width
+     * using [method@Gtk.Widget.set_size_request].
+     * @param wrap - whether to wrap lines
+     */
     setWrap(wrap: boolean): void;
+    /**
+     * Controls how line wrapping is done.
+     *
+     * This only affects the label if line wrapping is on. (See
+     * [method@Gtk.Label.set_wrap])
+     *
+     * The default is [enum@Pango.WrapMode.word], which means
+     * wrap on word boundaries.
+     *
+     * For sizing behavior, also consider the
+     * [property@Gtk.Label:natural-wrap-mode] property.
+     * @param wrapMode - the line wrapping mode
+     */
     setWrapMode(wrapMode: Pango.WrapMode): void;
+    /**
+     * Sets the `xalign` of the label.
+     *
+     * See the [property@Gtk.Label:xalign] property.
+     * @param xalign - the new xalign value, between 0 and 1
+     */
     setXalign(xalign: number): void;
+    /**
+     * Sets the `yalign` of the label.
+     *
+     * See the [property@Gtk.Label:yalign] property.
+     * @param yalign - the new yalign value, between 0 and 1
+     */
     setYalign(yalign: number): 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;
     connect(signal: "activate-current-link", handler: (self: Label) => void, after?: boolean): number;
     connect(signal: "activate-link", handler: (self: Label, uri: string) => boolean, after?: boolean): number;