class HT_Font

class HT_Font_Engine

An object of this class provides fonts and font management. Font engines may be implemented in hardware or software. A font engine is either an attribute of a renderer or is a default software font engine provided by the Heidi system. You can obtain an existing font engine by calling the font_engine method of a renderer or by loading the default font engine with

HD_Dynamic_Loader ("gdifont10.hdi", "HD_Font_Engine").

A font engine provides a set of fonts. To specify the fonts, the application must provide the font engine with a list of directories to search. This is accomplished with the font directory methods.

After directories have been installed, the application queries the font engine for a list of fonts or provides the font engine with a font descriptor to choose a font to be loaded. These are loaded with the load_font method.

In order for the font engine to take into effect the set configurations, the clients of the font engine need to call establish(). establish(), in turn, does the appropriate configurations necessary and calls establish_configuration(). The text can then be drawn by choosing the appropriate attribute settings for the rendition and calling draw_2d_textor draw_3d_text. After the text is drawn, the unload_font method is used to remove the fonts.

For more information and code examples see chapter 5, "The Font Engine."

See Also HT_Font,HT_Contour_Set, HT_Renderer::draw_2d_text, HT_Renderer::draw_3d_text Access Methods

Character Methods

get_char_outline

Returns the outline of the character as an HT_Contour_Set.

get_character_placement

Returns the widths of the characters in a string.

get_character_widths

Returns the widths of the characters in the range first_char to last_char.

Font Directory Methods

add_dir

Adds a directory to the font search path.

dir

Returns the directory at the current position in the list.

first_dir

Gets the pointer to the first directory and sets the current position to the head of the list of directories.

next_dir

Returns the next directory in the list, or null if at the end of the list and also advances the current position in the list.

Font Engine Draw Methods

draw_2d_text

Draws the text in 2D using the font and attributes which were set on the passed rendition.

draw_3d_text

Draws the text in 3D using the font and attributes which were set on the passed rendition.

Font Engine Get Methods

get_font_design_metrics

Returns the font metrics in font design units. Font design units are the units (the resolution of the grid) in which the font was designed.

get_font_metrics

Returns the font metrics in pixel units.

Font Load Methods

load_font

Method to request the font engine to load the required font.

font_loaded

Method indicating that the font is loaded.

unload_font

Method to unload a font.

Font Management Methods

add_font

Add a font to the font engine's list of fonts.

attachment

Place holder for application information associated with runtime loadable objects.

find_font

Returns a font based on a font descriptor.

find_glyph

Returns true if the character/glyph exists in a font.

first_font

Get the pointer to the first font and set the current position to the head of the list of fonts.

font

Returns the font at the current position in the list.

next_font

Returns the next font in the list, or null if at the end of the list and also advances the current position in the list.
Query Methods

option

Retrieves a pointer to the current option structure.

option_value, set_option_value

Retrieves and sets an option value.

renderer, set_renderer

Retrieves and sets a pointer to the renderer in which this font engine is installed.

Text Methods

get_text_extent

Calculates the text bound. Constructor/Destructor

HT_Font_Engine

Creates a font engine object which is typically done by the application after the font engine has been loaded.

~HT_Font_Engine

Destroys a font engine object.

HT_Font_Engine::add_{dir, font}

Purpose

Methods to add a font search path directory to a directory list, or a font object into the font list of the font engine. Synopsis

void add_dir (char *x)

HT_Position add_font (HT_Font const & x)

Details The specified object (either directory name or font object) is added to one of the two lists maintained by the font engine. For information about how to iterate through these lists, see the first_... and next_... members of this class.

HT_Font_Engine::attachment, set_attachment

Purpose

A place holder for applications to hang information associated with objects created by runtime loadable routines.

Synopsis

HT_Counted const * attachment () const

void set_attachment (HT_Counted * in)

Details A current and configuration access method, it is used with the Appkit utility.

HT_Font_Engine::{dir, font}

Purpose

Methods to retrieve the current position in the font search path directory, or font lists maintained by this font engine. Synopsis

HT_Font font(HT_Position p)

HT_Directory * dir(HT_Position p)

Details The entry in the position specified by pos in the list of directory names, or font objects is returned. For information about how to retrieve the first element in each of these lists, see the first_... members of this class.

HT_Font_Engine::draw_2d_text

Purpose

Draws 2D text into the display context of the renderer. Synopsis

void draw_2d_text (
            HT_Rendition const &        hr,
            HT_DCI_Point const &        pos,
            char const *                str,
            int                         count = -1) alter

void draw_2d_text (
            HT_Rendition const &        hr,
            HT_DCI_Point const &        pos,
            unsigned short const *      str,
            int                         count) alter

Details This function is used by applications to draw 2D text into the device context of the renderer. The font engine draws the text according to the current text and color attributes specified in the rendition passed by hr. pos specifies the device coordinates for the lower-left corner of the text starting position. str specifies the text which is drawn according to the font that this font object represents. float const* char_spacing is specifying an array of floats for character spacing. The forms take a count refering to the number of characters (not the size in bytes) to use. The multi-byte character string need not be null terminated. The second form is for UNICODE.

