@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/pango/font-description.js

@@ -1,7 +1,18 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * A `PangoFontDescription` describes a font in an implementation-independent
+ * manner.
+ *
+ * `PangoFontDescription` structures are used both to list what fonts are
+ * available on the system and also for specifying the characteristics of
+ * a font to load.
+ */
 export class FontDescription {
     ptr;
+    /**
+     * Creates a new font description structure with all fields unset.
+     */
     constructor() {
         this.ptr = this.createPtr([]);
     }
@@ -12,6 +23,61 @@ export class FontDescription {
             innerType: "PangoFontDescription",
         });
     }
+    /**
+     * Creates a new font description from a string representation.
+     *
+     * The string must have the form
+     *
+     * [FAMILY-LIST] [STYLE-OPTIONS] [SIZE] [VARIATIONS] [FEATURES]
+     *
+     * where FAMILY-LIST is a comma-separated list of families optionally
+     * terminated by a comma, STYLE_OPTIONS is a whitespace-separated list
+     * of words where each word describes one of style, variant, weight,
+     * stretch, or gravity, and SIZE is a decimal number (size in points)
+     * or optionally followed by the unit modifier "px" for absolute size.
+     *
+     * The following words are understood as styles:
+     * "Normal", "Roman", "Oblique", "Italic".
+     *
+     * The following words are understood as variants:
+     * "Small-Caps", "All-Small-Caps", "Petite-Caps", "All-Petite-Caps",
+     * "Unicase", "Title-Caps".
+     *
+     * The following words are understood as weights:
+     * "Thin", "Ultra-Light", "Extra-Light", "Light", "Semi-Light",
+     * "Demi-Light", "Book", "Regular", "Medium", "Semi-Bold", "Demi-Bold",
+     * "Bold", "Ultra-Bold", "Extra-Bold", "Heavy", "Black", "Ultra-Black",
+     * "Extra-Black".
+     *
+     * The following words are understood as stretch values:
+     * "Ultra-Condensed", "Extra-Condensed", "Condensed", "Semi-Condensed",
+     * "Semi-Expanded", "Expanded", "Extra-Expanded", "Ultra-Expanded".
+     *
+     * The following words are understood as gravity values:
+     * "Not-Rotated", "South", "Upside-Down", "North", "Rotated-Left",
+     * "East", "Rotated-Right", "West".
+     *
+     * The following words are understood as color values:
+     * "With-Color", "Without-Color".
+     *
+     * VARIATIONS is a comma-separated list of font variations
+     * of the form @‍axis1=value,axis2=value,...
+     *
+     * FEATURES is a comma-separated list of font features of the form
+     * \#‍feature1=value,feature2=value,...
+     * The =value part can be ommitted if the value is 1.
+     *
+     * Any one of the options may be absent. If FAMILY-LIST is absent, then
+     * the family_name field of the resulting font description will be
+     * initialized to %NULL. If STYLE-OPTIONS is missing, then all style
+     * options will be set to the default values. If SIZE is missing, the
+     * size in the resulting font description will be set to 0.
+     *
+     * A typical example:
+     *
+     * Cantarell Italic Light 15 @‍wght=200 #‍tnum=1
+     * @param str - string representation of a font description.
+     */
     static fromString(str) {
         const ptr = call("libpango-1.0.so.0", "pango_font_description_from_string", [
             {
@@ -26,6 +92,21 @@ export class FontDescription {
         });
         return getObject(ptr, FontDescription);
     }
+    /**
+     * Determines if the style attributes of `new_match` are a closer match
+     * for `desc` than those of `old_match` are, or if `old_match` is %NULL,
+     * determines if `new_match` is a match at all.
+     *
+     * Approximate matching is done for weight and style; other style attributes
+     * must match exactly. Style attributes are all attributes other than family
+     * and size-related attributes. Approximate matching for style considers
+     * %PANGO_STYLE_OBLIQUE and %PANGO_STYLE_ITALIC as matches, but not as good
+     * a match as when the styles are equal.
+     *
+     * Note that `old_match` must match @desc.
+     * @param oldMatch - a `PangoFontDescription`, or %NULL
+     * @param newMatch - a `PangoFontDescription`
+     */
     betterMatch(newMatch, oldMatch) {
         return call("libpango-1.0.so.0", "pango_font_description_better_match", [
             {
@@ -53,6 +134,9 @@ export class FontDescription {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Make a copy of a `PangoFontDescription`.
+     */
     copy() {
         const ptr = call("libpango-1.0.so.0", "pango_font_description_copy", [
             {
@@ -69,6 +153,15 @@ export class FontDescription {
             return null;
         return getObject(ptr, FontDescription);
     }
+    /**
+     * Make a copy of a `PangoFontDescription`, but don't duplicate
+     * allocated fields.
+     *
+     * This is like [method@Pango.FontDescription.copy], but only a shallow
+     * copy is made of the family name and other allocated fields. The result
+     * can only be used until `desc` is modified or freed. This is meant
+     * to be used when the copy is only needed temporarily.
+     */
     copyStatic() {
         const ptr = call("libpango-1.0.so.0", "pango_font_description_copy_static", [
             {
@@ -85,6 +178,15 @@ export class FontDescription {
             return null;
         return getObject(ptr, FontDescription);
     }
+    /**
+     * Compares two font descriptions for equality.
+     *
+     * Two font descriptions are considered equal if the fonts they describe
+     * are provably identical. This means that their masks do not have to match,
+     * as long as other fields are all the same. (Two font descriptions may
+     * result in identical fonts being loaded, but still compare %FALSE.)
+     * @param desc2 - another `PangoFontDescription`
+     */
     equal(desc2) {
         return call("libpango-1.0.so.0", "pango_font_description_equal", [
             {
@@ -102,6 +204,9 @@ export class FontDescription {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Frees a font description.
+     */
     free() {
         call("libpango-1.0.so.0", "pango_font_description_free", [
             {
@@ -110,6 +215,12 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns the color field of the font description.
+     *
+     * This field determines whether the font description should
+     * match fonts that have color glyphs, or fonts that don't.
+     */
     getColor() {
         return call("libpango-1.0.so.0", "pango_font_description_get_color", [
             {
@@ -118,6 +229,11 @@ export class FontDescription {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the family name field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_family].
+     */
     getFamily() {
         return call("libpango-1.0.so.0", "pango_font_description_get_family", [
             {
@@ -126,6 +242,11 @@ export class FontDescription {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the features field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_features].
+     */
     getFeatures() {
         return call("libpango-1.0.so.0", "pango_font_description_get_features", [
             {
@@ -134,6 +255,11 @@ export class FontDescription {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the gravity field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_gravity].
+     */
     getGravity() {
         return call("libpango-1.0.so.0", "pango_font_description_get_gravity", [
             {
@@ -142,6 +268,9 @@ export class FontDescription {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Determines which fields in a font description have been set.
+     */
     getSetFields() {
         return call("libpango-1.0.so.0", "pango_font_description_get_set_fields", [
             {
@@ -150,6 +279,11 @@ export class FontDescription {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the size field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_size].
+     */
     getSize() {
         return call("libpango-1.0.so.0", "pango_font_description_get_size", [
             {
@@ -158,6 +292,13 @@ export class FontDescription {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Determines whether the size of the font is in points (not absolute)
+     * or device units (absolute).
+     *
+     * See [method@Pango.FontDescription.set_size]
+     * and [method@Pango.FontDescription.set_absolute_size].
+     */
     getSizeIsAbsolute() {
         return call("libpango-1.0.so.0", "pango_font_description_get_size_is_absolute", [
             {
@@ -166,6 +307,11 @@ export class FontDescription {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the stretch field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_stretch].
+     */
     getStretch() {
         return call("libpango-1.0.so.0", "pango_font_description_get_stretch", [
             {
@@ -174,6 +320,11 @@ export class FontDescription {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the style field of a `PangoFontDescription`.
+     *
+     * See [method@Pango.FontDescription.set_style].
+     */
     getStyle() {
         return call("libpango-1.0.so.0", "pango_font_description_get_style", [
             {
@@ -182,6 +333,11 @@ export class FontDescription {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the variant field of a `PangoFontDescription`.
+     *
+     * See [method@Pango.FontDescription.set_variant].
+     */
     getVariant() {
         return call("libpango-1.0.so.0", "pango_font_description_get_variant", [
             {
@@ -190,6 +346,11 @@ export class FontDescription {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the variations field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_variations].
+     */
     getVariations() {
         return call("libpango-1.0.so.0", "pango_font_description_get_variations", [
             {
@@ -198,6 +359,11 @@ export class FontDescription {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the weight field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_weight].
+     */
     getWeight() {
         return call("libpango-1.0.so.0", "pango_font_description_get_weight", [
             {
@@ -206,6 +372,12 @@ export class FontDescription {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Computes a hash of a `PangoFontDescription` structure.
+     *
+     * This is suitable to be used, for example, as an argument
+     * to g_hash_table_new(). The hash value is independent of @desc->mask.
+     */
     hash() {
         return call("libpango-1.0.so.0", "pango_font_description_hash", [
             {
@@ -214,6 +386,18 @@ export class FontDescription {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Merges the fields that are set in `desc_to_merge` into the fields in
+     * @desc.
+     *
+     * If `replace_existing` is %FALSE, only fields in `desc` that
+     * are not already set are affected. If %TRUE, then fields that are
+     * already set will be replaced as well.
+     *
+     * If `desc_to_merge` is %NULL, this function performs nothing.
+     * @param descToMerge - the `PangoFontDescription` to merge from,
+     * @param replaceExisting - if %TRUE, replace fields in `desc` with the
+     */
     merge(replaceExisting, descToMerge) {
         call("libpango-1.0.so.0", "pango_font_description_merge", [
             {
@@ -236,6 +420,17 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Merges the fields that are set in `desc_to_merge` into the fields in
+     * @desc, without copying allocated fields.
+     *
+     * This is like [method@Pango.FontDescription.merge], but only a shallow copy
+     * is made of the family name and other allocated fields. `desc` can only
+     * be used until `desc_to_merge` is modified or freed. This is meant to
+     * be used when the merged font description is only needed temporarily.
+     * @param descToMerge - the `PangoFontDescription` to merge from
+     * @param replaceExisting - if %TRUE, replace fields in `desc` with the
+     */
     mergeStatic(descToMerge, replaceExisting) {
         call("libpango-1.0.so.0", "pango_font_description_merge_static", [
             {
@@ -257,6 +452,13 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the size field of a font description, in device units.
+     *
+     * This is mutually exclusive with [method@Pango.FontDescription.set_size]
+     * which sets the font size in points.
+     * @param size - the new size, in Pango units. There are %PANGO_SCALE Pango units
+     */
     setAbsoluteSize(size) {
         call("libpango-1.0.so.0", "pango_font_description_set_absolute_size", [
             {
@@ -269,6 +471,13 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the color field of a font description.
+     *
+     * This field determines whether the font description should
+     * match fonts that have color glyphs, or fonts that don't.
+     * @param color - the `PangoFontColor` value
+     */
     setColor(color) {
         call("libpango-1.0.so.0", "pango_font_description_set_color", [
             {
@@ -281,6 +490,16 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the family name field of a font description.
+     *
+     * The family
+     * name represents a family of related font styles, and will
+     * resolve to a particular `PangoFontFamily`. In some uses of
+     * `PangoFontDescription`, it is also possible to use a comma
+     * separated list of family names for this field.
+     * @param family - a string representing the family name.
+     */
     setFamily(family) {
         call("libpango-1.0.so.0", "pango_font_description_set_family", [
             {
@@ -293,6 +512,16 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the family name field of a font description, without copying the string.
+     *
+     * This is like [method@Pango.FontDescription.set_family], except that no
+     * copy of `family` is made. The caller must make sure that the
+     * string passed in stays around until `desc` has been freed or the
+     * name is set again. This function can be used if `family` is a static
+     * string such as a C string literal, or if `desc` is only needed temporarily.
+     * @param family - a string representing the family name
+     */
     setFamilyStatic(family) {
         call("libpango-1.0.so.0", "pango_font_description_set_family_static", [
             {
@@ -305,6 +534,33 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the features field of a font description.
+     *
+     * OpenType font features allow to enable or disable certain optional
+     * features of a font, such as tabular numbers.
+     *
+     * The format of the features string is comma-separated list of
+     * feature assignments, with each assignment being one of these forms:
+     *
+     * FEATURE=n
+     *
+     * where FEATURE must be a 4 character tag that identifies and OpenType
+     * feature, and n an integer (depending on the feature, the allowed
+     * values may be 0, 1 or bigger numbers). Unknown features are ignored.
+     *
+     * Note that font features set in this way are enabled for the entire text
+     * that is using the font, which is not appropriate for all OpenType features.
+     * The intended use case is to select character variations (features cv01 - c99),
+     * style sets (ss01 - ss20) and the like.
+     *
+     * Pango does not currently have a way to find supported OpenType features
+     * of a font. Both harfbuzz and freetype have API for this. See for example
+     * hb_ot_layout_table_get_feature_tags.
+     *
+     * Features that are not supported by the font are silently ignored.
+     * @param features - a string representing the features
+     */
     setFeatures(features) {
         call("libpango-1.0.so.0", "pango_font_description_set_features", [
             {
@@ -318,6 +574,17 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the features field of a font description.
+     *
+     * This is like [method@Pango.FontDescription.set_features], except
+     * that no copy of `featuresis` made. The caller must make sure that
+     * the string passed in stays around until `desc` has been freed
+     * or the name is set again. This function can be used if
+     * `features` is a static string such as a C string literal,
+     * or if `desc` is only needed temporarily.
+     * @param features - a string representing the features
+     */
     setFeaturesStatic(features) {
         call("libpango-1.0.so.0", "pango_font_description_set_features_static", [
             {
@@ -330,6 +597,18 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the gravity field of a font description.
+     *
+     * The gravity field
+     * specifies how the glyphs should be rotated. If `gravity` is
+     * %PANGO_GRAVITY_AUTO, this actually unsets the gravity mask on
+     * the font description.
+     *
+     * This function is seldom useful to the user. Gravity should normally
+     * be set on a `PangoContext`.
+     * @param gravity - the gravity for the font description.
+     */
     setGravity(gravity) {
         call("libpango-1.0.so.0", "pango_font_description_set_gravity", [
             {
@@ -342,6 +621,13 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the size field of a font description in fractional points.
+     *
+     * This is mutually exclusive with
+     * [method@Pango.FontDescription.set_absolute_size].
+     * @param size - the size of the font in points, scaled by %PANGO_SCALE.
+     */
     setSize(size) {
         call("libpango-1.0.so.0", "pango_font_description_set_size", [
             {
@@ -354,6 +640,13 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the stretch field of a font description.
+     *
+     * The [enum@Pango.Stretch] field specifies how narrow or
+     * wide the font should be.
+     * @param stretch - the stretch for the font description
+     */
     setStretch(stretch) {
         call("libpango-1.0.so.0", "pango_font_description_set_stretch", [
             {
@@ -366,6 +659,19 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the style field of a `PangoFontDescription`.
+     *
+     * The [enum@Pango.Style] enumeration describes whether the font is
+     * slanted and the manner in which it is slanted; it can be either
+     * %PANGO_STYLE_NORMAL, %PANGO_STYLE_ITALIC, or %PANGO_STYLE_OBLIQUE.
+     *
+     * Most fonts will either have a italic style or an oblique style,
+     * but not both, and font matching in Pango will match italic
+     * specifications with oblique fonts and vice-versa if an exact
+     * match is not found.
+     * @param style - the style for the font description
+     */
     setStyle(style) {
         call("libpango-1.0.so.0", "pango_font_description_set_style", [
             {
@@ -378,6 +684,13 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the variant field of a font description.
+     *
+     * The [enum@Pango.Variant] can either be %PANGO_VARIANT_NORMAL
+     * or %PANGO_VARIANT_SMALL_CAPS.
+     * @param variant - the variant type for the font description.
+     */
     setVariant(variant) {
         call("libpango-1.0.so.0", "pango_font_description_set_variant", [
             {
@@ -390,6 +703,25 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the variations field of a font description.
+     *
+     * OpenType font variations allow to select a font instance by
+     * specifying values for a number of axes, such as width or weight.
+     *
+     * The format of the variations string is
+     *
+     * AXIS1=VALUE,AXIS2=VALUE...
+     *
+     * with each AXIS a 4 character tag that identifies a font axis,
+     * and each VALUE a floating point number. Unknown axes are ignored,
+     * and values are clamped to their allowed range.
+     *
+     * Pango does not currently have a way to find supported axes of
+     * a font. Both harfbuzz and freetype have API for this. See
+     * for example hb_ot_var_get_axis_infos.
+     * @param variations - a string representing the variations
+     */
     setVariations(variations) {
         call("libpango-1.0.so.0", "pango_font_description_set_variations", [
             {
@@ -403,6 +735,17 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the variations field of a font description.
+     *
+     * This is like [method@Pango.FontDescription.set_variations], except
+     * that no copy of `variations` is made. The caller must make sure that
+     * the string passed in stays around until `desc` has been freed
+     * or the name is set again. This function can be used if
+     * `variations` is a static string such as a C string literal,
+     * or if `desc` is only needed temporarily.
+     * @param variations - a string representing the variations
+     */
     setVariationsStatic(variations) {
         call("libpango-1.0.so.0", "pango_font_description_set_variations_static", [
             {
@@ -415,6 +758,15 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the weight field of a font description.
+     *
+     * The weight field
+     * specifies how bold or light the font should be. In addition
+     * to the values of the [enum@Pango.Weight] enumeration, other
+     * intermediate numeric values are possible.
+     * @param weight - the weight for the font description.
+     */
     setWeight(weight) {
         call("libpango-1.0.so.0", "pango_font_description_set_weight", [
             {
@@ -427,6 +779,14 @@ export class FontDescription {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Creates a filename representation of a font description.
+     *
+     * The filename is identical to the result from calling
+     * [method@Pango.FontDescription.to_string], but with underscores
+     * instead of characters that are untypical in filenames, and in
+     * lower case only.
+     */
     toFilename() {
         return call("libpango-1.0.so.0", "pango_font_description_to_filename", [
             {
@@ -435,6 +795,14 @@ export class FontDescription {
             },
         ], { type: "string" });
     }
+    /**
+     * Creates a string representation of a font description.
+     *
+     * See [func@Pango.FontDescription.from_string] for a description
+     * of the format of the string representation. The family list in
+     * the string description will only have a terminating comma if
+     * the last word of the list is a valid style option.
+     */
     toString() {
         return call("libpango-1.0.so.0", "pango_font_description_to_string", [
             {
@@ -443,6 +811,12 @@ export class FontDescription {
             },
         ], { type: "string" });
     }
+    /**
+     * Unsets some of the fields in a `PangoFontDescription`.
+     *
+     * The unset fields will get back to their default values.
+     * @param toUnset - bitmask of fields in the `desc` to unset.
+     */
     unsetFields(toUnset) {
         call("libpango-1.0.so.0", "pango_font_description_unset_fields", [
             {

package/dist/generated/pango/font-face.d.ts

@@ -2,13 +2,51 @@ import { Ref } from "@gtkx/native";
 import { FontDescription } from "./font-description.js";
 import { FontFamily } from "./font-family.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * A `PangoFontFace` is used to represent a group of fonts with
+ * the same family, slant, weight, and width, but varying sizes.
+ */
 export declare class FontFace extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Returns a font description that matches the face.
+     *
+     * The resulting font description will have the family, style,
+     * variant, weight and stretch of the face, but its size field
+     * will be unset.
+     */
     describe(): FontDescription;
+    /**
+     * Gets a name representing the style of this face.
+     *
+     * Note that a font family may contain multiple faces
+     * with the same name (e.g. a variable and a non-variable
+     * face for the same style).
+     */
     getFaceName(): string;
+    /**
+     * Gets the `PangoFontFamily` that `face` belongs to.
+     */
     getFamily(): FontFamily;
+    /**
+     * Returns whether a `PangoFontFace` is synthesized.
+     *
+     * This will be the case if the underlying font rendering engine
+     * creates this face from another face, by shearing, emboldening,
+     * lightening or modifying it in some other way.
+     */
     isSynthesized(): boolean;
+    /**
+     * List the available sizes for a font.
+     *
+     * This is only applicable to bitmap fonts. For scalable fonts, stores
+     * %NULL at the location pointed to by `sizes` and 0 at the location pointed
+     * to by @n_sizes. The sizes returned are in Pango units and are sorted
+     * in ascending order.
+     * @param sizes - location to store a pointer to an array of int. This array
+     * @param nSizes - location to store the number of elements in @sizes
+     */
     listSizes(nSizes: Ref<number>, sizes?: Ref<number[]> | null): void;
     connect(signal: "notify", handler: (self: FontFace, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;