@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/pango/glyph-item-iter.d.ts

@@ -7,15 +7,87 @@ export interface GlyphItemIterInit {
     endIndex?: number;
     endChar?: number;
 }
+/**
+ * A `PangoGlyphItemIter` is an iterator over the clusters in a
+ * `PangoGlyphItem`.
+ *
+ * The *forward direction* of the iterator is the logical direction of text.
+ * That is, with increasing `start_index` and `start_char` values. If `glyph_item` is right-to-left (that is, if `glyph_item->item->analysis.level` is odd),
+ * then `start_glyph` decreases as the iterator moves forward.  Moreover,
+ * in right-to-left cases, `start_glyph` is greater than @end_glyph.
+ *
+ * An iterator should be initialized using either
+ * pango_glyph_item_iter_init_start() or
+ * pango_glyph_item_iter_init_end(), for forward and backward iteration
+ * respectively, and walked over using any desired mixture of
+ * pango_glyph_item_iter_next_cluster() and
+ * pango_glyph_item_iter_prev_cluster().
+ *
+ * A common idiom for doing a forward iteration over the clusters is:
+ *
+ * ```
+ * PangoGlyphItemIter cluster_iter;
+ * gboolean have_cluster;
+ *
+ * for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter,
+ * glyph_item, text);
+ * have_cluster;
+ * have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
+ * {
+ * ...
+ * }
+ * ```
+ *
+ * Note that `text` is the start of the text for layout, which is then
+ * indexed by `glyph_item->item->offset` to get to the text of @glyph_item.
+ * The `start_index` and `end_index` values can directly index into @text. The
+ * @start_glyph, @end_glyph, @start_char, and `end_char` values however are
+ * zero-based for the @glyph_item.  For each cluster, the item pointed at by
+ * the start variables is included in the cluster while the one pointed at by
+ * end variables is not.
+ *
+ * None of the members of a `PangoGlyphItemIter` should be modified manually.
+ */
 export declare class GlyphItemIter {
     ptr: unknown;
     constructor(init?: GlyphItemIterInit);
     protected createPtr(init: GlyphItemIterInit): unknown;
+    /**
+     * Make a shallow copy of an existing `PangoGlyphItemIter` structure.
+     */
     copy(): GlyphItemIter | null;
+    /**
+     * Frees a `PangoGlyphItem`Iter.
+     */
     free(): void;
+    /**
+     * Initializes a `PangoGlyphItemIter` structure to point to the
+     * last cluster in a glyph item.
+     *
+     * See `PangoGlyphItemIter` for details of cluster orders.
+     * @param glyphItem - the glyph item to iterate over
+     * @param text - text corresponding to the glyph item
+     */
     initEnd(glyphItem: GlyphItem, text: string): boolean;
+    /**
+     * Initializes a `PangoGlyphItemIter` structure to point to the
+     * first cluster in a glyph item.
+     *
+     * See `PangoGlyphItemIter` for details of cluster orders.
+     * @param glyphItem - the glyph item to iterate over
+     * @param text - text corresponding to the glyph item
+     */
     initStart(glyphItem: GlyphItem, text: string): boolean;
+    /**
+     * Advances the iterator to the next cluster in the glyph item.
+     *
+     * See `PangoGlyphItemIter` for details of cluster orders.
+     */
     nextCluster(): boolean;
+    /**
+     * Moves the iterator to the preceding cluster in the glyph item.
+     * See `PangoGlyphItemIter` for details of cluster orders.
+     */
     prevCluster(): boolean;
     get glyphItem(): GlyphItem;
     get text(): string;

package/dist/generated/pango/glyph-item-iter.js

@@ -1,5 +1,46 @@
 import { alloc, call, read, write } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * A `PangoGlyphItemIter` is an iterator over the clusters in a
+ * `PangoGlyphItem`.
+ *
+ * The *forward direction* of the iterator is the logical direction of text.
+ * That is, with increasing `start_index` and `start_char` values. If `glyph_item` is right-to-left (that is, if `glyph_item->item->analysis.level` is odd),
+ * then `start_glyph` decreases as the iterator moves forward.  Moreover,
+ * in right-to-left cases, `start_glyph` is greater than @end_glyph.
+ *
+ * An iterator should be initialized using either
+ * pango_glyph_item_iter_init_start() or
+ * pango_glyph_item_iter_init_end(), for forward and backward iteration
+ * respectively, and walked over using any desired mixture of
+ * pango_glyph_item_iter_next_cluster() and
+ * pango_glyph_item_iter_prev_cluster().
+ *
+ * A common idiom for doing a forward iteration over the clusters is:
+ *
+ * ```
+ * PangoGlyphItemIter cluster_iter;
+ * gboolean have_cluster;
+ *
+ * for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter,
+ * glyph_item, text);
+ * have_cluster;
+ * have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
+ * {
+ * ...
+ * }
+ * ```
+ *
+ * Note that `text` is the start of the text for layout, which is then
+ * indexed by `glyph_item->item->offset` to get to the text of @glyph_item.
+ * The `start_index` and `end_index` values can directly index into @text. The
+ * @start_glyph, @end_glyph, @start_char, and `end_char` values however are
+ * zero-based for the @glyph_item.  For each cluster, the item pointed at by
+ * the start variables is included in the cluster while the one pointed at by
+ * end variables is not.
+ *
+ * None of the members of a `PangoGlyphItemIter` should be modified manually.
+ */
 export class GlyphItemIter {
     ptr;
     constructor(init = {}) {
@@ -21,6 +62,9 @@ export class GlyphItemIter {
             write(ptr, { type: "int", size: 32, unsigned: false }, 36, init.endChar);
         return ptr;
     }
+    /**
+     * Make a shallow copy of an existing `PangoGlyphItemIter` structure.
+     */
     copy() {
         const ptr = call("libpango-1.0.so.0", "pango_glyph_item_iter_copy", [
             {
@@ -37,6 +81,9 @@ export class GlyphItemIter {
             return null;
         return getObject(ptr, GlyphItemIter);
     }
+    /**
+     * Frees a `PangoGlyphItem`Iter.
+     */
     free() {
         call("libpango-1.0.so.0", "pango_glyph_item_iter_free", [
             {
@@ -45,6 +92,14 @@ export class GlyphItemIter {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Initializes a `PangoGlyphItemIter` structure to point to the
+     * last cluster in a glyph item.
+     *
+     * See `PangoGlyphItemIter` for details of cluster orders.
+     * @param glyphItem - the glyph item to iterate over
+     * @param text - text corresponding to the glyph item
+     */
     initEnd(glyphItem, text) {
         return call("libpango-1.0.so.0", "pango_glyph_item_iter_init_end", [
             {
@@ -66,6 +121,14 @@ export class GlyphItemIter {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Initializes a `PangoGlyphItemIter` structure to point to the
+     * first cluster in a glyph item.
+     *
+     * See `PangoGlyphItemIter` for details of cluster orders.
+     * @param glyphItem - the glyph item to iterate over
+     * @param text - text corresponding to the glyph item
+     */
     initStart(glyphItem, text) {
         return call("libpango-1.0.so.0", "pango_glyph_item_iter_init_start", [
             {
@@ -87,6 +150,11 @@ export class GlyphItemIter {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Advances the iterator to the next cluster in the glyph item.
+     *
+     * See `PangoGlyphItemIter` for details of cluster orders.
+     */
     nextCluster() {
         return call("libpango-1.0.so.0", "pango_glyph_item_iter_next_cluster", [
             {
@@ -95,6 +163,10 @@ export class GlyphItemIter {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Moves the iterator to the preceding cluster in the glyph item.
+     * See `PangoGlyphItemIter` for details of cluster orders.
+     */
     prevCluster() {
         return call("libpango-1.0.so.0", "pango_glyph_item_iter_prev_cluster", [
             {

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

@@ -7,22 +7,104 @@ export interface GlyphItemInit {
     startXOffset?: number;
     endXOffset?: number;
 }
+/**
+ * A `PangoGlyphItem` is a pair of a `PangoItem` and the glyphs
+ * resulting from shaping the items text.
+ *
+ * As an example of the usage of `PangoGlyphItem`, the results
+ * of shaping text with `PangoLayout` is a list of `PangoLayoutLine`,
+ * each of which contains a list of `PangoGlyphItem`.
+ */
 export declare class GlyphItem {
     ptr: unknown;
     constructor(init?: GlyphItemInit);
     protected createPtr(init: GlyphItemInit): unknown;
+    /**
+     * Splits a shaped item (`PangoGlyphItem`) into multiple items based
+     * on an attribute list.
+     *
+     * The idea is that if you have attributes that don't affect shaping,
+     * such as color or underline, to avoid affecting shaping, you filter
+     * them out ([method@Pango.AttrList.filter]), apply the shaping process
+     * and then reapply them to the result using this function.
+     *
+     * All attributes that start or end inside a cluster are applied
+     * to that cluster; for instance, if half of a cluster is underlined
+     * and the other-half strikethrough, then the cluster will end
+     * up with both underline and strikethrough attributes. In these
+     * cases, it may happen that @item->extra_attrs for some of the
+     * result items can have multiple attributes of the same type.
+     *
+     * This function takes ownership of @glyph_item; it will be reused
+     * as one of the elements in the list.
+     * @param text - text that `list` applies to
+     * @param list - a `PangoAttrList`
+     */
     applyAttrs(text: string, list: AttrList): GlyphItem[];
+    /**
+     * Make a deep copy of an existing `PangoGlyphItem` structure.
+     */
     copy(): GlyphItem | null;
+    /**
+     * Frees a `PangoGlyphItem` and resources to which it points.
+     */
     free(): void;
+    /**
+     * Given a `PangoGlyphItem` and the 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.GlyphString.get_logical_widths].
+     * @param text - text that `glyph_item` corresponds to
+     * @param logicalWidths - an array whose length
+     */
     getLogicalWidths(text: string, logicalWidths: Ref<number[]>): void;
+    /**
+     * Adds spacing between the graphemes of `glyph_item` to
+     * give the effect of typographic letter spacing.
+     * @param text - text that `glyph_item` corresponds to
+     * @param logAttrs - logical attributes for the item
+     * @param letterSpacing - amount of letter spacing to add
+     */
     letterSpace(text: string, logAttrs: number[], letterSpacing: number): void;
+    /**
+     * 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).
+     *
+     * This function is similar in function to pango_item_split() (and uses
+     * it internally.)
+     * @param text - text to which positions in `orig` apply
+     * @param splitIndex - byte index of position to split item, relative to the
+     */
     split(text: string, splitIndex: number): GlyphItem | null;
+    /** corresponding `PangoItem` */
     get item(): Item;
+    /** corresponding `PangoGlyphString` */
     get glyphs(): GlyphString;
+    /**
+     * shift of the baseline, relative to the baseline
+     * of the containing line. Positive values shift upwards
+     */
     get yOffset(): number;
     set yOffset(value: number);
+    /**
+     * horizontal displacement to apply before the
+     * glyph item. Positive values shift right
+     */
     get startXOffset(): number;
     set startXOffset(value: number);
+    /**
+     * horizontal displacement to apply after th
+     * glyph item. Positive values shift right
+     */
     get endXOffset(): number;
     set endXOffset(value: number);
 }

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

@@ -1,5 +1,13 @@
 import { alloc, call, read, write } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * A `PangoGlyphItem` is a pair of a `PangoItem` and the glyphs
+ * resulting from shaping the items text.
+ *
+ * As an example of the usage of `PangoGlyphItem`, the results
+ * of shaping text with `PangoLayout` is a list of `PangoLayoutLine`,
+ * each of which contains a list of `PangoGlyphItem`.
+ */
 export class GlyphItem {
     ptr;
     constructor(init = {}) {
@@ -15,6 +23,27 @@ export class GlyphItem {
             write(ptr, { type: "int", size: 32, unsigned: false }, 24, init.endXOffset);
         return ptr;
     }
+    /**
+     * Splits a shaped item (`PangoGlyphItem`) into multiple items based
+     * on an attribute list.
+     *
+     * The idea is that if you have attributes that don't affect shaping,
+     * such as color or underline, to avoid affecting shaping, you filter
+     * them out ([method@Pango.AttrList.filter]), apply the shaping process
+     * and then reapply them to the result using this function.
+     *
+     * All attributes that start or end inside a cluster are applied
+     * to that cluster; for instance, if half of a cluster is underlined
+     * and the other-half strikethrough, then the cluster will end
+     * up with both underline and strikethrough attributes. In these
+     * cases, it may happen that @item->extra_attrs for some of the
+     * result items can have multiple attributes of the same type.
+     *
+     * This function takes ownership of @glyph_item; it will be reused
+     * as one of the elements in the list.
+     * @param text - text that `list` applies to
+     * @param list - a `PangoAttrList`
+     */
     applyAttrs(text, list) {
         return call("libpango-1.0.so.0", "pango_glyph_item_apply_attrs", [
             {
@@ -45,6 +74,9 @@ export class GlyphItem {
             borrowed: true,
         });
     }
+    /**
+     * Make a deep copy of an existing `PangoGlyphItem` structure.
+     */
     copy() {
         const ptr = call("libpango-1.0.so.0", "pango_glyph_item_copy", [
             {
@@ -61,6 +93,9 @@ export class GlyphItem {
             return null;
         return getObject(ptr, GlyphItem);
     }
+    /**
+     * Frees a `PangoGlyphItem` and resources to which it points.
+     */
     free() {
         call("libpango-1.0.so.0", "pango_glyph_item_free", [
             {
@@ -69,6 +104,17 @@ export class GlyphItem {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Given a `PangoGlyphItem` and the 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.GlyphString.get_logical_widths].
+     * @param text - text that `glyph_item` corresponds to
+     * @param logicalWidths - an array whose length
+     */
     getLogicalWidths(text, logicalWidths) {
         call("libpango-1.0.so.0", "pango_glyph_item_get_logical_widths", [
             {
@@ -91,6 +137,13 @@ export class GlyphItem {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds spacing between the graphemes of `glyph_item` to
+     * give the effect of typographic letter spacing.
+     * @param text - text that `glyph_item` corresponds to
+     * @param logAttrs - logical attributes for the item
+     * @param letterSpacing - amount of letter spacing to add
+     */
     letterSpace(text, logAttrs, letterSpacing) {
         call("libpango-1.0.so.0", "pango_glyph_item_letter_space", [
             {
@@ -114,6 +167,21 @@ export class GlyphItem {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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).
+     *
+     * This function is similar in function to pango_item_split() (and uses
+     * it internally.)
+     * @param text - text to which positions in `orig` apply
+     * @param splitIndex - byte index of position to split item, relative to the
+     */
     split(text, splitIndex) {
         const ptr = call("libpango-1.0.so.0", "pango_glyph_item_split", [
             {
@@ -138,9 +206,11 @@ export class GlyphItem {
             return null;
         return getObject(ptr, GlyphItem);
     }
+    /** corresponding `PangoItem` */
     get item() {
         return read(this.ptr, { type: "boxed", innerType: "PangoItem", lib: "libpango-1.0.so.0" }, 0);
     }
+    /** corresponding `PangoGlyphString` */
     get glyphs() {
         return read(this.ptr, {
             type: "boxed",
@@ -148,18 +218,30 @@ export class GlyphItem {
             lib: "libpango-1.0.so.0",
         }, 8);
     }
+    /**
+     * shift of the baseline, relative to the baseline
+     * of the containing line. Positive values shift upwards
+     */
     get yOffset() {
         return read(this.ptr, { type: "int", size: 32, unsigned: false }, 16);
     }
     set yOffset(value) {
         write(this.ptr, { type: "int", size: 32, unsigned: false }, 16, value);
     }
+    /**
+     * horizontal displacement to apply before the
+     * glyph item. Positive values shift right
+     */
     get startXOffset() {
         return read(this.ptr, { type: "int", size: 32, unsigned: false }, 20);
     }
     set startXOffset(value) {
         write(this.ptr, { type: "int", size: 32, unsigned: false }, 20, value);
     }
+    /**
+     * horizontal displacement to apply after th
+     * glyph item. Positive values shift right
+     */
     get endXOffset() {
         return read(this.ptr, { type: "int", size: 32, unsigned: false }, 24);
     }

package/dist/generated/pango/glyph-string.d.ts

@@ -1,22 +1,136 @@
 import { Ref } from "@gtkx/native";
 import { Font } from "./font.js";
+/**
+ * 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 declare class GlyphString {
     ptr: unknown;
+    /**
+     * Create a new `PangoGlyphString`.
+     */
     constructor();
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Copy a glyph string and associated storage.
+     */
     copy(): GlyphString | null;
+    /**
+     * 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: Font, inkRect?: Ref<number> | null, logicalRect?: Ref<number> | null): void;
+    /**
+     * 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: number, end: number, font: Font, inkRect?: Ref<number> | null, logicalRect?: Ref<number> | null): void;
+    /**
+     * Free a glyph string and associated storage.
+     */
     free(): void;
+    /**
+     * 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: string, length: number, embeddingLevel: number, logicalWidths: Ref<number[]>): void;
+    /**
+     * 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(): number;
+    /**
+     * 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: string, length: number, analysis: number, index_: number, trailing: boolean, xPos?: Ref<number> | null): void;
+    /**
+     * 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: string, length: number, analysis: number, index_: number, trailing: boolean, attrs?: number | null, xPos?: Ref<number> | null): void;
+    /**
+     * Resize a glyph string to the given length.
+     * @param newLen - the new length of the string
+     */
     setSize(newLen: number): void;
+    /**
+     * 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: string, length: number, analysis: number, xPos: number, index_?: Ref<number> | null, trailing?: Ref<number> | null): void;
+    /** number of glyphs in this glyph string */
     get numGlyphs(): number;
     set numGlyphs(value: number);
+    /** array of glyph information */
     get glyphs(): number[];
+    /**
+     * logical cluster info, indexed by the byte index
+     * within the text corresponding to the glyph string
+     */
     get logClusters(): number;
     set logClusters(value: number);
 }