Module org.freedesktop.cairo

Package org.freedesktop.cairo

Class FontOptions

java.lang.Object

io.github.jwharm.cairobindings.Proxy

org.freedesktop.cairo.FontOptions

public class FontOptions
extends Proxy

How a font should be rendered.

The font options specify how fonts should be rendered. Most of the time the font options implied by a surface are just right and do not need any changes, but for pixel-based targets tweaking font options may result in superior output on a particular display.

Individual features of a cairo_font_options_t can be set or accessed using functions named FontOptions.setFeatureName() and FontOptions.getFeatureName(), like setAntialias(Antialias) and getAntialias().

New features may be added to FontOptions in the future. For this reason, copy(), equals(Object), merge(FontOptions) and hashCode() should be used to copy, check for equality, merge, or compute a hash value of FontOptions objects.

Since:

1.0

See Also:

• ScaledFont

Field Summary

Fields

Modifier and Type	Field	Description
static final int	COLOR_PALETTE_DEFAULT	The default color palette index.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
FontOptions	copy()	Allocates a new font options object copying the option values from the original.
static FontOptions	create()	Allocates a new font options object with all options initialized to default values.
void	destroy()	Invokes the cleanup action that is normally invoked during garbage collection.
boolean	equals(Object other)	Compares two font options objects for equality.
Antialias	getAntialias()	Gets the antialiasing mode for the font options object.
ColorMode	getColorMode()	Gets the color mode for the font options object.
int	getColorPalette()	Gets the current OpenType color font palette for the font options object.
RGBA	getCustomPaletteColor(int index)	Gets the custom palette color for the color index for the font options object.
HintMetrics	getHintMetrics()	Gets the metrics hinting mode for the font options object.
HintStyle	getHintStyle()	Gets the hint style for font outlines for the font options object.
SubpixelOrder	getSubpixelOrder()	Gets the subpixel order for the font options object.
static org.gnome.glib.Type	getType()	Get the CairoFontOptions GType
String	getVariations()	Gets the OpenType font variations for the font options object.
int	hashCode()	Compute a hash for the font options object; this value will be useful when storing an object containing FontOptions in a hash table.
void	merge(FontOptions other)	Merges non-default options from other into this FontOptions, replacing existing values.
void	setAntialias(Antialias antialias)	Sets the antialiasing mode for the font options object.
void	setColorMode(ColorMode colorMode)	Sets the color mode for the font options object.
void	setColorPalette(int colorPalette)	Sets the OpenType font color palette for the font options object.
void	setCustomPaletteColor(int index, double red, double green, double blue, double alpha)	Sets a custom palette color for the font options object.
void	setHintMetrics(HintMetrics hintMetrics)	Sets the metrics hinting mode for the font options object.
void	setHintStyle(HintStyle hintStyle)	Sets the hint style for font outlines for the font options object.
void	setSubpixelOrder(SubpixelOrder subpixelOrder)	Sets the subpixel order for the font options object.
void	setVariations(String variations)	Sets the OpenType font variations for the font options object.
Status	status()	Checks whether an error has previously occurred for this font options object

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

handle

Methods inherited from class java.lang.Object

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

Field Details

COLOR_PALETTE_DEFAULT

public static final int COLOR_PALETTE_DEFAULT

The default color palette index.

Since:

1.18

See Also:

• Constant Field Values

Constructor Details

FontOptions

public FontOptions(MemorySegment address)

Constructor used internally to instantiate a java FontOptions object for a native cairo_font_options_t instance

Parameters:

address - the memory address of the native cairo_font_options_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 FontOptions create()

Allocates a new font options object with all options initialized to default values.

Returns:

newly allocated FontOptions

Since:

1.0

copy

public FontOptions copy()

Allocates a new font options object copying the option values from the original.

Returns:

newly allocated FontOptions

Since:

1.0

status

public Status status()

Checks whether an error has previously occurred for this font options object

Returns:

Status.SUCCESS, Status.NO_MEMORY or Status.NULL_POINTER.

Since:

1.0

merge

public void merge(FontOptions other)

Merges non-default options from other into this FontOptions, replacing existing values. This operation can be thought of as somewhat similar to compositing other onto options with the operation of Operator.OVER.

Parameters:

other - another FontOptions

Since:

1.0

hashCode

public int hashCode()

Compute a hash for the font options object; this value will be useful when storing an object containing FontOptions in a hash table.

Overrides:

hashCode in class Proxy

Returns:

the hash value for the font options object. The return value is cast to a 32-bit type.

Since:

1.0

See Also:

• MemorySegment.hashCode()

equals

public boolean equals(Object other)

Compares two font options objects for equality.

Overrides:

equals in class Proxy

Parameters:

