freetype::FaceDelegate Class Reference

c++ interface on top of c-object pointer More...

#include <cpp_freetype/Face.h>

Public Member Functions
Short &	ascender ()
	The typographic ascender of the face, expressed in font units. For font formats not having this information, it is set to ‘bbox.yMax’. Only relevant for scalable formats. More...
const Short &	ascender () const
Short &	descender ()
	The typographic descender of the face, expressed in font units. For font formats not having this information, it is set to ‘bbox.yMin’. Note that this field is usually negative. Only relevant for scalable formats. More...
const Short &	descender () const
Long &	face_flags ()
	A set of bit flags that give important information about the face; see FT_FACE_FLAG_XXX for the details. More...
const Long &	face_flags () const
Long &	face_index ()
	The index of the face in the font file. It is set to 0 if there is only one face in the font file. More...
const Long &	face_index () const
String *	family_name ()
	The face's family name. This is an ASCII string, usually in English, which describes the typeface's family (like ‘Times New Roman’, ‘Bodoni’, ‘Garamond’, etc). This is a least common denominator used to list fonts. Some formats (TrueType & OpenType) provide localized and Unicode versions of this string. Applications should use the format specific interface to access them. Can be NULL (e.g., in fonts embedded in a PDF file). More...
const String *	family_name () const
UInt	get_char_index (ULong charcode)
	Return the glyph index of a given character code. This function uses a charmap object to do the mapping. More...
ULong	get_first_char (UInt &agindex)
	This function is used to return the first character code in the current charmap of a given face. It also returns the corresponding glyph index. More...
UShort	get_fstype_flags ()
	Return the fsType flags for a font. More...
Error	get_glyph_name (UInt glyph_index, Pointer buffer, UInt buffer_max)
	Retrieve the ASCII name of a given glyph in a face. This only works for those faces where FT_HAS_GLYPH_NAMES(face) returns 1. More...
UInt	get_name_index (String *glyph_name)
	Return the glyph index of a given glyph name. This function uses driver specific objects to do the translation. More...
ULong	get_next_char (ULong char_code, UInt &agindex)
	This function is used to return the next character code in the current charmap of a given face following the value ‘char_code’, as well as the corresponding glyph index. More...
const char *	get_postscript_name ()
	Retrieve the ASCII PostScript name of a given face, if available. This only works with PostScript and TrueType fonts. More...
RefPtr< GlyphSlot >	glyph ()
	The face's associated glyph slot(s). More...
bool	has_fast_glyphs ()
bool	has_fixed_sizes ()
bool	has_glyph_names ()
bool	has_horizontal ()
	The current active size for this face. More...
bool	has_kerning ()
bool	has_multiple_masters ()
bool	has_vertical ()
Short &	height ()
	The height is the vertical distance between two consecutive baselines, expressed in font units. It is always positive. Only relevant for scalable formats. More...
const Short &	height () const
bool	is_cid_keyed ()
bool	is_fixed_width ()
bool	is_scalable ()
bool	is_sfnt ()
bool	is_tricky ()
Error	load_char (ULong char_code, Int32 load_flags)
	A function used to load a single glyph into the glyph slot of a face object, according to its character code. More...
Error	load_glyph (UInt glyph_index, Int32 load_flags)
	A function used to load a single glyph into the glyph slot of a face object. More...
Short &	max_advance_height ()
	The maximum advance height, in font units, for all glyphs in this face. This is only relevant for vertical layouts, and is set to ‘height’ for fonts that do not provide vertical metrics. Only relevant for scalable formats. More...
const Short &	max_advance_height () const
Short &	max_advance_width ()
	The maximum advance width, in font units, for all glyphs in this face. This can be used to make word wrapping computations faster. Only relevant for scalable formats. More...
const Short &	max_advance_width () const
Int &	num_charmaps ()
	An array of FT_Bitmap_Size for all bitmap strikes in the face. It is set to NULL if there is no bitmap strike. More...
const Int &	num_charmaps () const
Long &	num_faces ()
	Structure Accessors More...
const Long &	num_faces () const
Int &	num_fixed_sizes ()
	The number of bitmap strikes in the face. Even if the face is scalable, there might still be bitmap strikes, which are called ‘sbits’ in that case. More...
const Int &	num_fixed_sizes () const
Long &	num_glyphs ()
	The number of glyphs in the face. If the face is scalable and has sbits (see ‘num_fixed_sizes’), it is set to the number of outline glyphs. For CID-keyed fonts, this value gives the highest CID used in the font. More...
