@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -1,44 +1,418 @@
 import { FontColor, FontMask, Gravity, Stretch, Style, Variant, Weight } from "./enums.js";
+/**
+ * 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 declare class FontDescription {
     ptr: unknown;
+    /**
+     * Creates a new font description structure with all fields unset.
+     */
     constructor();
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * 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: string): 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: FontDescription, oldMatch?: FontDescription | null): boolean;
+    /**
+     * Make a copy of a `PangoFontDescription`.
+     */
     copy(): FontDescription | null;
+    /**
+     * 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(): FontDescription | null;
+    /**
+     * 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: FontDescription): boolean;
+    /**
+     * Frees a font description.
+     */
     free(): void;
+    /**
+     * 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(): FontColor;
+    /**
+     * Gets the family name field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_family].
+     */
     getFamily(): string | null;
+    /**
+     * Gets the features field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_features].
+     */
     getFeatures(): string | null;
+    /**
+     * Gets the gravity field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_gravity].
+     */
     getGravity(): Gravity;
+    /**
+     * Determines which fields in a font description have been set.
+     */
     getSetFields(): FontMask;
+    /**
+     * Gets the size field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_size].
+     */
     getSize(): number;
+    /**
+     * 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(): boolean;
+    /**
+     * Gets the stretch field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_stretch].
+     */
     getStretch(): Stretch;
+    /**
+     * Gets the style field of a `PangoFontDescription`.
+     *
+     * See [method@Pango.FontDescription.set_style].
+     */
     getStyle(): Style;
+    /**
+     * Gets the variant field of a `PangoFontDescription`.
+     *
+     * See [method@Pango.FontDescription.set_variant].
+     */
     getVariant(): Variant;
+    /**
+     * Gets the variations field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_variations].
+     */
     getVariations(): string | null;
+    /**
+     * Gets the weight field of a font description.
+     *
+     * See [method@Pango.FontDescription.set_weight].
+     */
     getWeight(): Weight;
+    /**
+     * 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(): number;
+    /**
+     * 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: boolean, descToMerge?: FontDescription | null): void;
+    /**
+     * 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: FontDescription, replaceExisting: boolean): void;
+    /**
+     * 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: number): void;
+    /**
+     * 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: FontColor): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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?: string | null): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: Gravity): void;
+    /**
+     * 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: number): void;
+    /**
+     * 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: Stretch): void;
+    /**
+     * 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: Style): void;
+    /**
+     * 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: Variant): void;
+    /**
+     * 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?: string | null): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: Weight): void;
+    /**
+     * 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(): string | null;
+    /**
+     * 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(): 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: FontMask): void;
 }