other - another FontOptions

Returns:

true if all fields of the two font options objects match. Note that this function will return false if either object is in error.

Since:

1.0

See Also:

• MemorySegment.equals(Object)

setAntialias

public void setAntialias(Antialias antialias)

Sets the antialiasing mode for the font options object. This specifies the type of antialiasing to do when rendering text.

Parameters:

antialias - the new antialiasing mode

Since:

1.0

getAntialias

public Antialias getAntialias()

Gets the antialiasing mode for the font options object.

Returns:

the antialiasing mode

Since:

1.0

setSubpixelOrder

public void setSubpixelOrder(SubpixelOrder subpixelOrder)

Sets the subpixel order for the font options object. The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of Antialias.SUBPIXEL. See the documentation for SubpixelOrder for full details.

Parameters:

subpixelOrder - the new subpixel order

Since:

1.0

getSubpixelOrder

public SubpixelOrder getSubpixelOrder()

Gets the subpixel order for the font options object. See the documentation for SubpixelOrder for full details.

Returns:

the subpixel order for the font options object

Since:

1.0

setHintStyle

public void setHintStyle(HintStyle hintStyle)

Sets the hint style for font outlines for the font options object. This controls whether to fit font outlines to the pixel grid, and if so, whether to optimize for fidelity or contrast. See the documentation for HintStyle for full details.

Parameters:

hintStyle - the new hint style

Since:

1.0

getHintStyle

public HintStyle getHintStyle()

Gets the hint style for font outlines for the font options object. See the documentation for HintStyle for full details.

Returns:

the hint style for the font options object

Since:

1.0

setHintMetrics

public void setHintMetrics(HintMetrics hintMetrics)

Sets the metrics hinting mode for the font options object. This controls whether metrics are quantized to integer values in device units. See the documentation for HintMetrics for full details.

Parameters:

hintMetrics - the new metrics hinting mode

Since:

1.0

getHintMetrics

public HintMetrics getHintMetrics()

Gets the metrics hinting mode for the font options object. See the documentation for HintMetrics for full details.

Returns:

the metrics hinting mode for the font options object

Since:

1.0

getVariations

public String getVariations()

Gets the OpenType font variations for the font options object. See setVariations(String) for details about the string format.

Returns:

the font variations for the font options object

Since:

1.16

setVariations

public void setVariations(String variations)

Sets the OpenType font variations for the font options object. Font variations are specified as a string with a format that is similar to the CSS font-variation-settings. The string contains a comma-separated list of axis assignments, which each assignment consists of a 4-character axis name and a value, separated by whitespace and optional equals sign.

Examples:

 wght=200,wdth=140.5
 wght 200 , wdth 140.5
 

Parameters:

variations - the new font variations, or null

Since:

1.16

setColorMode

public void setColorMode(ColorMode colorMode)

Sets the color mode for the font options object. This controls whether color fonts are to be rendered in color or as outlines. See the documentation for ColorMode for full details.

Parameters:

colorMode - the new color mode

Since:

1.18

getColorMode

public ColorMode getColorMode()

Gets the color mode for the font options object. See the documentation for ColorMode for full details.

Returns:

the color mode for the font options object

Since:

1.18

setColorPalette

public void setColorPalette(int colorPalette)

Sets the OpenType font color palette for the font options object. OpenType color fonts with a CPAL table may contain multiple palettes. The default color palette index is COLOR_PALETTE_DEFAULT.

If palette_index is invalid, the default palette is used.

Individual colors within the palette may be overriden with cairo_font_options_set_custom_palette_color().

Parameters:

colorPalette - the palette index in the CPAL table

Since:

1.18

getColorPalette

public int getColorPalette()

Gets the current OpenType color font palette for the font options object.

Returns:

the palette index (an unsigned int)

Since:

1.18

setCustomPaletteColor

public void setCustomPaletteColor(int index,
 double red,
 double green,
 double blue,
 double alpha)

Sets a custom palette color for the font options object. This overrides the palette color at the specified color index. This override is independent of the selected palette index and will remain in place even if setColorPalette(int) is called to change the palette index.

It is only possible to override color indexes already in the font palette.

Parameters:

index - the index of the color to set

red - red component of color

green - green component of color

blue - blue component of color

alpha - alpha component of color

Since:

1.18

getCustomPaletteColor

public RGBA getCustomPaletteColor(int index)
                           throws IndexOutOfBoundsException

Gets the custom palette color for the color index for the font options object.

Parameters:

index - the index of the color to get (an unsigned int)

Returns:

the red, green, blue and alpha components of color

Throws:

IndexOutOfBoundsException - if no custom color exists for the color index

Since:

1.18

getType

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

Get the CairoFontOptions GType

Returns:

the GType