const Long &	num_glyphs () const
FaceDelegate *	operator-> ()
const FaceDelegate *	operator-> () const
Error	select_charmap (Encoding encoding)
	Select a given charmap by its encoding tag (as listed in ‘freetype.h’). More...
Error	select_size (Int strike_index)
	Member Functions More...
Error	set_char_size (F26Dot6 char_width, F26Dot6 char_height, UInt horz_resolution, UInt vert_resolution)
	Calls FT_Request_Size to request the nominal size (in points) More...
Error	set_charmap (UInt id)
	Select a given charmap for character code to glyph index mapping. More...
Error	set_pixel_sizes (UInt pixel_width, UInt pixel_height)
	This function calls FT_Request_Size to request the nominal size (in pixels). More...
Long &	style_flags ()
	A set of bit flags indicating the style of the face; see FT_STYLE_FLAG_XXX for the details. More...
const Long &	style_flags () const
String *	style_name ()
	The face's style name. This is an ASCII string, usually in English, which describes the typeface's style (like ‘Italic’, ‘Bold’, ‘Condensed’, etc). Not all font formats provide a style name, so this field is optional, and can be set to NULL. As for ‘family_name’, some formats provide localized and Unicode versions of this string. Applications should use the format specific interface to access them. More...
const String *	style_name () const
Short &	underline_position ()
	The position, in font units, of the underline line for this face. It is the center of the underlining stem. Only relevant for scalable formats. More...
const Short &	underline_position () const
Short &	underline_thickness ()
	The thickness, in font units, of the underline for this face. Only relevant for scalable formats. More...
const Short &	underline_thickness () const
UShort &	units_per_EM ()
	An array of the charmaps of the face. More...
const UShort &	units_per_EM () const

Private Member Functions
	FaceDelegate (FT_Face ptr=0)
	constructable only by RefPtr<Face> More...
	FaceDelegate (const FaceDelegate &)
	not copy-constructable More...
FaceDelegate &	operator= (const FaceDelegate &)
	not copy-assignable More...

Private Attributes
FT_Face	m_ptr

Friends
class	RefPtr< Face >

Detailed Description

c++ interface on top of c-object pointer

Definition at line 45 of file Face.h.

Constructor & Destructor Documentation

freetype::FaceDelegate::FaceDelegate ( FT_Face  ptr = 0 )

inlineprivate

constructable only by RefPtr<Face>

Definition at line 51 of file Face.h.

freetype::FaceDelegate::FaceDelegate ( const FaceDelegate &  )

private

not copy-constructable

Member Function Documentation

Short& freetype::FaceDelegate::ascender

(

)

The typographic ascender of the face, expressed in font units. For font formats not having this information, it is set to ‘bbox.yMax’. Only relevant for scalable formats.

const Short& freetype::FaceDelegate::ascender

(

)

const

Short& freetype::FaceDelegate::descender

(

)

The typographic descender of the face, expressed in font units. For font formats not having this information, it is set to ‘bbox.yMin’. Note that this field is usually negative. Only relevant for scalable formats.

const Short& freetype::FaceDelegate::descender

(

)

const

Long& freetype::FaceDelegate::face_flags

(

)

A set of bit flags that give important information about the face; see FT_FACE_FLAG_XXX for the details.

const Long& freetype::FaceDelegate::face_flags

(

)

const

Long& freetype::FaceDelegate::face_index

(

)

The index of the face in the font file. It is set to 0 if there is only one face in the font file.

const Long& freetype::FaceDelegate::face_index

(

)

const

String* freetype::FaceDelegate::family_name

(

)

The face's family name. This is an ASCII string, usually in English, which describes the typeface's family (like ‘Times New Roman’, ‘Bodoni’, ‘Garamond’, etc). This is a least common denominator used to list fonts. Some formats (TrueType & OpenType) provide localized and Unicode versions of this string. Applications should use the format specific interface to access them. Can be NULL (e.g., in fonts embedded in a PDF file).

const String* freetype::FaceDelegate::family_name

(

)

const

UInt freetype::FaceDelegate::get_char_index

(

ULong

charcode

)

Return the glyph index of a given character code. This function uses a charmap object to do the mapping.

Parameters

[in]

charcode

The character code.

Returns

The glyph index. 0 means ‘undefined character code’.

