Class Documentation
Font |
2.0 |
ID_FONT |
Unspecified |
Graphics |
pandora/graphics/font.h |
April 2003 |
Rocklyte Systems, some portions based on the FreeType Project. |
Rocklyte Systems, 1998-2003. All rights reserved. |
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. |
Draw |
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.
ERR_Okay | The font graphic was drawn successfully. |
ERR_FieldNotSet | The Bitmap and/or String field has not been set. |
|
|
Refresh |
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.
ERR_Okay | Fonts were successfully refreshed. |
ERR_AccessObject | Access to the SytsemFonts object was denied, or the object does not exist. |
|
|
CalcStringWidth() |
Returns the pixel width of any given string in relation to a font's settings. |
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.
ERR_Okay | The width was successfully calculated. |
ERR_Args | Invalid arguments were specified. |
ERR_ObjectCorrupt | The font object structure is corrupt. |
|
|
ConvertFontCoords() |
Converts pixel coordinates into equivalent column and row positions in font strings. |
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.
ERR_Okay | The character position was calculated. |
ERR_Args | Invalid arguments were specified. |
ERR_FieldNotSet | The String field has not been set. |
|
|
InstallFont() |
Installs a new font to the system. |
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.
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. |
|
|
RemoveFont() |
Removes an installed font from the system. |
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.
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:
BOTTOM | Aligns the font to the bottom of the drawable area. |
CENTER | Centers the font on both the vertical and horizontal axis. |
LEFT | Aligns the font to the left (horizontal coordinate 0). |
MIDDLE | Synonym for the CENTER flag. |
RIGHT | Aligns the font so that the last character is positioned flush against the right. |
TOP | Aligns the font to the top (vertical coordinate 0). |
HORIZONTAL | Centers the font on the horizontal axis. |
VERTICAL | Centers 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:
ANTIALIAS | Smooths 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. |
BOLD | Indicates that bold text is enabled for the font (read only). |
HEAVYLINE | Enables font underlining at twice the normal amount, using the colour in the UnderlineRGB field. |
ITALICS | Indicates that italic text is enabled for the font (read only). |
OUTLINE | Enables font outlines using the colour in the OutlineRGB field. Only works with bitmap fonts. |
UNDERLINE | Enables font underlining using the colour in the UnderlineRGB field. |
UPDATEXY | If this field is set then the XCoord and YCoord fields will be increase to the next cursor position after a successful Draw action. |
WORDWRAP | Wraps 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.
|
|