Package org.gnome.pango

Class FontDescription

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.pango.FontDescription

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.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 Summary

Constructors

Constructor	Description
FontDescription()	Creates a new font description structure with all fields unset.
FontDescription(MemorySegment address)	Create a FontDescription proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
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.
@Nullable FontDescription	copy()	Make a copy of a PangoFontDescription.
@Nullable FontDescription	copyStatic()	Make a copy of a PangoFontDescription, but don't duplicate allocated fields.
boolean	equal(FontDescription desc2)	Compares two font descriptions for equality.
void	free()	Frees a font description.
static FontDescription	fromString(String str)	Creates a new font description from a string representation.
FontColor	getColor()	Returns the color field of the font description.
@Nullable String	getFamily()	Gets the family name field of a font description.
@Nullable String	getFeatures()	Gets the features field of a font description.
Gravity	getGravity()	Gets the gravity field of a font description.
Set<FontMask>	getSetFields()	Determines which fields in a font description have been set.
int	getSize()	Gets the size field of a font description.
boolean	getSizeIsAbsolute()	Determines whether the size of the font is in points (not absolute) or device units (absolute).
Stretch	getStretch()	Gets the stretch field of a font description.
Style	getStyle()	Gets the style field of a PangoFontDescription.
static @Nullable Type	getType()	Get the GType of the FontDescription class
Variant	getVariant()	Gets the variant field of a PangoFontDescription.
@Nullable String	getVariations()	Gets the variations field of a font description.
Weight	getWeight()	Gets the weight field of a font description.
int	hash()	Computes a hash of a PangoFontDescription structure.
void	merge(@Nullable FontDescription descToMerge, boolean replaceExisting)	Merges the fields that are set in descToMerge into the fields in desc.
void	mergeStatic(FontDescription descToMerge, boolean replaceExisting)	Merges the fields that are set in descToMerge into the fields in desc, without copying allocated fields.
void	setAbsoluteSize(double size)	Sets the size field of a font description, in device units.
void	setColor(FontColor color)	Sets the color field of a font description.
void	setFamily(String family)	Sets the family name field of a font description.
void	setFamilyStatic(String family)	Sets the family name field of a font description, without copying the string.
void	setFeatures(@Nullable String features)	Sets the features field of a font description.
void	setFeaturesStatic(String features)	Sets the features field of a font description.
void	setGravity(Gravity gravity)	Sets the gravity field of a font description.
void	setSize(int size)	Sets the size field of a font description in fractional points.
void	setStretch(Stretch stretch)	Sets the stretch field of a font description.
void	setStyle(Style style)	Sets the style field of a PangoFontDescription.
void	setVariant(Variant variant)	Sets the variant field of a font description.
void	setVariations(@Nullable String variations)	Sets the variations field of a font description.
void	setVariationsStatic(String variations)	Sets the variations field of a font description.
void	setWeight(Weight weight)	Sets the weight field of a font description.
@Nullable String	toFilename()	Creates a filename representation of a font description.
String	toString()	Creates a string representation of a font description.
void	unsetFields(Set<FontMask> toUnset)	Unsets some of the fields in a PangoFontDescription.
void	unsetFields(FontMask... toUnset)	Unsets some of the fields in a PangoFontDescription.

Methods inherited from class org.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

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

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(java.lang.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(java.lang.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(org.gnome.pango.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(org.gnome.pango.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(org.gnome.pango.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(org.gnome.pango.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(java.lang.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(org.gnome.pango.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(org.gnome.pango.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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.