Class Documentation

Name:Font
Version:2.0
ID:ID_FONT
Status:Unspecified
Category:Graphics
Include:pandora/graphics/font.h
Date:April 2003
Author:Rocklyte Systems, some portions based on the FreeType Project.
Copyright:  Rocklyte Systems, 1998-2003. All rights reserved.
Short:  Draws text in different type faces and styles.



Description

The Font class is provided for the purpose of rendering strings to Bitmap graphics. It supports standard effects such as bold, italic and underlined text, along with extra features such as adjustable spacing, word alignment and outlining. Fixed-point bitmap fonts are supported through the Windows .fon file format and TrueType font files are supported for scaled font rendering.

Fonts must be stored in the "fonts:" directory in order to be recognised and either in the "fixed" or "truetype" sub-directories as appropriate. The process of font installation and file management is managed by the "SystemFonts" object, a member of the FontServer class. If you need to install, remove or retrieve font information (such as a list of available faces), please refer to the FontServer documentation for more detail.

The Font class includes full support for the unicode character set through its support for UTF-8. This gives you the added benefit of being able to support international character sets with ease, but you must be careful not to use character codes above #127 without being sure that they follow UTF-8 guidelines. You can find out more about UTF-8 at this web page.

Initialisation of a new font object can be as simple as declaring its Point size and Face name. It is necessary to bear in mind that fonts are resistent to alteration after initialisation, so all style and graphical selections must be set early. For example, it is not possible to change styling from regular to bold format without the request being rejected. To support multiple styles of the same font, you therefore need to create a font object for every style that you wish to support. Basic features such as colour, the font string and text positioning are not affected by these restrictions.

To draw a font string to a Bitmap object, start by setting the Bitmap and String fields. The XCoord and YCoord fields determine string positioning and you can also use the Align field to align a string to the right or center of the drawable area.

