Class FontDescription

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.pango.FontDescription
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class FontDescription extends ProxyInstance

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.

  • Constructor Details

    • FontDescription

      public FontDescription(MemorySegment address)
      Create a FontDescription proxy instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • FontDescription

      public FontDescription()
      Creates a new font description structure with all fields unset.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the FontDescription class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • fromString

      public static FontDescription fromString(String str)

      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
      Parameters:
      str - string representation of a font description.
      Returns:
      a new PangoFontDescription.

    • betterMatch

      public boolean betterMatch(@Nullable FontDescription oldMatch, FontDescription newMatch)

      Determines if the style attributes of newMatch are a closer match for this FontDescription than those of oldMatch are, or if oldMatch is null, determines if newMatch 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 Style.OBLIQUE and Style.ITALIC as matches, but not as good a match as when the styles are equal.

      Note that oldMatch must match desc.

      Parameters:
      oldMatch - a PangoFontDescription, or null
      newMatch - a PangoFontDescription
      Returns:
      true if newMatch is a better match

    • copy

      public @Nullable FontDescription copy()
      Make a copy of a PangoFontDescription.
      Returns:
      the newly allocated PangoFontDescription, which should be freed with free(), or null if this FontDescription was null.

    • copyStatic

      public @Nullable FontDescription copyStatic()

      Make a copy of a PangoFontDescription, but don't duplicate allocated fields.

      This is like copy(), but only a shallow copy is made of the family name and other allocated fields. The result can only be used until this FontDescription is modified or freed. This is meant to be used when the copy is only needed temporarily.

      Returns:
      the newly allocated PangoFontDescription, which should be freed with free(), or null if this FontDescription was null.

    • equal

      public boolean equal(FontDescription desc2)

      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.)

      Parameters:
      desc2 - another PangoFontDescription
      Returns:
      true if the two font descriptions are identical, false otherwise.

    • free

      public void free()
      Frees a font description.

    • getColor

      public FontColor getColor()

      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.

      Since:
      1.57

    • getFamily

      public @Nullable String getFamily()

      Gets the family name field of a font description.

      See setFamily(String).

      Returns:
      the family name field for the font description, or null if not previously set. This has the same life-time as the font description itself and should not be freed.

    • getFeatures

      public @Nullable String getFeatures()

      Gets the features field of a font description.

      See setFeatures(String).

      Returns:
      the features field for the font description, or null if not previously set. This has the same life-time as the font description itself and should not be freed.
      Since:
      1.56

    • getGravity

      public Gravity getGravity()

      Gets the gravity field of a font description.

      See setGravity(Gravity).

      Returns:
      the gravity field for the font description. Use getSetFields() to find out if the field was explicitly set or not.
      Since:
      1.16

    • getSetFields

      public Set<FontMask> getSetFields()
      Determines which fields in a font description have been set.
      Returns:
      a bitmask with bits set corresponding to the fields in this FontDescription that have been set.

    • getSize

      public int getSize()

      Gets the size field of a font description.

      See setSize(int).

      Returns:
      the size field for the font description in points or device units. You must call getSizeIsAbsolute() to find out which is the case. Returns 0 if the size field has not previously been set or it has been set to 0 explicitly. Use getSetFields() to find out if the field was explicitly set or not.

    • getSizeIsAbsolute

      public boolean getSizeIsAbsolute()

      Determines whether the size of the font is in points (not absolute) or device units (absolute).

      See setSize(int) and setAbsoluteSize(double).

      Returns:
      whether the size for the font description is in points or device units. Use getSetFields() to find out if the size field of the font description was explicitly set or not.
      Since:
      1.8

    • getStretch

      public Stretch getStretch()

      Gets the stretch field of a font description.

      See setStretch(Stretch).

      Returns:
      the stretch field for the font description. Use getSetFields() to find out if the field was explicitly set or not.

    • getStyle

      public Style getStyle()

      Gets the style field of a PangoFontDescription.

      See setStyle(Style).

      Returns:
      the style field for the font description. Use getSetFields() to find out if the field was explicitly set or not.

    • getVariant

      public Variant getVariant()

      Gets the variant field of a PangoFontDescription.

      See setVariant(Variant).

      Returns:
      the variant field for the font description. Use getSetFields() to find out if the field was explicitly set or not.

    • getVariations

      public @Nullable String getVariations()

      Gets the variations field of a font description.

      See setVariations(String).

      Returns:
      the variations field for the font description, or null if not previously set. This has the same life-time as the font description itself and should not be freed.
      Since:
      1.42

    • getWeight

      public Weight getWeight()

      Gets the weight field of a font description.

      See setWeight(Weight).

      Returns:
      the weight field for the font description. Use getSetFields() to find out if the field was explicitly set or not.

    • hash

      public int hash()

      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.

      Returns:
      the hash value.

    • merge

      public void merge(@Nullable FontDescription descToMerge, boolean replaceExisting)

      Merges the fields that are set in descToMerge into the fields in desc.

      If replaceExisting is false, only fields in this FontDescription that are not already set are affected. If true, then fields that are already set will be replaced as well.

      If descToMerge is null, this function performs nothing.

      Parameters:
      descToMerge - the PangoFontDescription to merge from, or null
      replaceExisting - if true, replace fields in this FontDescription with the corresponding values from descToMerge, even if they are already exist.

    • mergeStatic

      public void mergeStatic(FontDescription descToMerge, boolean replaceExisting)

      Merges the fields that are set in descToMerge into the fields in desc, without copying allocated fields.

      This is like merge(FontDescription, boolean), but only a shallow copy is made of the family name and other allocated fields. this FontDescription can only be used until descToMerge is modified or freed. This is meant to be used when the merged font description is only needed temporarily.

      Parameters:
      descToMerge - the PangoFontDescription to merge from
      replaceExisting - if true, replace fields in this FontDescription with the corresponding values from descToMerge, even if they are already exist.

    • setAbsoluteSize

      public void setAbsoluteSize(double size)

      Sets the size field of a font description, in device units.

      This is mutually exclusive with setSize(int) which sets the font size in points.

      Parameters:
      size - the new size, in Pango units. There are PANGO_SCALE Pango units in one device unit. For an output backend where a device unit is a pixel, a size value of 10 * PANGO_SCALE gives a 10 pixel font.
      Since:
      1.8

    • setColor

      public void setColor(FontColor color)

      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.

      Parameters:
      color - the PangoFontColor value
      Since:
      1.57

    • setFamily

      public void setFamily(String family)

      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.

      Parameters:
      family - a string representing the family name.

    • setFamilyStatic

      public void setFamilyStatic(String family)

      Sets the family name field of a font description, without copying the string.

      This is like setFamily(String), except that no copy of family is made. The caller must make sure that the string passed in stays around until this FontDescription 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 this FontDescription is only needed temporarily.

      Parameters:
      family - a string representing the family name

    • setFeatures

      public void setFeatures(@Nullable String features)

      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.

      Parameters:
      features - a string representing the features
      Since:
      1.56

    • setFeaturesStatic

      public void setFeaturesStatic(String features)

      Sets the features field of a font description.

      This is like setFeatures(String), except that no copy of featuresis made. The caller must make sure that the string passed in stays around until this FontDescription 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 this FontDescription is only needed temporarily.

      Parameters:
      features - a string representing the features
      Since:
      1.56

    • setGravity

      public void setGravity(Gravity gravity)

      Sets the gravity field of a font description.

      The gravity field specifies how the glyphs should be rotated. If gravity is 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.

      Parameters:
      gravity - the gravity for the font description.
      Since:
      1.16

    • setSize

      public void setSize(int size)

      Sets the size field of a font description in fractional points.

      This is mutually exclusive with setAbsoluteSize(double).

      Parameters:
      size - the size of the font in points, scaled by PANGO_SCALE. (That is, a size value of 10 * PANGO_SCALE is a 10 point font. The conversion factor between points and device units depends on system configuration and the output device. For screen display, a logical DPI of 96 is common, in which case a 10 point font corresponds to a 10 * (96 / 72) = 13.3 pixel font. Use setAbsoluteSize(double) if you need a particular size in device units.

    • setStretch

      public void setStretch(Stretch stretch)

      Sets the stretch field of a font description.

      The Pango.Stretch field specifies how narrow or wide the font should be.

      Parameters:
      stretch - the stretch for the font description

    • setStyle

      public void setStyle(Style style)

      Sets the style field of a PangoFontDescription.

      The Pango.Style enumeration describes whether the font is slanted and the manner in which it is slanted; it can be either Style.NORMAL, Style.ITALIC, or 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.

      Parameters:
      style - the style for the font description

    • setVariant

      public void setVariant(Variant variant)

      Sets the variant field of a font description.

      The Pango.Variant can either be Variant.NORMAL or Variant.SMALL_CAPS.

      Parameters:
      variant - the variant type for the font description.

    • setVariations

      public void setVariations(@Nullable String variations)

      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.

      Parameters:
      variations - a string representing the variations
      Since:
      1.42

    • setVariationsStatic

      public void setVariationsStatic(String variations)

      Sets the variations field of a font description.

      This is like setVariations(String), except that no copy of variations is made. The caller must make sure that the string passed in stays around until this FontDescription 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 this FontDescription is only needed temporarily.

      Parameters:
      variations - a string representing the variations
      Since:
      1.42

    • setWeight

      public void setWeight(Weight weight)

      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 Pango.Weight enumeration, other intermediate numeric values are possible.

      Parameters:
      weight - the weight for the font description.

    • toFilename

      public @Nullable String toFilename()

      Creates a filename representation of a font description.

      The filename is identical to the result from calling toString(), but with underscores instead of characters that are untypical in filenames, and in lower case only.

      Returns:
      a new string that must be freed with g_free().

    • toString

      public String toString()

      Creates a string representation of a font description.

      See fromString(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.

      Overrides:
      toString in class Object
      Returns:
      a new string that must be freed with g_free().

    • unsetFields

      public void unsetFields(Set<FontMask> toUnset)

      Unsets some of the fields in a PangoFontDescription.

      The unset fields will get back to their default values.

      Parameters:
      toUnset - bitmask of fields in the this FontDescription to unset.

    • unsetFields

      public void unsetFields(FontMask... toUnset)

      Unsets some of the fields in a PangoFontDescription.

      The unset fields will get back to their default values.

      Parameters:
      toUnset - bitmask of fields in the this FontDescription to unset.