If you use FreeType to manipulate the contents of font files directly, be aware that the glyph index returned by this function doesn't always correspond to the internal indices used within the file. This is done to ensure that value 0 always corresponds to the ‘missing glyph’. If the first glyph is not named ‘.notdef’, then for Type 1 and Type 42 fonts, ‘.notdef’ will be moved into the glyph ID 0 position, and whatever was there will be moved to the position ‘.notdef’ had. For Type 1 fonts, if there is no ‘.notdef’ glyph at all, then one will be created at index 0 and whatever was there will be moved to the last index – Type 42 fonts are considered invalid under this condition.

ULong freetype::FaceDelegate::get_first_char

(

UInt &

agindex

)

This function is used to return the first character code in the current charmap of a given face. It also returns the corresponding glyph index.

Parameters

[out]

agindex

Glyph index of first character code. 0 if charmap is empty.

Returns

The charmap's first character code.

You should use this function with FT_Get_Next_Char to be able to parse all character codes available in a given charmap. The code should look like this:

FT_ULong  charcode;
FT_UInt   gindex;


charcode = FT_Get_First_Char( face, &gindex );
while ( gindex != 0 )
{
    //... do something with (charcode,gindex) pair ...

    charcode = FT_Get_Next_Char( face, charcode, &gindex );
}

        Note that ‘*agindex’ is set to 0 if the charmap is empty. The
        result itself can be 0 in two cases: if the charmap is empty or if
        the value 0 is the first valid character code.

UShort freetype::FaceDelegate::get_fstype_flags

(

)

Return the fsType flags for a font.

Returns

The fsType flags, FT_FSTYPE_XXX.

Use this function rather than directly reading the ‘fs_type’ field in the PS_FontInfoRec structure which is only guaranteed to return the correct results for Type 1 fonts.

Error freetype::FaceDelegate::get_glyph_name	(	UInt	glyph_index,
		Pointer	buffer,
		UInt	buffer_max
	)

Retrieve the ASCII name of a given glyph in a face. This only works for those faces where FT_HAS_GLYPH_NAMES(face) returns 1.

Parameters

[in]	glyph_index	The glyph index.
[out]	buffer	A pointer to a target buffer where the name is copied to.
[in]	buffer_max	The maximum number of bytes available in the buffer.

Returns

FreeType error code. 0 means success.

An error is returned if the face doesn't provide glyph names or if the glyph index is invalid. In all cases of failure, the first byte of ‘buffer’ is set to 0 to indicate an empty name.

The glyph name is truncated to fit within the buffer if it is too long. The returned string is always zero-terminated.

Be aware that FreeType reorders glyph indices internally so that glyph index 0 always corresponds to the ‘missing glyph’ (called ‘.notdef’).

This function is not compiled within the library if the config macro ‘FT_CONFIG_OPTION_NO_GLYPH_NAMES’ is defined in ‘include/freetype/config/ftoptions.h’.

UInt freetype::FaceDelegate::get_name_index

(

String *

glyph_name

)

Return the glyph index of a given glyph name. This function uses driver specific objects to do the translation.

Parameters

[in]

glyph_name

The glyph name.

Returns

The glyph index. 0 means ‘undefined character code’.

ULong freetype::FaceDelegate::get_next_char	(	ULong	char_code,
		UInt &	agindex
	)

This function is used to return the next character code in the current charmap of a given face following the value ‘char_code’, as well as the corresponding glyph index.

Parameters

[in]	char_code	The starting character code.
[out]	agindex	Glyph index of next character code. 0 if charmap is empty.

Returns

The charmap's next character code.

You should use this function with FT_Get_First_Char to walk over all character codes available in a given charmap. See the note for this function for a simple code example.

Note that ‘*agindex’ is set to 0 when there are no more codes in the charmap.

const char* freetype::FaceDelegate::get_postscript_name

(

)

Retrieve the ASCII PostScript name of a given face, if available. This only works with PostScript and TrueType fonts.

Returns

A pointer to the face's PostScript name. NULL if unavailable.

Note

The returned pointer is owned by the face and is destroyed with it.

RefPtr<GlyphSlot> freetype::FaceDelegate::glyph

(

)

The face's associated glyph slot(s).

bool freetype::FaceDelegate::has_fast_glyphs

(

)

bool freetype::FaceDelegate::has_fixed_sizes

(

)

bool freetype::FaceDelegate::has_glyph_names

(

)

bool freetype::FaceDelegate::has_horizontal

(

)

The current active size for this face.

The current active charmap for this face.

bool freetype::FaceDelegate::has_kerning

