Class Documentation

Name:Font
Version:2.0
ID:ID_FONT
Status:Unspecified
Category:Graphics
Include:graphics/font.h
Date:July 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 1998-2001. All rights reserved.
Short:  Draws text in different type faces and styles.



Description

The Font class is provided for the purpose of drawing strings to Bitmap areas. It supports standard effects such as bold, italics and underlining, along with extra features such as adjustable horizontal and vertical spacing. Font data files are loaded from the "fonts:" directory and are grouped within the configuration file "fonts:registry.cfg". Initialisation of a new Font is as simple as declaring its Point size and Face. Available faces can be read from the "fonts:registry.cfg" file, or your program can read faces dynamically from the 'SystemFonts' public object.

For your benefit, here is some clarification on some of the terminology used in the Font class:

  • 'Point' determines the height of the line that a Font is printed on.
  • 'Gutter' determines the space between each line. Letters like g, y, j and others that have 'tails' can enter the gutter space.
  • 'Height' represents the Point + Gutter, i.e. the true height of a Font.
  • Drawing strings to a Bitmap is as simple as using the Draw action. It is necessary to set the Font String field so that you actually have something to print, and the XCoord and YCoord fields so that the String is correctly positioned. You can also use the Align field to align a string to the right or center of the drawable area.

    Actions

    The Font class supports the following actions:

    Draw  Draws a Font to a Bitmap.

    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.

    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.
    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.
    Gutter  The size of a Font's vertical gutter space.
    HSpacing  The amount of spacing between each character.
    Height  The full height of a Font.
    LineCount  The amount of lines in a Font String.
    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.
    TabSize  Defines the tab size to use when drawing and manipulating a Font string.
    Translucency  Alters the translucency of a Font.
    Underline  String-based field for defining the underlining colour of a Font.
    UnderlineRGB  Defines the colour to use when underlining a Font.
    VSpacing  The amount of spacing between each line
    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.
    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.
    ERR_ExclusiveDenied  Access to the internal Picture object was denied.

     

    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 length of the string, or -1 if you want the length to be calculated.
    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.

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

     

    Method:ConvertFontCoords() [V2]
    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 column position.
    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.

     

    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: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:Get/Set

    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.

     

    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. Can slow down drawing considerably and only works on certain font types.
    BOLDTurns on bold text.
    HEAVYLINEEnables font underlining at twice the normal amount, using the colour in the UnderlineRGB field.
    HEAVYITALICSTurns on italics at a sharp 45 degree angle.
    ITALICSTurns on italics at a 22.5 degree angle.
    OUTLINEEnables font outlines using the colour in the OutlineRGB field.
    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.
    WRAPWraps text back to the value given in Font XCoord every time the edge of the drawing area is reached.

     

    Field:Gutter
    Short:The size of a Font's vertical gutter space.
    Type:LONG
    Status:Read

    The gutter is the amount of space available for the 'tails' on certain characters. For example g, y, p, q and j all have tails that extend below the font line. Certain symbols such as commas and semi-colons may also enter the gutter space. The value of the Gutter field is determined by the data file that a Font originates from - you cannot write to the Gutter field from your program.

     

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

    This field represents the horizontal spacing between each Font character. Fonts that have a high HSpacing 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. Generally the HSpacing value should be set to a figure between 1 and 3.

     

    Field:Height
    Short:The full height of a Font.
    Type:LONG
    Status:Read

    The full Height of a Font is defined by a calculation of "Height = Point + Gutter". The height of a Font 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: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 how many pixels make up the line that a Font is printed on. If you were to measure the lines printed on a log book for example, the point size is the distance between two ruled lines on the page. You can specify the Point size on initialisation to have a font graphic loaded to that size. For certain font types the exact point size may not be achievable, in which case the initialisation process will find the best matching 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 simply be ignored when printing.

     

    Field:TabSize [V2]
    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 and have a character value of 9.

     

    Field:Translucency
    Short:Alters the translucency of a Font.
    Type:FLOAT
    Status:Get/Set

    This field determines the translucency level of a Font graphic. The default setting is 0%, which means that a 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. Low values will retain the boldness of the Font, while higher 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: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:VSpacing
    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. Generally this field should be set between a range of 1 to 6. It is possible to specify negative values in this field, which if high enough will cause text to be printed 'upwards' every time that a line feed or column wrap is encountered when drawing a Font.

     

    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 String 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.