@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/pango/glyph-string.js

@@ -1,7 +1,17 @@
 import { call, read, write } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * A `PangoGlyphString` is used to store strings of glyphs with geometry
+ * and visual attribute information.
+ *
+ * The storage for the glyph information is owned by the structure
+ * which simplifies memory management.
+ */
 export class GlyphString {
     ptr;
+    /**
+     * Create a new `PangoGlyphString`.
+     */
     constructor() {
         this.ptr = this.createPtr([]);
     }
@@ -12,6 +22,9 @@ export class GlyphString {
             innerType: "PangoGlyphString",
         });
     }
+    /**
+     * Copy a glyph string and associated storage.
+     */
     copy() {
         const ptr = call("libpango-1.0.so.0", "pango_glyph_string_copy", [
             {
@@ -28,6 +41,17 @@ export class GlyphString {
             return null;
         return getObject(ptr, GlyphString);
     }
+    /**
+     * Compute the logical and ink extents of a glyph string.
+     *
+     * See the documentation for [method@Pango.Font.get_glyph_extents] for details
+     * about the interpretation of the rectangles.
+     *
+     * Examples of logical (red) and ink (green) rects:
+     * @param font - a `PangoFont`
+     * @param inkRect - rectangle used to store the extents of the glyph string as drawn
+     * @param logicalRect - rectangle used to store the logical extents of the glyph string
+     */
     extents(font, inkRect, logicalRect) {
         call("libpango-1.0.so.0", "pango_glyph_string_extents", [
             {
@@ -56,6 +80,18 @@ export class GlyphString {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Computes the extents of a sub-portion of a glyph string.
+     *
+     * The extents are relative to the start of the glyph string range
+     * (the origin of their coordinate system is at the start of the range,
+     * not at the start of the entire glyph string).
+     * @param start - start index
+     * @param end - end index (the range is the set of bytes with
+     * @param font - a `PangoFont`
+     * @param inkRect - rectangle used to
+     * @param logicalRect - rectangle used to
+     */
     extentsRange(start, end, font, inkRect, logicalRect) {
         call("libpango-1.0.so.0", "pango_glyph_string_extents_range", [
             {
@@ -92,6 +128,9 @@ export class GlyphString {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Free a glyph string and associated storage.
+     */
     free() {
         call("libpango-1.0.so.0", "pango_glyph_string_free", [
             {
@@ -100,6 +139,19 @@ export class GlyphString {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Given a `PangoGlyphString` and corresponding text, determine the width
+     * corresponding to each character.
+     *
+     * When multiple characters compose a single cluster, the width of the
+     * entire cluster is divided equally among the characters.
+     *
+     * See also [method@Pango.GlyphItem.get_logical_widths].
+     * @param text - the text corresponding to the glyphs
+     * @param length - the length of @text, in bytes
+     * @param embeddingLevel - the embedding level of the string
+     * @param logicalWidths - an array whose length is
+     */
     getLogicalWidths(text, length, embeddingLevel, logicalWidths) {
         call("libpango-1.0.so.0", "pango_glyph_string_get_logical_widths", [
             {
@@ -130,6 +182,14 @@ export class GlyphString {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Computes the logical width of the glyph string.
+     *
+     * This can also be computed using [method@Pango.GlyphString.extents].
+     * However, since this only computes the width, it's much faster. This
+     * is in fact only a convenience function that computes the sum of
+     * @geometry.width for each glyph in the @glyphs.
+     */
     getWidth() {
         return call("libpango-1.0.so.0", "pango_glyph_string_get_width", [
             {
@@ -138,6 +198,20 @@ export class GlyphString {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Converts from character position to x position.
+     *
+     * The X position is measured from the left edge of the run.
+     * Character positions are obtained using font metrics for ligatures
+     * where available, and computed by dividing up each cluster
+     * into equal portions, otherwise.
+     * @param text - the text for the run
+     * @param length - the number of bytes (not characters) in @text.
+     * @param analysis - the analysis information return from [func@itemize]
+     * @param index_ - the byte index within @text
+     * @param trailing - whether we should compute the result for the beginning (%FALSE)
+     * @param xPos - location to store result
+     */
     indexToX(text, length, analysis, index_, trailing, xPos) {
         call("libpango-1.0.so.0", "pango_glyph_string_index_to_x", [
             {
@@ -174,6 +248,21 @@ export class GlyphString {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Converts from character position to x position.
+     *
+     * This variant of [method@Pango.GlyphString.index_to_x] additionally
+     * accepts a `PangoLogAttr` array. The grapheme boundary information
+     * in it can be used to disambiguate positioning inside some complex
+     * clusters.
+     * @param text - the text for the run
+     * @param length - the number of bytes (not characters) in @text.
+     * @param analysis - the analysis information return from [func@itemize]
+     * @param attrs - `PangoLogAttr` array for @text
+     * @param index_ - the byte index within @text
+     * @param trailing - whether we should compute the result for the beginning (%FALSE)
+     * @param xPos - location to store result
+     */
     indexToXFull(text, length, analysis, index_, trailing, attrs, xPos) {
         call("libpango-1.0.so.0", "pango_glyph_string_index_to_x_full", [
             {
@@ -215,6 +304,10 @@ export class GlyphString {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Resize a glyph string to the given length.
+     * @param newLen - the new length of the string
+     */
     setSize(newLen) {
         call("libpango-1.0.so.0", "pango_glyph_string_set_size", [
             {
@@ -227,6 +320,21 @@ export class GlyphString {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Convert from x offset to character position.
+     *
+     * Character positions are computed by dividing up each cluster into
+     * equal portions. In scripts where positioning within a cluster is
+     * not allowed (such as Thai), the returned value may not be a valid
+     * cursor position; the caller must combine the result with the logical
+     * attributes for the text to compute the valid cursor position.
+     * @param text - the text for the run
+     * @param length - the number of bytes (not characters) in text.
+     * @param analysis - the analysis information return from [func@itemize]
+     * @param xPos - the x offset (in Pango units)
+     * @param index_ - location to store calculated byte index
+     * @param trailing - location to store a boolean indicating
+     */
     xToIndex(text, length, analysis, xPos, index_, trailing) {
         call("libpango-1.0.so.0", "pango_glyph_string_x_to_index", [
             {
@@ -267,15 +375,21 @@ export class GlyphString {
             },
         ], { type: "undefined" });
     }
+    /** number of glyphs in this glyph string */
     get numGlyphs() {
         return read(this.ptr, { type: "int", size: 32, unsigned: false }, 0);
     }
     set numGlyphs(value) {
         write(this.ptr, { type: "int", size: 32, unsigned: false }, 0, value);
     }
+    /** array of glyph information */
     get glyphs() {
         return read(this.ptr, { type: "array", itemType: { type: "int", size: 64, unsigned: true } }, 8);
     }
+    /**
+     * logical cluster info, indexed by the byte index
+     * within the text corresponding to the glyph string
+     */
     get logClusters() {
         return read(this.ptr, { type: "int", size: 32, unsigned: false }, 16);
     }

package/dist/generated/pango/item.d.ts

@@ -1,18 +1,75 @@
 import { AttrIterator } from "./attr-iterator.js";
+/**
+ * The `PangoItem` structure stores information about a segment of text.
+ *
+ * You typically obtain `PangoItems` by itemizing a piece of text
+ * with [func@itemize].
+ */
 export declare class Item {
     ptr: unknown;
+    /**
+     * Creates a new `PangoItem` structure initialized to default values.
+     */
     constructor();
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Add attributes to a `PangoItem`.
+     *
+     * The idea is that you have attributes that don't affect itemization,
+     * such as font features, so you filter them out using
+     * [method@Pango.AttrList.filter], itemize your text, then reapply the
+     * attributes to the resulting items using this function.
+     *
+     * The `iter` should be positioned before the range of the item,
+     * and will be advanced past it. This function is meant to be called
+     * in a loop over the items resulting from itemization, while passing
+     * the iter to each call.
+     * @param iter - a `PangoAttrIterator`
+     */
     applyAttrs(iter: AttrIterator): void;
+    /**
+     * Copy an existing `PangoItem` structure.
+     */
     copy(): Item | null;
+    /**
+     * Free a `PangoItem` and all associated memory.
+     */
     free(): void;
+    /**
+     * Returns the character offset of the item from the beginning
+     * of the itemized text.
+     *
+     * If the item has not been obtained from Pango's itemization
+     * machinery, then the character offset is not available. In
+     * that case, this function returns -1.
+     */
     getCharOffset(): number;
+    /**
+     * Modifies `orig` to cover only the text after @split_index, and
+     * returns a new item that covers the text before `split_index` that
+     * used to be in @orig.
+     *
+     * You can think of `split_index` as the length of the returned item.
+     * `split_index` may not be 0, and it may not be greater than or equal
+     * to the length of `orig` (that is, there must be at least one byte
+     * assigned to each item, you can't create a zero-length item).
+     * `split_offset` is the length of the first item in chars, and must be
+     * provided because the text used to generate the item isn't available,
+     * so `pango_item_split()` can't count the char length of the split items
+     * itself.
+     * @param splitIndex - byte index of position to split item, relative to the
+     * @param splitOffset - number of chars between start of `orig` and @split_index
+     */
     split(splitIndex: number, splitOffset: number): Item;
+    /** byte offset of the start of this item in text. */
     get offset(): number;
     set offset(value: number);
+    /** length of this item in bytes. */
     get length(): number;
     set length(value: number);
+    /** number of Unicode characters in the item. */
     get numChars(): number;
     set numChars(value: number);
+    /** analysis results for the item. */
     get analysis(): number;
 }

package/dist/generated/pango/item.js

@@ -1,7 +1,16 @@
 import { call, read, write } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * The `PangoItem` structure stores information about a segment of text.
+ *
+ * You typically obtain `PangoItems` by itemizing a piece of text
+ * with [func@itemize].
+ */
 export class Item {
     ptr;
+    /**
+     * Creates a new `PangoItem` structure initialized to default values.
+     */
     constructor() {
         this.ptr = this.createPtr([]);
     }
@@ -12,6 +21,20 @@ export class Item {
             innerType: "PangoItem",
         });
     }
+    /**
+     * Add attributes to a `PangoItem`.
+     *
+     * The idea is that you have attributes that don't affect itemization,
+     * such as font features, so you filter them out using
+     * [method@Pango.AttrList.filter], itemize your text, then reapply the
+     * attributes to the resulting items using this function.
+     *
+     * The `iter` should be positioned before the range of the item,
+     * and will be advanced past it. This function is meant to be called
+     * in a loop over the items resulting from itemization, while passing
+     * the iter to each call.
+     * @param iter - a `PangoAttrIterator`
+     */
     applyAttrs(iter) {
         call("libpango-1.0.so.0", "pango_item_apply_attrs", [
             {
@@ -29,6 +52,9 @@ export class Item {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Copy an existing `PangoItem` structure.
+     */
     copy() {
         const ptr = call("libpango-1.0.so.0", "pango_item_copy", [
             {
@@ -45,6 +71,9 @@ export class Item {
             return null;
         return getObject(ptr, Item);
     }
+    /**
+     * Free a `PangoItem` and all associated memory.
+     */
     free() {
         call("libpango-1.0.so.0", "pango_item_free", [
             {
@@ -53,6 +82,14 @@ export class Item {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns the character offset of the item from the beginning
+     * of the itemized text.
+     *
+     * If the item has not been obtained from Pango's itemization
+     * machinery, then the character offset is not available. In
+     * that case, this function returns -1.
+     */
     getCharOffset() {
         return call("libpango-1.0.so.0", "pango_item_get_char_offset", [
             {
@@ -61,6 +98,22 @@ export class Item {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Modifies `orig` to cover only the text after @split_index, and
+     * returns a new item that covers the text before `split_index` that
+     * used to be in @orig.
+     *
+     * You can think of `split_index` as the length of the returned item.
+     * `split_index` may not be 0, and it may not be greater than or equal
+     * to the length of `orig` (that is, there must be at least one byte
+     * assigned to each item, you can't create a zero-length item).
+     * `split_offset` is the length of the first item in chars, and must be
+     * provided because the text used to generate the item isn't available,
+     * so `pango_item_split()` can't count the char length of the split items
+     * itself.
+     * @param splitIndex - byte index of position to split item, relative to the
+     * @param splitOffset - number of chars between start of `orig` and @split_index
+     */
     split(splitIndex, splitOffset) {
         const ptr = call("libpango-1.0.so.0", "pango_item_split", [
             {
@@ -83,24 +136,28 @@ export class Item {
         });
         return getObject(ptr, Item);
     }
+    /** byte offset of the start of this item in text. */
     get offset() {
         return read(this.ptr, { type: "int", size: 32, unsigned: false }, 0);
     }
     set offset(value) {
         write(this.ptr, { type: "int", size: 32, unsigned: false }, 0, value);
     }
+    /** length of this item in bytes. */
     get length() {
         return read(this.ptr, { type: "int", size: 32, unsigned: false }, 4);
     }
     set length(value) {
         write(this.ptr, { type: "int", size: 32, unsigned: false }, 4, value);
     }
+    /** number of Unicode characters in the item. */
     get numChars() {
         return read(this.ptr, { type: "int", size: 32, unsigned: false }, 8);
     }
     set numChars(value) {
         write(this.ptr, { type: "int", size: 32, unsigned: false }, 8, value);
     }
+    /** analysis results for the item. */
     get analysis() {
         return read(this.ptr, { type: "int", size: 64, unsigned: true }, 16);
     }

package/dist/generated/pango/language.d.ts

@@ -1,15 +1,160 @@
 import { Ref } from "@gtkx/native";
 import { Script } from "./enums.js";
+/**
+ * The `PangoLanguage` structure is used to
+ * represent a language.
+ *
+ * `PangoLanguage` pointers can be efficiently
+ * copied and compared with each other.
+ */
 export declare class Language {
     ptr: unknown;
     constructor();
     protected createPtr(_init: Record<string, unknown>): unknown;
+    /**
+     * Convert a language tag to a `PangoLanguage`.
+     *
+     * The language tag must be in a RFC-3066 format. `PangoLanguage` pointers
+     * can be efficiently copied (copy the pointer) and compared with other
+     * language tags (compare the pointer.)
+     *
+     * This function first canonicalizes the string by converting it to
+     * lowercase, mapping '_' to '-', and stripping all characters other
+     * than letters and '-'.
+     *
+     * Use [func@Pango.Language.get_default] if you want to get the
+     * `PangoLanguage` for the current locale of the process.
+     * @param language - a string representing a language tag
+     */
     static fromString(language?: string | null): Language;
+    /**
+     * Returns the `PangoLanguage` for the current locale of the process.
+     *
+     * On Unix systems, this is the return value is derived from
+     * `setlocale (LC_CTYPE, NULL)`, and the user can
+     * affect this through the environment variables LC_ALL, LC_CTYPE or
+     * LANG (checked in that order). The locale string typically is in
+     * the form lang_COUNTRY, where lang is an ISO-639 language code, and
+     * COUNTRY is an ISO-3166 country code. For instance, sv_FI for
+     * Swedish as written in Finland or pt_BR for Portuguese as written in
+     * Brazil.
+     *
+     * On Windows, the C library does not use any such environment
+     * variables, and setting them won't affect the behavior of functions
+     * like ctime(). The user sets the locale through the Regional Options
+     * in the Control Panel. The C library (in the setlocale() function)
+     * does not use country and language codes, but country and language
+     * names spelled out in English.
+     * However, this function does check the above environment
+     * variables, and does return a Unix-style locale string based on
+     * either said environment variables or the thread's current locale.
+     *
+     * Your application should call `setlocale(LC_ALL, "")` for the user
+     * settings to take effect. GTK does this in its initialization
+     * functions automatically (by calling gtk_set_locale()).
+     * See the setlocale() manpage for more details.
+     *
+     * Note that the default language can change over the life of an application.
+     *
+     * Also note that this function will not do the right thing if you
+     * use per-thread locales with uselocale(). In that case, you should
+     * just call pango_language_from_string() yourself.
+     */
     static getDefault(): Language;
+    /**
+     * Returns the list of languages that the user prefers.
+     *
+     * The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE`
+     * environment variables, in order of preference. Note that this
+     * list does not necessarily include the language returned by
+     * [func@Pango.Language.get_default].
+     *
+     * When choosing language-specific resources, such as the sample
+     * text returned by [method@Pango.Language.get_sample_string],
+     * you should first try the default language, followed by the
+     * languages returned by this function.
+     */
     static getPreferred(): Language[];
+    /**
+     * Get a string that is representative of the characters needed to
+     * render a particular language.
+     *
+     * The sample text may be a pangram, but is not necessarily. It is chosen
+     * to be demonstrative of normal text in the language, as well as exposing
+     * font feature requirements unique to the language. It is suitable for use
+     * as sample text in a font selection dialog.
+     *
+     * If `language` is %NULL, the default language as found by
+     * [func@Pango.Language.get_default] is used.
+     *
+     * If Pango does not have a sample string for @language, the classic
+     * "The quick brown fox..." is returned.  This can be detected by
+     * comparing the returned pointer value to that returned for (non-existent)
+     * language code "xx".  That is, compare to:
+     *
+     * ```
+     * pango_language_get_sample_string (pango_language_from_string ("xx"))
+     * ```
+     */
     getSampleString(): string;
+    /**
+     * Determines the scripts used to to write @language.
+     *
+     * If nothing is known about the language tag @language,
+     * or if `language` is %NULL, then %NULL is returned.
+     * The list of scripts returned starts with the script that the
+     * language uses most and continues to the one it uses least.
+     *
+     * The value `num_script` points at will be set to the number
+     * of scripts in the returned array (or zero if %NULL is returned).
+     *
+     * Most languages use only one script for writing, but there are
+     * some that use two (Latin and Cyrillic for example), and a few
+     * use three (Japanese for example). Applications should not make
+     * any assumptions on the maximum number of scripts returned
+     * though, except that it is positive if the return value is not
+     * %NULL, and it is a small number.
+     *
+     * The [method@Pango.Language.includes_script] function uses this
+     * function internally.
+     *
+     * Note: while the return value is declared as `PangoScript`, the
+     * returned values are from the `GUnicodeScript` enumeration, which
+     * may have more values. Callers need to handle unknown values.
+     * @param numScripts - location to return number of scripts
+     */
     getScripts(numScripts?: Ref<number> | null): Script[] | null;
+    /**
+     * Determines if `script` is one of the scripts used to
+     * write @language.
+     *
+     * The returned value is conservative; if nothing is known about
+     * the language tag @language, %TRUE will be returned, since, as
+     * far as Pango knows, `script` might be used to write @language.
+     *
+     * This routine is used in Pango's itemization process when
+     * determining if a supplied language tag is relevant to
+     * a particular section of text. It probably is not useful
+     * for applications in most circumstances.
+     *
+     * This function uses [method@Pango.Language.get_scripts] internally.
+     * @param script - a `PangoScript`
+     */
     includesScript(script: Script): boolean;
+    /**
+     * Checks if a language tag matches one of the elements in a list of
+     * language ranges.
+     *
+     * A language tag is considered to match a range in the list if the
+     * range is '*', the range is exactly the tag, or the range is a prefix
+     * of the tag, and the character after it in the tag is '-'.
+     * @param rangeList - a list of language ranges, separated by ';', ':',
+     */
     matches(rangeList: string): boolean;
+    /**
+     * Gets the RFC-3066 format string representing the given language tag.
+     *
+     * Returns (transfer none): a string representing the language tag
+     */
     toString(): string;
 }