(

)

bool freetype::FaceDelegate::has_multiple_masters

(

)

bool freetype::FaceDelegate::has_vertical

(

)

Short& freetype::FaceDelegate::height

(

)

The height is the vertical distance between two consecutive baselines, expressed in font units. It is always positive. Only relevant for scalable formats.

const Short& freetype::FaceDelegate::height

(

)

const

bool freetype::FaceDelegate::is_cid_keyed

(

)

bool freetype::FaceDelegate::is_fixed_width

(

)

bool freetype::FaceDelegate::is_scalable

(

)

bool freetype::FaceDelegate::is_sfnt

(

)

bool freetype::FaceDelegate::is_tricky

(

)

Error freetype::FaceDelegate::load_char	(	ULong	char_code,
		Int32	load_flags
	)

A function used to load a single glyph into the glyph slot of a face object, according to its character code.

Parameters

[in]	char_code	The glyph's character code, according to the current charmap used in the face.
[in]	load_flags	A flag indicating what to load for this glyph. The FT_LOAD_XXX constants can be used to control the glyph loading process (e.g., whether the outline should be scaled, whether to load bitmaps or not, whether to hint the outline, etc).

Returns

FreeType error code. 0 means success.

This function simply calls FT_Get_Char_Index and FT_Load_Glyph.

Error freetype::FaceDelegate::load_glyph	(	UInt	glyph_index,
		Int32	load_flags
	)

A function used to load a single glyph into the glyph slot of a face object.

Parameters

[in]	glyph_index	The index of the glyph in the font file. For CID-keyed fonts (either in PS or in CFF format) this argument specifies the CID value.
[in]	load_flags	A flag indicating what to load for this glyph. The FT_LOAD_XXX constants can be used to control the glyph loading process (e.g., whether the outline should be scaled, whether to load bitmaps or not, whether to hint the outline, etc).

Returns

FreeType error code. 0 means success.

The loaded glyph may be transformed. See FT_Set_Transform for the details.

