Module org.freedesktop.cairo

Package org.freedesktop.cairo

Class ScaledFont

java.lang.Object

io.github.jwharm.cairobindings.Proxy

org.freedesktop.cairo.ScaledFont

Direct Known Subclasses:

FTScaledFont, UserScaledFont

public class ScaledFont
extends Proxy

Font face at particular size and options.

A ScaledFont is a font scaled to a particular size and device resolution. A ScaledFont is most useful for low-level font usage where a library or application wants to cache a reference to a scaled font to speed up the computation of metrics.

There are various types of scaled fonts, depending on the font backend they use. The type of a scaled font can be queried using getFontType().

Since:

1.0

See Also:

• FontFace
• Matrix
• FontOptions

Constructor Summary

Constructors

Constructor	Description
ScaledFont(MemorySegment address)	Constructor used internally to instantiate a java ScaledFont object for a native cairo_scaled_font_t instance

Method Summary

Modifier and Type	Method	Description
static ScaledFont	create(FontFace fontFace, Matrix fontMatrix, Matrix ctm, FontOptions options)	Creates a ScaledFont object from a font face and matrices that describe the size of the font and the environment in which it will be used.
void	destroy()	Invokes the cleanup action that is normally invoked during garbage collection.
void	extents(FontExtents extents)	Gets the metrics for a ScaledFont.
void	getCTM(Matrix ctm)	Returns the CTM with which the ScaledFont was created.
FontFace	getFontFace()	Gets the font face that this scaled font uses.
void	getFontMatrix(Matrix fontMatrix)	Stores the font matrix with which the ScaledFont was created into fontMatrix.
void	getFontOptions(FontOptions options)	Stores the font options with which the ScaledFont was created into options.
FontType	getFontType()	This function returns the type of the backend used to create a scaled font.
void	getScaleMatrix(Matrix scaleMatrix)	Returns the scale matrix of the ScaledFont.
static org.gnome.glib.Type	getType()	Get the CairoScaledFont GType
MemorySegment	getUserData(UserDataKey key)	Return user data previously attached to the scaled font using the specified key.
void	glyphExtents(Glyphs glyphs, TextExtents extents)	Gets the extents for an array of glyphs.
UserDataKey	setUserData(UserDataKey key, MemorySegment userData)	Attach user data to the scaled font.
Status	status()	Checks whether an error has previously occurred for this scaled_font.
void	textExtents(String string, TextExtents extents)	Gets the extents for a string of text.
Glyphs	textToGlyphs(double x, double y, String string)	Converts UTF-8 text to an array of glyphs, optionally with cluster mapping, that can be used to render later using the ScaledFont.

Methods inherited from class io.github.jwharm.cairobindings.Proxy

equals, handle, hashCode

Methods inherited from class java.lang.Object

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

Constructor Details

ScaledFont

public ScaledFont(MemorySegment address)

Constructor used internally to instantiate a java ScaledFont object for a native cairo_scaled_font_t instance

Parameters:

address - the memory address of the native cairo_scaled_font_t instance

Method Details

destroy

public void destroy()

Invokes the cleanup action that is normally invoked during garbage collection. If the instance is "owned" by the user, the destroy() function is run to dispose the native instance.

create

public static ScaledFont create(FontFace fontFace,
 Matrix fontMatrix,
 Matrix ctm,
 FontOptions options)

Creates a ScaledFont object from a font face and matrices that describe the size of the font and the environment in which it will be used.

Parameters:

fontFace - a FontFace

fontMatrix - font space to user space transformation matrix for the font. In the simplest case of a N point font, this matrix is just a scale by N, but it can also be used to shear the font or stretch it unequally along the two axes. See Context.setFontMatrix(Matrix).

ctm - user to device transformation matrix with which the font will be used.

options - options to use when getting metrics for the font and rendering with it.

Returns:

a newly created ScaledFont

Since:

1.0

status

public Status status()

Checks whether an error has previously occurred for this scaled_font.

Returns:

Status.SUCCESS or another error such as Status.NO_MEMORY.

Since:

1.0

extents

public void extents(FontExtents extents)

Gets the metrics for a ScaledFont.

Parameters:

extents - a FontExtents in which to store the retrieved extents

Since:

1.0

textExtents

public void textExtents(String string,
 TextExtents extents)

Gets the extents for a string of text. The extents describe a user-space rectangle that encloses the "inked" portion of the text drawn at the origin (0,0) (as it would be drawn by Context.showText(String) if the cairo graphics state were set to the same FontFace, font Matrix, CTM, and FontOptions as this ScaledFont). Additionally, the xAdvance() and yAdvance() values indicate the amount by which the current point would be advanced by Context.showText(String).

Note that whitespace characters do not directly contribute to the size of the rectangle (extents.width() and extents.height()). They do contribute indirectly by changing the position of non-whitespace characters. In particular, trailing whitespace characters are likely to not affect the size of the rectangle, though they will affect the xAdvance() and yAdvance() values.