Finally, here is some clarification on some of the terminology used in the Font class and further documentation:

  • 'Point' determines the size of a font. The value is relative only to other point sizes of the same font face, i.e. two faces at the same point size are not necessarily the same height.
  • 'Height' represents the 'vertical bearing' or point of the font, expressed as a pixel value. The height does not cover for any leading at the top of the font, or the gutter space used for the tails on characters like 'g' and 'y'.
  • 'Gutter' is the amount of space that a character can descend below the base line. Characters like 'g' and 'y' are examples of characters that utilise the gutter space. The gutter is also sometimes known as the "external leading" of a character.
  • 'LineSpacing' is the recommended pixel distance between each line that is printed with the font.
  • Actions

    The Font class supports the following actions:

    Draw  Draws a font to a Bitmap.
    Refresh  Refreshes the system font list with up-to-date font information.

    Methods

    The Font class implements the following methods:

    CalcStringWidth  Returns the pixel width of any given string in relation to a font's settings.
    ConvertFontCoords  Converts pixel coordinates into equivalent column and row positions in font strings.
    InstallFont  Installs a new font to the system.
    RemoveFont  Removes an installed font from the system.
    SelectFont  Searches for a 'best fitting' font file based on select criteria.

    Structure

    The Font object consists of the following public fields:

    Align  Sets the position of a font string to an abstract alignment.
    Bitmap  The destination Bitmap to use when drawing a font.
    Bold  Set to TRUE to enable bold styling.
    Colour  String-based field for defining the colour of a font.
    ColourRGB  The base colour of a font.
    Face  The name of a font face that is to be loaded on initialisation.
    Flags  Optional flags.
    GlyphSpacing  The amount of spacing between each character.
    Height  The full height of a font (distance between font lines).
    LineCount  The amount of lines in a font String.
    LineSpacing  The amount of spacing between each line.
    Opacity  Determines the level of translucency applied to a font.
    Outline  String-based field for defining the outline colour of a font.
    OutlineRGB  The colour of a font's outline.
    Point  The point size of a font.
    String  The string to use when drawing a Font.
    Style  Determines font styling.
    TabSize  Defines the tab size to use when drawing and manipulating a font string.
    TotalFonts  Reflects the total number of fonts installed in the system.
    Underline  String-based field for defining the underlining colour of a font.
    UnderlineRGB  Defines the colour to use when underlining a font.
    Width  Returns the pixel width of a string.
    XCoord  The horizontal coordinate of a font's string.
    YCoord  The vertical coordinate of a font's string.
    YOffset  Additional offset value that is added to vertically aligned fonts.
    Action:Draw
    Short:Draws a font to a Bitmap.

    When you are ready to draw a font to a Bitmap, use the Draw action. Drawing will start from the coordinates given in the XCoord and YCoord fields, using the characters in the font String. The result of calling Draw will depend on what type of Font you are using and how you have set up the font object.

    Result
    ERR_Okay  The font graphic was drawn successfully.
    ERR_FieldNotSet  The Bitmap and/or String field has not been set.

    Action:Refresh
    Short:Refreshes the system font list with up-to-date font information.

    The RefreshFonts() function is used to scan for fonts that have been installed in the system, for the purpose of detecting deleted and recently installed font files. Ideally this function should not be necessary when the InstallFont() and RemoveFont() methods are used correctly, however it can be useful when font files have been manually deleted or added to the system.

    Refreshing fonts can take an extensive amount of time as each font file needs to be completely analysed for information. Once the analysis is complete, the "SystemFonts" object will be updated and the "fonts:registry.cfg" file will reflect current font settings.

    Result
    ERR_Okay  Fonts were successfully refreshed.
    ERR_AccessObject  Access to the SytsemFonts object was denied, or the object does not exist.

    Method:CalcStringWidth()
    Short:Returns the pixel width of any given string in relation to a font's settings.
    Arguments:
    STRING String  The string to be calculated.
    LONG Length  The number of characters (give consideration to UTF-8 formatting) to be used in calculating the string length, or -1 if you want the entire string to be used.
    LONG Width  The calculated width will be stored in this parameter before returning.

    This method calculates the pixel width of any string in relation to a font's object definition. The routine takes into account any line feeds that might be specified in the String, so if the String contains 8 lines, then the width of the longest line will be returned.

    Word wrapping will not be taken into account from the font, even if it has been enabled in the object.

    Result
    ERR_Okay  The width was successfully calculated.
    ERR_Args  Invalid arguments were specified.
    ERR_ObjectCorrupt  The font object structure is corrupt.

    Method:ConvertFontCoords()
    Short:Converts pixel coordinates into equivalent column and row positions in font strings.
    Arguments:
    STRING String  Must point to the string that you will be inspecting, or NULL if you want to inspect the string currently in the font's String field.
    LONG XCoord  The horizontal coordinate that you want to translate into a column position.
    LONG YCoord  The vertical coordinate that you want to translate into a row position.
    LONG Column  This parameter will be updated to reflect the calculated character position, with consideration to the UTF-8 standard.
    LONG Row  This parameter will be updated to reflect the calculated row position.
    LONG ByteColumn  This parameter will be updated to reflect the absolute column byte position within the given row.
    LONG BytePosition  This parameter will be updated to reflect the absolute byte position with the font String.

    This method is used to convert pixel coordinates within a font String into the equivalent Row and Column character positions. If the coordinate values that you supply are in excess of the String dimensions, the Column and Row results will be automatically restricted to their maximum value. For instance, if the YCoord argument is set to 280 and the String consists of 15 rows amounting to 150 pixels in height, the Row value will be returned as 15.

    Negative coordinate values are not permitted.

    Result
    ERR_Okay  The character position was calculated.
    ERR_Args  Invalid arguments were specified.
    ERR_FieldNotSet  The String field has not been set.

    Method:InstallFont()
    Short:Installs a new font to the system.
    Arguments:
    STRING Files  A list of the font files that are to be installed must be specified here. If there is more than one data file, separate each file name with a semi-colon.

    The InstallFont() function is used to install new fonts on a system running the Pandora Engine. While it is possible for users to download new font files and install them by hand, this is a process that is too difficult for novices and is open to mistakes on the part of the user. By using a program that uses the InstallFont() function, the installation process can take place automatically.

    To install a new font, you only need to know the location of the font file(s). The rest of the information about the font will be derived after an analysis of the data.

    Once this function is called, the data files will be copied into the correct sub-directory and the font registration files will be updated to reflect the presence of the new font. The font will be available immediately thereafter, so there is no need to reset the system to acknowledge the presence of the font.

    Result
    ERR_Okay  The font information was successfully installed.
    ERR_ExclusiveDenied  Access to the SystemFonts object was denied.
    ERR_Args  Invalid arguments were detected.
    ERR_NoSupport  One of the font files is in an unsupported file format.

    Method:RemoveFont()
    Short:Removes an installed font from the system.
    Arguments:
    STRING Name  The name of the font face that you want to delete.

    This function is designed to remove fonts that have been installed on a Pandora Engine system. All you need to do is provide the Name (face) of the font and it will be removed if it exists. Once a font has been removed, the data is permanently destroyed and it cannot be recovered.

    Result
    ERR_Okay  The font was succesfully removed.
    ERR_Args  Invalid arguments were specified.

    Field:Align
    Short:Sets the position of a font string to an abstract alignment.
    Type:LONG
    Prefix:ALIGN
    Status:Set

    You can use this field to set the alignment of a font within its drawable area. This is an abstract means of positioning in comparison to setting the XCoord and YCoord fields directly. Available alignment flags are listed in the following table:

    FlagDescription
    BOTTOMAligns the font to the bottom of the drawable area.
    CENTERCenters the font on both the vertical and horizontal axis.
    LEFTAligns the font to the left (horizontal coordinate 0).
    MIDDLESynonym for the CENTER flag.
    RIGHTAligns the font so that the last character is positioned flush against the right.
    TOPAligns the font to the top (vertical coordinate 0).
    HORIZONTALCenters the font on the horizontal axis.
    VERTICALCenters the font on the vertical axis.

    Field:Bitmap
    Short:The destination Bitmap to use when drawing a font.
    Type:struct Bitmap *
    Status:Read/Set

    Before calling the Draw action on a font object, the Bitmap field must be set so that the font has a graphical destination. This field is dynamic, so a font does not have to be anchored to a Bitmap after initialisation (i.e. you can use a single font object to draw to as many different Bitmap types as you please).


    Field:Bold
    Short:Set to TRUE to enable bold styling.
    Type:LONG
    Status:Get/Init

    You may set the Bold field to TRUE prior to initialisation if you would like a font to use bold styling. This field is provided only for convenience - we recommend that you set the Style field for determining font styling where possible.


    Field:Colour
    Short:String-based field for defining the colour of a font.
    Type:STRING
    Status:Set

    The colour of a font can be declared by writing to this field. The colour must be in hexadecimal or separated-decimal format - for example to create a pure red colour, a setting of "#ff0000" or "255,0,0" would be valid.

    If you create a font object without setting the Colour field, the text will be printed in black.


    Field:ColourRGB
    Short:The base colour of a font.
    Type:RGB
    Status:Read/Set

    The base RGB colour of a Font is defined in this field. If the colour is not set then the Font will be drawn in black text.


    Field:Face
    Short:The name of a font face that is to be loaded on initialisation.
    Type:STRING
    Status:Read/Init

    The name of the face that you wish to use for a font must be specified here. If this field is not set then the initialisation process will use the user's preferred face. A list of available faces can be obtained from the 'SystemFonts' public object.

    For convenience, the face string can also be extended with extra parameters so that you can define point size and style information at the same time when writing this field. Extra parameters are delimited with the colon character and must follow a set order as defined here:

       face:pointsize:style:colour
    

    Here are some examples:

      Helvetica:12:Bold Italic:#ff0000
      Courier:10
      Charter:16::255,128,255
    

    To load a font file that is not installed by default, replace the face parameter with the SRC command, followed by the font location:

      SRC:exodus:data/images/shine:14:Italic
    

    Field:Flags
    Short:Optional flags.
    Type:LONG
    Prefix:FTF
    Status:Read/Init

    This field contains flags that affect font behaviour. Currently available flags are:

    FlagDescription
    ANTIALIASSmooths text with an anti-alias technique. Anti-aliasing is forced automatically when scalable fonts are used. This flag has no purpose when using fixed bitmap fonts.
    BOLDIndicates that bold text is enabled for the font (read only).
    HEAVYLINEEnables font underlining at twice the normal amount, using the colour in the UnderlineRGB field.
    ITALICSIndicates that italic text is enabled for the font (read only).
    OUTLINEEnables font outlines using the colour in the OutlineRGB field. Only works with bitmap fonts.
    UNDERLINEEnables font underlining using the colour in the UnderlineRGB field.
    UPDATEXYIf this field is set then the XCoord and YCoord fields will be increase to the next cursor position after a successful Draw action.
    WORDWRAPWraps text back to the value given in a font's XCoord every time the edge of the drawing area is reached.

    Field:GlyphSpacing
    Short:The amount of spacing between each character.
    Type:LONG
    Status:Read/Write

    This field represents the horizontal spacing between each glyph, technically known as kerning between each font character. Fonts that have a high GlyphSpacing value will typically print out like this:

         H e l l o   W o r l d !
    

    On the other hand, using negative values in this field can cause text to be printed backwards. The GlyphSpacing value is typically set to zero or one by default, depending on the font type that has been loaded.


    Field:Height
    Short:The full height of a font (distance between font lines).
    Type:LONG
    Status:Read

    The height of a font object is defined in this field and describes the distance between individual font lines (measured in pixels). The font height is calculated on initialisation and can be read at any time.


    Field:LineCount
    Short:The amount of lines in a font String.
    Type:LONG
    Status:Read

    You can read this field if you need to know how many lines are present in a font's String field. This figure does not include lines that may result from column wrapping, i.e. only specific line feeds are recognised.


    Field:LineSpacing
    Short:The amount of spacing between each line.
    Type:LONG
    Status:Read/Write

    This field defines the amount of space between each line that is printed with a font object. It is set automatically during initialisation to reflect the recommended distance between each line. You can increase or decrease this value to make finer adjustments to the line spacing. If negative, the text will be printed in a reverse vertical direction with each new line.

    If you set this field prior to initialisation, the value that you set will be added to the font's normal line-spacing, instead of over-riding it. For instance, setting the LineSpacing to 2 will result in an extra 2 pixels being added to the font's spacing.


    Field:Opacity
    Synonyms:Translucency
    Short:Determines the level of translucency applied to a font.
    Type:FLOAT
    Status:Get/Set

    This field determines the translucency level of a font graphic. The default setting is 100%, which means that the font will not be translucent. Any other value that you set here will alter the impact of a font's graphic over the destination Bitmap. High values will retain the boldness of the font, while low values can render it close to invisible.

    Please note that the use of translucency will always have an impact on the time it normally takes to draw a font.


    Field:Outline
    Short:String-based field for defining the outline colour of a font.
    Type:STRING
    Status:Set

    If you want to use font outlining, you need to set either the Outline or OutlineRGB field so that the font object knows what colour to use for the outline. When writing to this field, the colour must be declared in hexadecimal or separated-decimal format. For example to create a pure red colour, a setting of "#ff0000" or "255,0,0" would be valid.


    Field:OutlineRGB
    Short:The colour of a font's outline.
    Type:RGB
    Status:Set

    If you have used the OUTLINE Flag then you may want to set the OutlineRGB field if you would like an outline colour other than black.


    Field:Point
    Short:The point size of a font.
    Type:LONG
    Status:Read/Set

    The point size of a font defines the size of a font relative to other point sizes for a particular font face. For example, Arial point 8 is half the size of Arial point 16. The point size between font families cannot be compared accurately due to designer discretion when it comes to determining font size. For accurate point size in terms of pixels, please refer to the Height field.

    When setting the point size of a bitmap font, the system will try and find the closest matching value for the requested point size. For instance, if you request a fixed font at point 11 and the closest size is point 8, the system will drop the font to point 8. This does not impact upon scalable fonts, which can be measured to any point size.


    Field:String
    Short:The string to use when drawing a Font.
    Type:STRING
    Status:Read/Set

    This field is used when you want to use the Draw action to draw a string to a drawable area. A string may consist of any characters that you like and line feeds are allowed (whenever a line feed is reached, the Draw action will start printing on the next line). Drawing will stop when the null termination character is reached.

    If a string contains characters that are not supported by a font, those characters will be printed using simply be ignored when printing.


    Field:Style
    Short:Determines font styling.
    Type:STRING
    Status:Read/Init

    The style of a font can be selected by setting the Style field. This comes into effect only if the font actually supports the specified style as part of its graphics set. If the style is unsupported, the regular styling of the face will be used on initialisation.

    Bitmap fonts are a special case if a bold or italic style is selected. In this situation the system can automatically convert the font to that style even if the correct graphics set does not exist.

    Typical font styles are "Bold", "Bold Italic", "Italic" and "Regular" (the default). TrueType fonts can consist of any style that the designer chooses, such as "Narrow" or "Wide", so check the SystemFonts object if you need to analyse available styles.


    Field:TabSize
    Short:Defines the tab size to use when drawing and manipulating a font string.
    Type:LONG
    Status:Read/Write

    You can set the TabSize of a font to alter the standard tab setting. The default tab size is 8, so if you consider this to be too large, then you may want to shrink it. The TabSize only comes into effect when tabs are used in the font String.


    Field:TotalFonts
    Short:Reflects the total number of fonts installed in the system.
    Type:LONG
    Status:Get

    Field:Underline
    Short:String-based field for defining the underlining colour of a font.
    Type:STRING
    Status:Set

    If you want to underline a font graphic, you need to set either the Underline or UnderlineRGB field so that the font object knows what colour to use for the underline. When writing to this field, the colour must be declared in hexadecimal or separated-decimal format. For example to create a pure red colour, a setting of "#ff0000" or "255,0,0" would be valid.


    Field:UnderlineRGB
    Short:Defines the colour to use when underlining a font.
    Type:*RGB
    Status:Read/Set

    If a font has the underline mode turned on, you can specify the colour of the line here. If a colour is not specified here then a black line will be used.


    Field:Width
    Short:Returns the pixel width of a string.
    Type:LONG
    Status:Get

    You can read this virtual field to obtain the pixel width of a font string. You must have a string already specified in the font for this to work, or a width of zero will be returned.


    Field:XCoord
    Short:The horizontal coordinate of a font's string.
    Type:LONG
    Status:Read/Write

    When drawing font strings, the XCoord and YCoord fields define the position that the string will placed at within its drawable container. If you do not initialise the coordinates then printing will always start from the top left of the drawing area.


    Field:YCoord
    Short:The vertical coordinate of a font's string.
    Type:LONG
    Status:Read/Write

    When drawing font strings, the XCoord and YCoord fields define the position that the string will placed at within its drawable container. If you do not initialise the coordinates then printing will always start from the top left of the drawing area.


    Field:YOffset
    Short:Additional offset value that is added to vertically aligned fonts.
    Type:LONG
    Status:Get

    Fonts that are aligned vertically (either in the center or bottom edge of the drawing area) will have a vertical offset value. You can read that value from this field and add it to the YCoord field in order to get a more accurate reading when determining where a font will be drawn.