For subsetted CID-keyed fonts, ‘FT_Err_Invalid_Argument’ is returned for invalid CID values (this is, for CID values which don't have a corresponding glyph in the font). See the discussion of the FT_FACE_FLAG_CID_KEYED flag for more details.

Short& freetype::FaceDelegate::max_advance_height

(

)

The maximum advance height, in font units, for all glyphs in this face. This is only relevant for vertical layouts, and is set to ‘height’ for fonts that do not provide vertical metrics. Only relevant for scalable formats.

const Short& freetype::FaceDelegate::max_advance_height

(

)

const

Short& freetype::FaceDelegate::max_advance_width

(

)

The maximum advance width, in font units, for all glyphs in this face. This can be used to make word wrapping computations faster. Only relevant for scalable formats.

const Short& freetype::FaceDelegate::max_advance_width

(

)

const

Int& freetype::FaceDelegate::num_charmaps

(

)

An array of FT_Bitmap_Size for all bitmap strikes in the face. It is set to NULL if there is no bitmap strike.

The number of charmaps in the face.

const Int& freetype::FaceDelegate::num_charmaps

(

)

const

Long& freetype::FaceDelegate::num_faces

(

)

---

Structure Accessors

The number of faces in the font file. Some font formats can have multiple faces in a font file.

const Long& freetype::FaceDelegate::num_faces

(

)

const

Int& freetype::FaceDelegate::num_fixed_sizes

(

)

The number of bitmap strikes in the face. Even if the face is scalable, there might still be bitmap strikes, which are called ‘sbits’ in that case.

const Int& freetype::FaceDelegate::num_fixed_sizes

(

)

const

Long& freetype::FaceDelegate::num_glyphs

(

)

The number of glyphs in the face. If the face is scalable and has sbits (see ‘num_fixed_sizes’), it is set to the number of outline glyphs. For CID-keyed fonts, this value gives the highest CID used in the font.

const Long& freetype::FaceDelegate::num_glyphs

(

)

const

FaceDelegate* freetype::FaceDelegate::operator-> ( )

inline

Definition at line 64 of file Face.h.

const FaceDelegate* freetype::FaceDelegate::operator-> ( ) const

inline

Definition at line 65 of file Face.h.

FaceDelegate& freetype::FaceDelegate::operator= ( const FaceDelegate &  )

private

not copy-assignable

Error freetype::FaceDelegate::select_charmap

(

Encoding

encoding

)

Select a given charmap by its encoding tag (as listed in ‘freetype.h’).

Parameters

[in]

encoding

handle to the selected encoding

Returns

FreeType error code. 0 means success.

This function returns an error if no charmap in the face corresponds to the encoding queried here.

Because many fonts contain more than a single cmap for Unicode encoding, this function has some special code to select the one which covers Unicode best (‘best’ in the sense that a UCS-4 cmap is preferred to a UCS-2 cmap). It is thus preferable to FT_Set_Charmap in this case.

Error freetype::FaceDelegate::select_size

(

Int

strike_index

)

---

Member Functions

Select a bitmap strike

Parameters

[in]

strike_index

the index of the bitmap strike in the available_sizes field of the underlying struct

Returns

FreeType error code. 0 means success.

Error freetype::FaceDelegate::set_char_size	(	F26Dot6	char_width,
		F26Dot6	char_height,
		UInt	horz_resolution,
		UInt	vert_resolution
	)

Calls FT_Request_Size to request the nominal size (in points)

Parameters

[in]	char_width	The nominal width, in 26.6 fractional points.
[in]	char_height	The nominal height, in 26.6 fractional points.
[in]	horz_resolution	The horizontal resolution in dpi.
[in]	vert_resolution	The vertical resolution in dpi.

Returns

FreeType error code. 0 means success.

If either the character width or height is zero, it is set equal to the other value.

If either the horizontal or vertical resolution is zero, it is set equal to the other value.

A character width or height smaller than 1pt is set to 1pt; if both resolution values are zero, they are set to 72dpi.

Don't use this function if you are using the FreeType cache API.

Error freetype::FaceDelegate::set_charmap

(

UInt

id

)

Select a given charmap for character code to glyph index mapping.

Parameters

[in]

id

index in charmaps, must be less than num_charmaps

Returns

FreeType error code. 0 means success.

This function returns an error if id is not a valid charmap.

Error freetype::FaceDelegate::set_pixel_sizes	(	UInt	pixel_width,
		UInt	pixel_height
	)

This function calls FT_Request_Size to request the nominal size (in pixels).

Parameters

[in]	pixel_width	The nominal width, in pixels.
[in]	pixel_height	The nominal height, in pixels.

Returns

FreeType error code. 0 means success.

Long& freetype::FaceDelegate::style_flags

(

)

A set of bit flags indicating the style of the face; see FT_STYLE_FLAG_XXX for the details.

const Long& freetype::FaceDelegate::style_flags

(

)

const

String* freetype::FaceDelegate::style_name

(

)

The face's style name. This is an ASCII string, usually in English, which describes the typeface's style (like ‘Italic’, ‘Bold’, ‘Condensed’, etc). Not all font formats provide a style name, so this field is optional, and can be set to NULL. As for ‘family_name’, some formats provide localized and Unicode versions of this string. Applications should use the format specific interface to access them.

const String* freetype::FaceDelegate::style_name

(

)

const

Short& freetype::FaceDelegate::underline_position

(

)

The position, in font units, of the underline line for this face. It is the center of the underlining stem. Only relevant for scalable formats.

const Short& freetype::FaceDelegate::underline_position

(

)

const

Short& freetype::FaceDelegate::underline_thickness

(

)

The thickness, in font units, of the underline for this face. Only relevant for scalable formats.

const Short& freetype::FaceDelegate::underline_thickness

(

)

const

UShort& freetype::FaceDelegate::units_per_EM

(

)

An array of the charmaps of the face.

A field reserved for client uses. See the FT_Generic type description. The font bounding box. Coordinates are expressed in font units (see ‘units_per_EM’). The box is large enough to contain any glyph from the font. Thus, ‘bbox.yMax’ can be seen as the ‘maximum ascender’, and ‘bbox.yMin’ as the ‘minimum descender’. Only relevant for scalable formats. Note that the bounding box might be off by (at least) one pixel for hinted fonts. See FT_Size_Metrics for further discussion. The number of font units per EM square for this face. This is typically 2048 for TrueType fonts, and 1000 for Type 1 fonts. Only relevant for scalable formats.

const UShort& freetype::FaceDelegate::units_per_EM

(

)

const

Friends And Related Function Documentation

friend class RefPtr< Face >

friend

Definition at line 62 of file Face.h.

Member Data Documentation

FT_Face freetype::FaceDelegate::m_ptr

private

Definition at line 48 of file Face.h.

---

The documentation for this class was generated from the following file:

• include/cpp_freetype/Face.h