@ts-for-gir/templates 4.0.0-beta.38 → 4.0.0-beta.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-for-gir/templates",
-  "version": "4.0.0-beta.38",
+  "version": "4.0.0-beta.40",
   "description": "Templates for ts-for-gir",
   "type": "module",
   "main": "package.json",

package/templates/gjs/cairo.d.ts

@@ -52,6 +52,23 @@ import Cairo from '<%- Cairo.importPath %>';
         yAdvance: number;
     }
 
+    /**
+     * Font metrics in user-space coordinates (cairo_font_extents_t).
+     * Not present in cairo-gobject GIR; defined locally to match the C API.
+     */
+    export interface FontExtents {
+        /** Distance the font extends above the baseline */
+        ascent: number;
+        /** Distance the font extends below the baseline (positive for typical fonts) */
+        descent: number;
+        /** Recommended vertical distance between baselines for consecutive lines */
+        height: number;
+        /** Maximum X advance for any glyph */
+        max_x_advance: number;
+        /** Maximum Y advance for any glyph (typically 0 for horizontal text) */
+        max_y_advance: number;
+    }
+
     /**
      * The main Cairo drawing context
      * 
@@ -540,6 +557,39 @@ import Cairo from '<%- Cairo.importPath %>';
          */
         textExtents(utf8: string): TextExtents;
 
+        /**
+         * Gets the font extents for the currently selected font
+         * @returns Font extents in user-space coordinates
+         */
+        getFontExtents(): FontExtents;
+
+        /**
+         * Renders an array of glyphs at the current point (low-level text API)
+         * @param glyphs Array of glyphs to show
+         */
+        showGlyphs(glyphs: Glyph[]): void;
+
+        /**
+         * Renders glyphs with embedded text and cluster mapping (e.g. for PDF/PS)
+         * @param utf8 UTF-8 text string
+         * @param glyphs Array of glyphs
+         * @param clusters Cluster mapping (bytes to glyphs)
+         * @param clusterFlags Direction of cluster mapping
+         */
+        showTextGlyphs(
+            utf8: string,
+            glyphs: Glyph[],
+            clusters: TextCluster[],
+            clusterFlags: TextClusterFlags,
+        ): void;
+
+        /**
+         * Computes the extents of an array of glyphs in user-space coordinates
+         * @param glyphs Array of glyphs
+         * @returns Extents as [x_bearing, y_bearing, width, height, x_advance, y_advance]
+         */
+        glyphExtents(glyphs: Glyph[]): TextExtents;
+
         /**
          * Translates the current transformation matrix
          * @param tx Translation in the X direction
@@ -615,6 +665,21 @@ import Cairo from '<%- Cairo.importPath %>';
          * Finishes the surface and drops all references to external resources
          */
         finish(): void;
+
+        /**
+         * Attaches user data to the surface (C API: cairo_surface_set_user_data)
+         * @param key Key for the user data
+         * @param userData Data to attach
+         * @param destroy Optional callback when the surface is destroyed or data is replaced
+         */
+        set_user_data(key: UserDataKey, userData: unknown, destroy?: (data: unknown) => void): Status;
+
+        /**
+         * Returns user data attached to the surface (C API: cairo_surface_get_user_data)
+         * @param key Key used when setting the data
+         * @returns The attached data or null
+         */
+        get_user_data(key: UserDataKey): unknown;
     }
 
     /**
@@ -828,14 +893,35 @@ import Cairo from '<%- Cairo.importPath %>';
     export class ScaledFont extends Cairo.ScaledFont {}
 
     /**
-     * A glyph object used for storing and manipulating glyphs
+     * A glyph object used for storing and manipulating glyphs (cairo_glyph_t).
+     * Defined locally so the template works even when the generated cairo-1.0
+     * does not include this record (GIR may omit it in some setups).
      */
-    export class Glyph extends Cairo.Glyph {}
+    export interface Glyph {
+        index: number;
+        x: number;
+        y: number;
+    }
 
     /**
-     * A text cluster object used for storing and manipulating text clusters
+     * A text cluster object used for storing and manipulating text clusters (cairo_text_cluster_t).
+     * Defined locally so the template works even when the generated cairo-1.0
+     * does not include this record (GIR may omit it in some setups).
      */
-    export class TextCluster extends Cairo.TextCluster {}
+    export interface TextCluster {
+        num_bytes: number;
+        num_glyphs: number;
+    }
+
+    /**
+     * Key for attaching user data to surfaces/contexts (cairo_user_data_key_t).
+     * In C only the key's address matters; in GJS any object can serve as key.
+     * Not in cairo-gobject GIR; defined locally for set_user_data/get_user_data.
+     */
+    export interface UserDataKey {
+        /** Unused in C; present only for ABI. In GJS keys are typically plain objects. */
+        readonly unused?: number;
+    }
 
     /**
      * A font options object used for storing and manipulating font options