Class Documentation
Font |
2.0 |
ID_FONT |
Unspecified |
Graphics |
graphics/font.h |
July 2001 |
Rocklyte Systems |
Rocklyte Systems, 1998-2001. All rights reserved. |
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. |
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. |
ERR_ExclusiveDenied | Access to the internal Picture object was denied. |
|
|
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 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.
ERR_Okay | The width was successfully calculated. |
ERR_Args | Invalid arguments were specified. |
ERR_ObjectCorrupt | The Font object's structure is corrupt. |
|
|
ConvertFontCoords() [V2] |
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 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.
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:
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: | 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:
ANTIALIAS | Smooths text with an anti-alias technique. Can slow down drawing considerably and only works on certain font types. |
BOLD | Turns on bold text. |
HEAVYLINE | Enables font underlining at twice the normal amount, using the colour in the UnderlineRGB field. |
HEAVYITALICS | Turns on italics at a sharp 45 degree angle. |
ITALICS | Turns on italics at a 22.5 degree angle. |
OUTLINE | Enables font outlines using the colour in the OutlineRGB field. |
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. |
WRAP | Wraps 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.
|
|