Parameters:

string - a string of text

extents - a TextExtents in which to store the retrieved extents.

Since:

1.2

glyphExtents

public void glyphExtents(Glyphs glyphs,
 TextExtents extents)

Gets the extents for an array of glyphs. The extents describe a user-space rectangle that encloses the "inked" portion of the glyphs, (as they would be drawn by cairo_show_glyphs() if the cairo graphics state were set to the same FontFace, font Matrix, CTM, and FontOptions as this ScaledFont). Additionally, the xAdvance() and yAdvance() values indicate the amount by which the current point would be advanced by Context.showGlyphs(org.freedesktop.cairo.Glyphs).

Note that whitespace glyphs do not contribute to the size of the rectangle (extents.width() and extents.height()).

Parameters:

glyphs - an array of glyph IDs with X and Y offsets.

extents - a TextExtents in which to store the retrieved extents.

Since:

1.0

textToGlyphs

public Glyphs textToGlyphs(double x,
 double y,
 String string)
                    throws IllegalStateException

Converts UTF-8 text to an array of glyphs, optionally with cluster mapping, that can be used to render later using the ScaledFont.

The glyphs and clusters parameters must be modifiable lists. Upon completion of the function call, the glyphs and cluster mappings will have been added to these lists. The glyphs list cannot be null, but clusters is optional and can be null when cluster mapping does not need to be computed.

In the simplest case, clusters can point to NULL because no cluster mapping is needed. In code:

 List<Glyph> glyphs = new ArrayList<>();
 scaledFont.textToGlyphs(x, y, string, glyphs, null);
 

If cluster mapping is to be computed:

 List<Glyph> glyphs = new ArrayList<>();
 List<TextCluster> clusters = new ArrayList<>();
 var clusterFlags = scaledFont.textToGlyphs(x, y, string, glyphs, clusters);
 

For details of how TextClusters and TextClusterFlags map input UTF-8 text to the output glyphs see Context.showTextGlyphs(String, Glyphs).

The output values can be converted to arrays and then readily passed to Context.showTextGlyphs(String, Glyphs), Context.showGlyphs(org.freedesktop.cairo.Glyphs), or related functions, assuming that the exact same ScaledFont is used for the operation.

Parameters:

x - X position to place first glyph

y - Y position to place first glyph

string - a string of text

Returns:

the glyphs array

Throws:

IllegalStateException - if the input values are wrong or if conversion failed

Since:

1.8

getFontFace

public FontFace getFontFace()

Gets the font face that this scaled font uses. This might be the font face passed to create(FontFace, Matrix, Matrix, FontOptions), but this does not hold true for all possible cases.

Returns:

The FontFace with which the ScaledFont was created.

getFontOptions

public void getFontOptions(FontOptions options)

Stores the font options with which the ScaledFont was created into options.

Parameters:

options - return value for the font options

Since:

1.2

getFontMatrix

public void getFontMatrix(Matrix fontMatrix)

Stores the font matrix with which the ScaledFont was created into fontMatrix.

Parameters:

fontMatrix - return value for the matrix

Since:

1.2

getCTM

public void getCTM(Matrix ctm)

Returns the CTM with which the ScaledFont was created. Note that the translation offsets (x0, y0) of the CTM are ignored by create(FontFace, Matrix, Matrix, FontOptions). So, the matrix this function returns always has 0,0 as x0,y0.

Parameters:

ctm - return value for the CTM

Since:

1.2

getScaleMatrix

public void getScaleMatrix(Matrix scaleMatrix)

Returns the scale matrix of the ScaledFont. The scale matrix is product of the font matrix and the ctm associated with the scaled font, and hence is the matrix mapping from font space to device space.

Parameters:

scaleMatrix - return value for the matrix

Since:

1.8

getFontType

public FontType getFontType()

This function returns the type of the backend used to create a scaled font. See FontType for available types. However, this function never returns FontType.TOY.

Returns:

the type of the ScaledFont.

Since:

1.2

setUserData

public UserDataKey setUserData(UserDataKey key,
 MemorySegment userData)

Attach user data to the scaled font. To remove user data from a scaled font, call this function with the key that was used to set it and null for userData.

Parameters:

key - the key to attach the user data to

userData - the user data to attach to the scaled font

Returns:

the key

Throws:

NullPointerException - if key is null

Since:

1.4

getUserData

public MemorySegment getUserData(UserDataKey key)

Return user data previously attached to the scaled font using the specified key. If no user data has been attached with the given key this function returns null.

The returned memory segment has zero length. It can be resized with MemorySegment.reinterpret(long)^RESTRICTED.

Parameters:

key - the UserDataKey the user data was attached to

Returns:

the user data previously attached or null

Since:

1.4

getType

public static org.gnome.glib.Type getType()

Get the CairoScaledFont GType

Returns:

the GType