cairo_font_face_t — Base class for font faces


cairo_font_face_t represents a particular font at a particular weight, slant, and other characteristic but no size, transformation, or size.

Font faces are created using font-backend-specific constructors, typically of the form cairo_backend_font_face_create(), or implicitly using the toy text API by way of cairo_select_font_face(). The resulting face can be accessed using cairo_get_font_face().



typedef struct _cairo_font_face cairo_font_face_t;

A cairo_font_face_t specifies all aspects of a font other than the size or font matrix (a font matrix is used to distort a font by sheering it or scaling it unequally in the two directions) . A font face can be set on a cairo_t by using cairo_set_font_face(); the size and font matrix are set with cairo_set_font_size() and cairo_set_font_matrix().

There are various types of font faces, depending on the font backend they use. The type of a font face can be queried using cairo_font_face_get_type().

Memory management of cairo_font_face_t is done with cairo_font_face_reference() and cairo_font_face_destroy().

cairo_font_face_reference ()

cairo_font_face_t * cairo_font_face_reference           (cairo_font_face_t *font_face);

Increases the reference count on font_face by one. This prevents font_face from being destroyed until a matching call to cairo_font_face_destroy() is made.

The number of references to a cairo_font_face_t can be get using cairo_font_face_get_reference_count().

font_face :

a cairo_font_face_t, (may be NULL in which case this function does nothing).

Returns :

the referenced cairo_font_face_t.

cairo_font_face_destroy ()

void                cairo_font_face_destroy             (cairo_font_face_t *font_face);

Decreases the reference count on font_face by one. If the result is zero, then font_face and all associated resources are freed. See cairo_font_face_reference().

font_face :

a cairo_font_face_t

cairo_font_face_status ()

cairo_status_t      cairo_font_face_status              (cairo_font_face_t *font_face);

Checks whether an error has previously occurred for this font face

font_face :

a cairo_font_face_t

Returns :


enum cairo_font_type_t

typedef enum _cairo_font_type {
} cairo_font_type_t;

cairo_font_type_t is used to describe the type of a given font face or scaled font. The font types are also known as "font backends" within cairo.

The type of a font face is determined by the function used to create it, which will generally be of the form cairo_type_font_face_create(). The font face type can be queried with cairo_font_face_get_type()

The various cairo_font_face_t functions can be used with a font face of any type.

The type of a scaled font is determined by the type of the font face passed to cairo_scaled_font_create(). The scaled font type can be queried with cairo_scaled_font_get_type()

The various cairo_scaled_font_t functions can be used with scaled fonts of any type, but some font backends also provide type-specific functions that must only be called with a scaled font of the appropriate type. These functions have names that begin with cairo_type_scaled_font() such as cairo_ft_scaled_font_lock_face().

The behavior of calling a type-specific function with a scaled font of the wrong type is undefined.

New entries may be added in future versions.


The font was created using cairo's toy font api


The font is of type FreeType


The font is of type Win32


The font is of type Quartz (Since: 1.6)


The font was create using cairo's user font api (Since: 1.8)

Since 1.2

cairo_font_face_get_type ()

cairo_font_type_t   cairo_font_face_get_type            (cairo_font_face_t *font_face);

This function returns the type of the backend used to create a font face. See cairo_font_type_t for available types.

font_face :

a font face

Returns :

The type of font_face.

Since 1.2

cairo_font_face_get_reference_count ()

unsigned int        cairo_font_face_get_reference_count (cairo_font_face_t *font_face);

Returns the current reference count of font_face.

font_face :

a cairo_font_face_t

Returns :

the current reference count of font_face. If the object is a nil object, 0 will be returned.

Since 1.4

cairo_font_face_set_user_data ()

cairo_status_t      cairo_font_face_set_user_data       (cairo_font_face_t *font_face,
                                                         const cairo_user_data_key_t *key,
                                                         void *user_data,
                                                         cairo_destroy_func_t destroy);

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

font_face :

a cairo_font_face_t

key :

the address of a cairo_user_data_key_t to attach the user data to

user_data :

the user data to attach to the font face

destroy :

a cairo_destroy_func_t which will be called when the font face is destroyed or when new user data is attached using the same key.

Returns :

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a slot could not be allocated for the user data.

cairo_font_face_get_user_data ()

void *              cairo_font_face_get_user_data       (cairo_font_face_t *font_face,
                                                         const cairo_user_data_key_t *key);

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

font_face :

a cairo_font_face_t

key :

the address of the cairo_user_data_key_t the user data was attached to

Returns :

the user data previously attached or NULL.