Note: The draw_2d_text() functions now use HT_DCI_Point for the position instead of HT_Point.

See Also

The HT_Renderer::draw_2d_text action draws 2D text similar to other geometry, instead of directly calling the Font Engine.

HT_Font_Engine::draw_3d_text

Purpose

Draws 3D text into the display context of the renderer. Synopsis

void draw_3d_text (
    HT_Rendition const &        hr,
    HT_Point const &            pos,
    char const *                str) alter

void draw_3d_text (
            HT_Rendition const &        hr,
            HT_Point const &            pos,
            char const *                str,
            int                         count) alter {

            modify().draw_3d_text (hr, pos, str, count);

void draw_3d_text (
    HT_Rendition const &        hr,
    HT_Point const &            pos,
    unsigned short const *      str,
    int                         count) alter

Details This function is used by applications to draw 3D text into the device context of the renderer. The font engine draws the text according to the current text and color attributes specified in the rendition passed by hr. pos specifies the device coordinates for the lower-left corner of the text starting position. strspecifies the text which is drawn according to the font that this font object represents. The second form takes a count refering to the number of characters (not the size in bytes) to use. The multi-byte character string need not be null terminated. The third form is for UNICODE. See Also

The HT_Renderer::draw_3d_text action draws 3D text similar to other geometry, instead of directly calling the Font Engine.

HT_Font_Engine::find_font

Purpose

Returns a font based on a font descriptor. Synopsis

HT_Font find_font (HT_Font_Descriptor const & x, HT_Position & p)

HT_Font find_font (HT_Font_Descriptor const & x)

HT_Font_Engine::find_glyph

Purpose

Returns true if the glyph associated with a given number, representing the character, exists in the current font. Synopsis

HT_Boolean find_glyph (HT_Rendition const & hr, unsigned short glyph)

Details A glyph is the pictorial representation of a character.

HT_Font_Engine::first_{dir, font}

Purpose

Methods to retrieve the first font search path directory, or the first font from the lists maintained by this font engine. Synopsis

HT_Directory * first_dir (HT_Position & p)

HT_Font first_font(HT_Position & p)

Details For information about how to iterate through the remainder lists, see the next_... members of this class.

HT_Font_Engine::font

Purpose

Returns the font at the current position in the list. Synopsis

HT_Font font (HT_Position p)

HT_Font_Engine::font_loaded

Purpose

Method indicating whether the font has been loaded. Synopsis

HT_Boolean font_loaded (HT_Font const & x) const

HT_Font_Engine::get_char_outline

Purpose

Returns the outline of the character Synopsis

HT_Contour_Set get_char_outline  (
    HT_Rendition const &         hr,
    unsigned short               uchar,
    HT_Glyph_Metrics *           gm) alter

Details

This function returns an HT_Contour_Set for the character outline along with an HT_Glyph_Metrics structure. A contour set is a collection of one or more contours. A contour is a list of vertices that make a polyline/polygon. For example, in figure 1, the contour set is comprised of two contours. Each contour has four vertices as shown. For more information see class HT_Contour_Set.

Figure 1. Contour set

The glyph metrics returns the metrics of the character such as the width, height and the increment required in the x and y directions to place the next character. Tessellations generated are based on resolution in dpi and text quality ¾ a number between 0 and 100. The default resolution is 96 dpi and the default text quality is 50.

Note: The following function is obsolete as the resolution parameter has been removed since resolution and text quality are now set as options on the font engine. As a result, in debug mode, the resolution option will report "obsolete" when called by older applications.

HT_Contour_Set get_char_outline (
            HT_Rendition const &        hr,
            unsigned short              uchar,
            int                         resolution,
            HT_Glyph_Metrics *          gm) alter

HT_Font_Engine::get_character_placement

Purpose

Currently, this method returns the widths of the characters in a string. Synopsis

void get_character_placement(
    HT_Rendition const &             hr, 
    unsigned short const *           str, 
    int                              count, 
    float *                          spacing) alter

Details This method returns the character spacing based on the current font, the given array and character count.

HT_Font_Engine::get_character_widths

Purpose

Returns the width of the characters in the range starting from and inclusive of first_char to last_char. Synopsis

void get_character_widths (
    HT_Rendition const &             hr,
    unsigned short                   first_char,
    unsigned short                   last_char,
    float *                          width) alter

Details This method returns the width of each character in a string. It starts with the first single character and considers each character until the last character in the range is reached.

HT_Font_Engine::get_font_design_metrics

Purpose

Returns the font metrics in Font design units. Font design units are the units (the resolution of the grid) in which the font was designed. Synopsis

void get_font_design_metrics (
    HT_Rendition const & hr, 
    HT_Font_Metrics * fm)alter

Details The get_font_design_metrics method returns the design metrics of the font in font design units. Font design units are the units in which the font is originally designed. The font design metrics is also the EmSquare size of the font, that is to say, the resolution of the rectangular grid used to digitize the font.

The font design units are very useful in that they give the true metrics of the font which will be unadulterated by rasterization. These metrics are useful for advanced text layout.

HT_Font_Engine::get_font_metrics

Purpose

Returns the font metrics in pixels, based on the current size of the font. Synopsis

void get_font_metrics (
    HT_Rendition const & hr,
    HT_Font_Metrics * fm)alter

Details

The get_font_metrics method returns the pixel based metrics of the font. The metrics will be scaled to reflect the values for the current font size. For more information, see the get_font_design_metricsmethod in this class.

HT_Font_Engine::get_text_extent

Purpose

Calculates the text bound. Synopsis

void get_text_extent (
            HT_Rendition const &        hr,
            HT_DCI_Point const &        pos,
            char const *                str,
            HT_Point *                  result,
            HT_Boolean                  tight_extents=HK_False,
            HT_Extent_Metrics *         extent_metrics=null) alter 

        void get_text_extent (
            HT_Rendition const &        hr,
            HT_DCI_Point const &        pos,
            char const *                str,
            int                         count,
            HT_Point *                  result,
            HT_Boolean                  tight_extents=HK_False,
            HT_Extent_Metrics *         extent_metrics=null) alter 

        void get_text_extent (
            HT_Rendition const &        hr,
            HT_DCI_Point const &        pos,
            unsigned short const *      str,
            int                         count,
            HT_Point *                  result,
            HT_Boolean                  tight_extents=HK_False,
            HT_Extent_Metrics *         extent_metrics=null) alter

Details This function is used by applications to compute the rectangle that bounds the input string str. The input parameter, resultis the address of an array of four HT_Point values, where the function fills in the bounds. pos specifies the device coordinates for the lower-left corner of the text base line, the starting position. str specifies the text which is drawn according to the font that this font object represents. extent_metrics tells the application the ascent, descent, leading and trailing spaces in the returned text extent. The extent metrics in addition returns the widths of each character in the string, which is useful for the application to do text layout and formatting.

By default, get_text_extent returns the rectangular extents of the text. If tight extents is specified, it returns the bounding box of the text in the rotated position. Figure 2 shows the case where tight_extents is true. The default for tight_extents is false.

The second form takes a count refering to the number of characters (not the size in bytes) to use.

The third form is for UNICODE.

Note: The get_text_extent() functions now use HT_DCI_Point for the position instead of HT_Point.

Figure 2. tight_extents = true

HT_Font_Engine::HT_Font_Engine

Purpose

Creates a font engine object. Synopsis

HT_Font_Engine()

HT_Font_Engine (HT_Font_Engine_Data const * in)

Details The font engine should only be created by applications. This is done after the engine is loaded with HD_Load_Dynamic_Routine which returns an HT_Create_Font_Engine pointer. From the pointer, HT_Font_Engine is created with the desired renderer as input.

HT_Font_Engine::~HT_Font_Engine

Purpose

Destroys a font engine object. Synopsis

~HT_Font_Engine()

Details A font engine object is destroyed. This is typically only done by an application when it has completed its use of the font engine. The font object was created by HT_Font_Engine::load_font.

HT_Font_Engine::load_font

Purpose

Method to load a font into the font engine. Synopsis

HT_Font load_font(HT_Font alter & x)

Details The font specified by the input parameter font_object is loaded. This internally, loads a font into memory or gets the font ready for query or draw purposes. load_font() does not select a font. The HT_Font object given to load_font() is a font that the font engine already knows. The font should be selected by iterating through the list of the font engine fonts or by using the find_font() method. The method returns true if the font was successfully loaded or else it returns false.

HT_Font_Engine::next_{dir, font}

Purpose

Methods to retrieve the next font search path directory, or loaded font from the lists maintained by this font engine. Synopsis

HT_Directory * next_dir(HT_Position& p)

HT_Font next_font(HT_Position& p)

Details For information about how to initialize the current position to the beginning of the list, see the first_... members of this class.

HT_Font_Engine::option

Purpose

Retrieves a pointer to the current option structure. Synopsis

HT_Option const * option (HT_String const & name) const

Details Current and configuration access methods.

HT_Font_Engine::option_value, set_option_value

Purpose

Retrieves and sets an option value. Synopsis

HT_Option const * option (HT_String const & name) const

HT_Boolean set_option_value (HT_String const & name,
                           HT_Option_Value const & value) alter

Details Current and configuration access methods.

HT_Font_Engine::renderer, set_renderer

Purpose

Returns the renderer in which this font engine is installed. Synopsis

HT_Renderer const & renderer() const

void set_renderer (HT_Renderer const & in_renderer) alter

Details The font engine is created in the context of a specific renderer. This function returns that renderer.

Note: Previously this renderer had to be GDI compatible, now this is nolonger necessary as the GDI_Font_Engine works with a non-GDI compatible renderer. Now, if Heidi is configured with a non-GDI compatible render below the font engine, the font engine will tesselate the font geometry into triangles, polygons or polylines and draw the tesselated data through Heidi.

HT_Font_Engine::unload_font

Purpose

Method to unload a font object Synopsis

HT_Boolean unload_font (HT_Font alter & x)

Details The method is used to unload (remove) the font from the font engine after the font has been loaded and the text drawn.