RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

The Font Manager


Introduction

A font is a set of characters of a given type style. The Font Manager provides facilities for painting characters of various sizes and styles on the screen.

To allow characters to be printed in any size, descriptions of fonts can be held in files as size-independent outlines, or pre-computed at specific sizes. The Font Manager allows programs to request font types and sizes by name, without worrying about how they are read from the filing system or stored in memory.

The Font Manager also scales fonts to the desired size automatically if the exact size is not available. The fonts are, in general, proportionally spaced, and there are facilities to print justified text - that is, adjusting spaces between words to fit the text in a specified width.

An anti-aliasing technique can be used to print the characters. This technique uses up to 16 shades of colour to represent pixels that should only be partially filled-in. Thus, the illusion is given of greater screen resolution.

The Font Manager can use hints, which help it scale fonts to a low resolution while retaining maximum legibility.

RISC OS 2

References in this chapter to the RISC OS 2 Font Manager describe the outline Font Manager that is supplied with Release 1.02 of Acorn Desktop Publisher. The RISC OS 2 ROM contains an earlier version of this Font Manager called the bitmap Font Manager. This is no longer supported, and you should always use the outline Font Manager.

Overview

The Font Manager can be divided internally into the following components:

  • Find and read font files
  • Cache font data in memory to speed painting
  • Get a handle for a font style (many commands use this handle)
  • Paint a string to the VDU memory
  • Change the colours that the text is painted in
  • Other assorted SWIs to handle scaling and measurements.

Measurement systems

Much of the Font Manager deals with an internal measurement system, using millipoints. This is 1/1000th of a point, or 1/72000th of an inch. This system is an abstraction from the physical characteristics of the VDU. Text can therefore be manipulated by its size, rather than in terms of numbers of pixels, which will vary from mode to mode.

OS coordinates

The Font Manager also uses OS coordinates as a measurement system. There are defined to be 180 OS units per inch. This is the coordinate system used by the VDU drivers, and is related to the physical pixel layout of the screen. Calls are provided to convert between these two systems, and even change the scaling factor between them.

Referencing fonts by name

A SWI is provided to scan through the list of available fonts. This allows a program to present the user with a list to select from. The list is cached and so is fast to access - except under RISC OS 2, where it's consequently a slow process to get the font list unless you cache it yourself, which we recommend.

Another SWI will return a handle for a given font style. A handle is a number that the Font Manager uses as an internal reference for the font style. This is like an Open command in a filing system. The equivalent of Close is also provided. This tells the Font Manager that the program has finished with the font.

There is a SWI to make a handle the currently selected one. This will be used implicitly by many calls in the Font Manager. It can be changed by commands within a string while painting to the VDU.

Cacheing

Cacheing is the technique of storing one or more fonts in a designated space in memory. The cacheing system decides what gets kept or discarded from its space. Two CMOS variables control how much space is used for cacheing. One sets the minimum amount, which no other part of the system will use. The other sets a threshold beyond which the Font Manager will discard as much cached information as possible in an endeavour not to let the cache grow. However, if many more fonts are in use than are reasonable for the configured threshold, the Font Manager may be forced to let the cache grow past this point.

You should adjust these settings to suit the font requirements of your application. If too little is allowed, then the system will have to continually re-load the fonts from file, which considerably slows response. If it is too large, then you will use up memory that could be used for other things.

The command *FontList is provided to show the total and used space in the cache, and what fonts are held in it. This is useful to check how the cache is occupied.

Colours

The anti-aliasing system uses up to 16 colours, depending on the screen mode. It will try, as intelligently as possible, to use these colours to shade a character giving the illusion of greater resolution.

Logical colours

The colour shades start with a background value, which is usually the colour that the character is painted onto. They progress up to a foreground colour, which is the desired colour for the character to appear in. This is usually what appears in the centre of the character. Both of these can be set to any valid logical colour numbers.

Palette

In between background and foreground colours can be a number of other logical colours. There is a call to program the palette so that these are set to graduating intermediate levels. The points of transition are called thresholds. The thresholds are set up so that the gradations produce a smooth colour change from background to foreground.

For screen modes with more than 16 colours, this sets up a 'pseudo palette' that indirects into the real palette.

Painting

A string can be painted into the VDU memory. As well as printable characters which are displayed in the current font style, there are non-printing control sequences, used in much the same way as those in the VDU driver. They can perform many operations, such as:

  • changing the colour
  • altering the write position in the x and y axes
  • changing the font handle
  • changing the appearance and position of the underlining.

By using these control sequences, a single string can be displayed with as many changes of these characteristics as required.

Measuring

Many SWIs exist to measure various attributes of fonts and strings. With a font, you can determine the smallest box which is large enough to contain any character in the set. This is called the font bounding box. You can also check the bounding box of an individual character.

With a string, you can measure its bounding box, or check where in the string the caret would be for a given coordinate. The caret is a special cursor used with fonts. It is usually displayed as a vertical bar with loops on each end.

VDU calls

A number of Font Manager operations can be performed through VDU commands. These have been kept for compatibility and you should not use them, as they may be phased out in future versions.

Technical Details

An easy way to introduce you to programming with the Font Manager is to use a simple example. It shows how to paint a text string on the screen using Font Manager SWIs. Further on in this section is a more detailed explanation of these and all other font SWIs.

Here is the sequence that you would use:

  • Font_FindFont - to 'open' the font in the size required
  • Font_SetFont - to make it the currently selected font and size
  • Font_SetPalette - to set the range of colours to use
  • Font_Paint - to paint the string on the screen
  • Font_LoseFont - to 'close' the font.

Measurement systems

Internal coordinates

The description of character and font sizes comes from specialist files called metrics files. The numbers in these files are held in units of 1/1000th of an em. An em is the size of a point multiplied by the point size of the font. For example, in a 10 point font, an em is 10 points, while in a 14 point font it is 14 points. The Font Manager converts 1000ths of ems into 1000ths of points, or millipoints, to use for its internal coordinate system. A millipoint is equal to 1/72000th of an inch. This has the advantage that rounding errors are minimal, since coordinates are only converted for the screen at the last moment. It also adds a level of abstraction from the physical characteristics of the target screen mode.

OS coordinates

Unfortunately, the coordinates provided for plot calls are only 16 bits, so this would mean that text could only be printed in an area of about 6/7ths of an inch.

Therefore, the font painter takes its initial coordinates from the user in the same coordinates as the screen uses, which are known as OS units. To make the conversion from OS units to points, the font painter assumes by default that there are 180 OS units to the inch. You can read and set this scale factor, which you may find useful to accurately calibrate the on screen fonts, or to build high resolution bitmaps.

Internal resolution

When the font painter moves the graphics point after printing a character, it does this internally to a resolution of millipoints, to minimise the effect of cumulative errors. The font painter also provides a justification facility, to save you the trouble of working the positions out yourself. The application can obtain the widths of characters to a resolution of millipoints.

SWIs

A pair of routines can be used to convert to and from internal millipoint coordinates to the external OS coordinates. Font_ConverttoOS will go from millipoints, while Font_Converttopoints will go to them.

Scaling factor

The scaling factor that the above SWIs (and many others in the Font Manager) use can be read with Font_ReadScaleFactor. You can also set this with Font_SetScaleFactor, although we recommend that you don't do so under the desktop, as other applications may assume the default. If you must alter this value, you should at the very least restore it before polling the Wimp.

Font files

The font files relating to a font are all held in a single directory structure consisting of one or more font subdirectories (for different weights and styles/angles) and one or more encoding subdirectories. All Acorn font names should conform to:

fontname.[weight.[style]]

The weight element can only be omitted if there is no style element either, eg for a Symbol font.

Files held within this structure are:

Filename Contents
IntMetrics metrics information for default encoding
IntMetric0 metrics information for encoding /Base0
IntMetricn metrics information for encoding to /Basen
encoding.x90y45 old format pixel file (4-bits-per-pixel) for encoding
encoding.f9999x9999 new format pixel file (4-bits-per-pixel) for encoding
encoding.b9999x9999 new format pixel file (1-bits-per-pixel) for encoding
Outlines outline file for default encoding
Outlines 0 outline file for encoding /Base0
Outlines n outline file for encoding to /Basen
Messagesn mapping of font identifiers to names for country n

The '9999's referred to above mean 'any decimal number in the range 1 - 9999'. They refer to the pixel size of the font contained within the file, which is equal to:

(font size in 1/16ths of a point) × dots per inch / 72

so, for example, a file containing 4-bits-per-pixel 12 point text at 90 dots per inch would be called f240x240, because 12 × 16 × 90 / 72 = 240.

The formats of these files are detailed in Appendix E: File formats on Draw files.

The default encoding for an alphabetic font (as opposed to symbol fonts, which have a fixed encoding) depends on the alphabet number of the current encoding. The encoding /Base0 includes all the characters supplied with a font; for an example of it, and of the Latin... encodings, see the file:

Resources:$.Fonts.Encodings

For details of the different RISC OS character sets, see Table D: Character sets.

The minimal requirement for a font is that it should contain an IntMetrics file, and an Outlines file (which we strongly urge you to include) or an x90y45 file. In addition, it can have any number of f9999x9999 or b9999x9999 files, to speed up the cacheing of common sizes.

Master and slave fonts

If outline data or scaled 4-bpp data is to be used as the source of font data it is first loaded into a 'master' font in the cache, which can be shared between many 'slave' fonts at various sizes. There can be only one master font for a given font identifier, regardless of size, whereas each size of font requires a separate slave font. If the data is loaded directly from a bitmap file into the slave font, the master font is not required.

Font names and identifiers

Font identifiers are the names of font subdirectories, and are used for all programmer's interfaces to the Font Manager, such as SWIs. They are constant across all countries. Font names are the local form of a font identifier for a particular country, and are used for all user interfaces to the Font Manager, such as menus.

Messages files

Font names are obtained by looking in the file Fontprefix.Messagescountryno, using the font identifier as a key. For example, a UK Messages file would be named Messages1. This allows internationalisation by having an extra level of indirection between font identifiers and font names. The file Fontprefix.Messages is used as a default if the country-specific file is not present.

The Font Manager only actually scans the font directory if no Messages file can be found. Of course, reading a Messages file is much faster than scanning the font directory.

Messages files allow font paths to become much more effective, since new font directories can be added to the list of known fonts without losing references to other font directories. This and the fact that the Font Manager knows exactly where each font is held makes it possible for a user to put fonts on several floppy discs and still use them effectively. Messages files also allow you to set the default font in a family (eg selecting just 'Trinity' in a font menu can be made to select 'Trinity.Medium', rather than just the first entry in the sub-menu).

Details of the format of Messages files are in Appendix E: File formats on Draw files - just as for all other font file formats.

Referencing fonts by identifier

The Font Manager uses the path variable Font$Path when it searches for fonts. This contains a list of full pathnames - each of which has (as in all ...$Path variables) a trailing '.' - which are, in turn, placed before the requested font identifier. The Font Manager uses the first directory that matches, provided it also contains an IntMetrics file. Because the variable is a list of path names, you can keep separate libraries of fonts.

Early versions of the Font Manager used the variable Font$Prefix to specify a single font directory. For compatibility, the Font Manager looks when it is initialised to see if Font$Path has been defined - if not, it initialises it as follows:

*SetMacro Font$Path <Font$Prefix>.

This ensures that the old Font$Prefix directory is searched if you haven't explicitly set up the Font Manager to look elsewhere. The trailing '.' is needed, as Font$Prefix does not include one, and Font$Path requires one.

*FontCat will list all the fonts that can be found using Font$Path.

Changing the font path

Applications which allow the user access to fonts should call Font_ListFonts repeatedly to discover the list of fonts available. This is normally done when the program starts up. The same call can be used with different parameters to build a menu of available fonts (but not under RISC OS 2).

The commands *FontInstall, *FontRemove and *FontLibrary add directories to Font$Path, or remove them. Service_FontsChanged is then issued to notify module-based applications that they should update their list of available fonts by calling Font_ListFonts again. These commands are not available under RISC OS 2, but where possible, you should use them. (Non module-based applications must call Font_ListFonts each time they require a list of available fonts, as they have no way of knowing when the list has changed.)

RISC OS 2

Under RISC OS 2 families of fonts are often found in a separate font 'application' directory, the !Run file of which RMEnsures the correct Font Manager module from within itself, and then either adds itself to Font$Path or resets Font$Path and Font$Prefix so that it is the only directory referenced.

In order to ensure that the user can access the new fonts available, applications running under RISC OS 2 should check whether the value of Font$Path or Font$Prefix has changed since the list of fonts was last cached, and recache the list if so. A BASIC program could accomplish this as follows:

size% = &200
DIM buffer% size%        : REM this could be a scratch buffer
...
SYS "OS_GSTrans","<Font$Prefix> and <Font$Path>",buffer%,size%-1 TO ,,length%
buffer%?length% = 13    :REM ensure there is a terminator (13 for BASIC)
IF $buffer%<>oldfontpath$ THEN
   oldfontpath$ = $buffer%
   PROCcache_list_of_fonts
ENDIF

Note that if the buffer overflows the string is simply truncated, so it is possible that the check may miss some changes to Font$Prefix. However, since new elements are normally added to the front of Font$Path, this will probably not matter.

The application could scan the list of fonts when it started up, remembering the value of Font$Path and Font$Prefix in oldfontpath$, and then make the check described above just before the menu tree containing the list of fonts was about to be opened.

Alternatively the application could scan the list of fonts only when required, by setting oldfontpath$="" when it started up, and checking for Font$Path changing only when the font submenu is about to be opened (using the Message_MenuWarning message protocol).

Opening and closing a font

In order to use a font, Font_FindFont must be used. This returns a handle for the font, and can be considered conceptually like a file open. In order to close it, Font_LoseFont must be used.

Handles

Font_ReadDefn will read the description of a handle, as it was created with Font_FindFont.

In order for a handle to be used, it should be set as the current handle with Font_SetFont. This setting stays until changed by another call to this function, or while painting, by a character command to change the handle.

Font_CurrentFont will tell you what the handle of the currently selected font is.

Cacheing

Setting cache size

The size of the cache can be set with two commands. *Configure FontSize sets the minimum that will be reserved. This allocation is protected by RISC OS and will not be used for any other purpose. Running the Task Display from the desktop and sliding the bar for font cache will change this setting until the next reset.

Above this amount, *Configure FontMax sets a maximum amount of memory for font cacheing. The Font Manager will endeavour not to use more than this, but may have to should there be many more fonts in use than are reasonable for the configured FontMax.

The difference between FontSize and FontMax is taken from unallocated free memory as required to accommodate fonts currently in use. If other parts of the system have used up all this memory, then fonts will be limited to FontSize. If there is plenty of free unallocated memory, then FontMax will stop font requirements from filling up the system with cached fonts.

Cache size

*FontList will generate a list of the size and free space of the cache, as well as a list of the fonts currently cached. Font_CacheAddr can be used in a program to get the cache size and free space.

Font_LoseFont

When a program calls Font_LoseFont, the font may not be discarded from memory. The cacheing system decides when to do this. A usage count is kept, so that it knows when no task is currently using it. An 'age' is also kept, so that the Font Manager knows when it hasn't been used for some time.

Cache formats

The cache format, and the algorithms used for cacheing characters, change from release to release. You must not directly access the cache.

Saving and loading the cache

You can use the commands *SaveFontCache to save the font cache in a known state. You can then use *LoadFontCache to reload it later, but there are restrictions when doing so:

  • The cache must not contain any claimed fonts (ie ones that are in use).
  • The format of the loaded cache must be understood by the Font Manager loading the cache. In practice this generally means that the cache must have been saved by the same version of the Font Manager as is loading it.

Using saved font caches can be a useful speed-up for your applications.

Colours

Colour selection with the Font Manager involves the range of logical colours that are used by the anti-aliasing software and the physical colours that are displayed.

Logical colours

The logical colour range required is set by Font_SetFontColours. This sets the background colour, the foreground colour and the range of colours in between.

Physical colours

Font_SetPalette duplicates what Font_SetFontColours does, and uses two extra parameters. These specify the foreground and background physical colours, using 4096 colour resolution. Given a range of logical colours and the physical colours for the start and finish of them, this SWI will program the palette with all the intermediate values.

256 colour screen modes

There can be a maximum of 16 colours used. For screen modes having more than 16 colours, the above calls instead set up a 'pseudo palette' that provides for up to 16 indirect references to colours in the real palette. Such a 'pseudo palette' must be defined before trying to paint fonts.

Wimp environment

It must be strongly emphasised that if the program you are writing is going to run under the Wimp environment then you must not use Font_SetPalette. It will damage the Wimp's colour information. It is better to use Wimp_SetFontColours, or ColourTrans_SetFontColours, or a control sequence 19,... in a string passed to Font_Paint; these all use colours that are already in the palette.

Thresholds

The setting of intermediate levels uses threshold tables. These can be read with Font_ReadThresholds or set with Font_SetThresholds. They use a lookup table that is described in Font_ReadThresholds.

Painting

Font_Paint is the central SWI that puts text onto the screen. It commences painting with the current handle, set with Font_SetFont. Printable characters it displays appropriately, using the current handle. Using Font_Paint, you can justify the text, back it with a rubout box, transform it, and/or apply kerning to its characters.

A number of embedded control sequences (introduced by control characters) change the way the string is painted:

Number Effect
9 x coordinate change in millipoints
11 y coordinate change in millipoints
17 change foreground or background colour
18 change foreground, background and range of colours
19 set colours using ColourTrans_SetFontColours (not in
RISC OS 2)
21 comment string that is not displayed
25 change underline position and thickness
26 change font handle
27 set new 4-entry transformation matrix (not in RISC OS 2)
28 set new 6-entry transformation matrix (not in RISC OS 2)

Note that these are not compatible with VDU commands. Any non-printing characters not in the above list will generate an error, apart from 0, 10 and 13 (which are the only valid terminators).

Measuring

There are a number of calls to return information about a string or character. Most of these are obsolete calls from earlier versions of the Font Manager, which are still supported for backward compatibility.

To get information on a string, you should call Font_ScanString. To get information on a character, you should call Font_CharBBox.

After using Font_ScanString, you can call Font_FutureFont. This will return what the font and colours would be if the string was passed through Font_Paint.

Caret

If the pointer is clicked on a string, and the caret needs to be placed in between two characters, it is necessary to calculate where on the string it would be. Again, Font_ScanString can do this.

You can plot the caret at a given height, position and colour using Font_Caret. Its height should be adjusted to suit the point size of the font it is placed with. The information returned from Font_ScanString would be appropriate for this adjustment.

Mixing fonts' metrics and characters

Where you are using an external printer (eg. PostScript) which has a larger range of fonts than those available on the screen, it can often be useful to use a similar-looking font on the screen, using the appropriate metrics (ie spacing) for the printer font.

The Font Manager provides a facility whereby a font can be created which has its own IntMetrics file, matching the appropriate font on the printer, but uses another font's characters on the screen.

This is done by putting a file called 'Outlines' in the font's directory which simply contains the identifier of the appropriate screen font to use. The Font Manager will use the IntMetrics file from the font's own directory, but will look in the other font's directory for any bitmap or outline information.

Under RISC OS 3 and later, the identifier can contain a transformation matrix specified in the same way as the font identifier passed to Font_FindFont. This allows simple generation of oblique fonts. For an example, see the RISC OS 3 file Resources:$.Fonts.Corpus.Oblique.Outlines0.

Handling mode changes

For efficiency, the Font Manager caches the value in millipoints of the last y coordinate to which it painted, and reuses that value if it paints to the same y coordinate next time. However, this cached value does not take account of screen eigen values, and both RISC OS 2 and RISC OS 3 (version 3.00) fail to notice a mode change and update the cached y position to take account of the new eigen values. Consequently the Font Manager will paint to the wrong y position on the screen.

To work around this, on receipt of a Service_ModeChange your application should call Font_Paint to paint a null string at coordinates (-1, -1), which is off the screen. This will invalidate the cached value, so a subsequent paint to the same y coordinate as before the mode change will then work correctly. For example you would make this call in BASIC:

SYS "Font_Paint",,"",&10,-1,-1

Service Calls


Service_FontsChanged
(Service Call &6E)

New Font$Path detected

On entry

R1 = &6E (reason code)

On exit

All registers preserved

Use

This is issued by the Font Manager to notify any module-based applications that they should call Font_ListFonts to update the list of available fonts.

SWI Calls


Font_CacheAddr
(SWI &40080)

Get the version number, font cache size and amount used

On entry

--

On exit

R0 = version number
R2 = total size of font cache (bytes)
R3 = amount of font cache used (bytes)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

The version number returned is the actual version multiplied by 100. For example, version 2.42 would return 242.

This call also returns the font cache size and the amount of space used in it.

*FontList can be used to display the font cache size and space.

Related SWIs

None

Related vectors

None


Font_FindFont
(SWI &40081)

Get the handle for a font

On entry

R1 = pointer to font identifier (terminated by a Ctrl char)
R2 = x point size × 16 (ie in 1/16ths point)
R3 = y point size × 16 (ie in 1/16ths point)
R4 = x resolution in dots per inch (0 => USE DEFAULT_ -1 => use current)
R5 = y resolution in dots per inch (0 => USE DEFAULT_ -1 => use current)

On exit

R0 = font handle
R1 - R3 preserved
R4 = x resolution in dots per inch
R5 = y resolution in dots per inch

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call returns a handle to a font whose identifier, point size and screen resolution are passed. It also sets it as the current font, to be used for future calls to Font_Paint etc.

The font identifier can also have various qualifiers added to it, which are a ' \ ' followed by an identifying letter and the value associated with the qualifier. These qualifiers are not supported by RISC OS 2. If the string does not start with a ' \ ', it is assumed that it is a font identifier.

The strings following qualifiers must not contain ' \ ', as this denotes the start of the next qualifier.

The possible qualifiers are:

\Fidentifier font identifier (as for earlier implementations of Font_FindFont)
\ft name territory number for font name, followed by the font name
\Eidentifier encoding identifier
\et name territory number for encoding name, followed by the encoding name
\Mmatrix transformation matrix to apply to this font

where:

  • identifier is a string of ASCII characters, in the range 33 to 126 inclusive, which must represent a legal filename (although it can contain '.'s).
  • name is the name of the font/encoding, expressed in the language of the current territory, and using the alphabet of the current territory, and terminated by an end-of-string.
  • t is the territory number of the current territory, ie the language in which the font/encoding name is expressed. It is followed by a space character, to separate it from the following name.
  • matrix is a set of 6 signed decimal integers which represent the values of the 6 words that go into making a draw-type matrix: the first four numbers are in fact 32-bit fixed point, with the integer part in the top 16 bits; the last two numbers are offsets, in 1/1000th of an em. Each number - including the last one - must be followed by a space.

Spaces are significant in the above syntaxes; you must include them only where shown.

The font identifier is the name of the font directory without the Font$Path prefix, and is invariant in any territory. These are used in all programmer's interfaces to the Font Manager, such as SWIs. The font name is the name of the font (ie the one displayed to the user) in the given territory. These are used in all user interfaces to the Font Manager, such as menus.

If Font_FindFont fails to find the font, an error message Font 'name' not found is returned, where name is the font name if the current territory is the same as the one in the string, and is the font identifier otherwise.

Applications should store the entire string returned from Font_DecodeMenu in the document, so that if a user loads the document without having the correct fonts available, the font name - rather than the identifier - can be returned, as long as the user is in the same territory.

The '\E' (encoding) field indicates the appropriate encoding for the font itself. This field is only supplied by Font_DecodeMenu if the font is deemed to be a 'language' font, ie one whose encoding depends on the territory. Other fonts are thought of as 'Symbol' fonts, which have a fixed encoding.

Note that Font_DecodeMenu will return a font identifier of the following form:

\Ffontid\fterritory fontname

To apply a particular encoding to a font, remember to eliminate the existing encoding fields (if present) first. Note that no field is allowed to contain a '\'.

\Eencid\eterritory encname\Ffontid\fterritoryfontname

Since fontid\fterritory fontname is also accepted by Font_FindFont, when prepending '\Eencid\eterritory encname' on the front, you should also put '\F' on the front of the original string if it did not start with '\'.

In BASIC, this looks like:

REM original$ is the original string passed to Font_FindFont
REM encoding$ is the string returned from Font_DecodeMenu
REM           typically "\E<enc_id>\e <territory> <enc_name>"
REM result is the new string to be passed to Font_FindFont
DEF FNapply_encoding_to_font(original$,encoding$)
IF LEFT$(original$,1)<>"\" THEN original$ = "\F"+original$
original$ = FNremove(original$,"\E")
original$ = FNremove(original$,"\e")
= encoding$ + original$
REM this function removes the specified field from the string
REM eliminates all characters from b$ to "\"
DEF FNremove(a$,b$)
LOCAL I%,J%
I% = INSTR(a$,b$)
IF I%=0 THEN =a$              :REM nothing to eliminate
J% = INSTR(a$+"\","\",I%+1)   :REM searches from I%+1
= LEFT$(a$,I%-1)+MID$(a$,J%)

In fact it is not strictly necessary to remove the original encoding fields from the font identifier, since an earlier occurrence of a field overrides a later one; but if this is not done then the length of the total string will continue to grow every time an encoding is altered.

Related SWIs

Font_LoseFont

Related vectors

None


Font_LoseFont
(SWI &40082)

Finish use of a font

On entry

R0 = font handle

On exit

R0 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call tells the Font Manager that a particular font is no longer required.

Related SWIs

Font_FindFont

Related vectors

None


Font_ReadDefn
(SWI &40083)

Read details about a font

On entry

R0 = font handle
R1 = pointer to buffer to hold font identifier, or 0 to return required size of buffer - if R3 = 'FULL' on entry
R3 = &4C4C5546 ('FULL') to return full information about encoding and matrix

On exit

R0, R1 preserved
R2 = x point size × 16 (ie in 1/16ths point)
R3 = y point size × 16 (ie in 1/16ths point)
R4 = x resolution (dots per inch)
R5 = y resolution (dots per inch)
R6 = age of font
R7 = usage count of font

or, if R1 = 0 and R3 = 'FULL' on entry:

R0, R1 preserved
R2 = required buffer size to hold full information
R3 - R7 corrupted

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call returns a number of details about a font. The usage count gives the number of times that Font_FindFont has found the font, minus the number of times that Font_LoseFont has been used on it. The age is the number of font accesses made since this one was last accessed.

Note that the x resolution in a 132 column mode will be the same as an 80 column mode. This is because it is assumed that it will be used on a monitor that displays it correctly, which is not the case with all monitors.

By setting R3 to 'FULL', you can get the full font identifier, including such information as its transformation matrix and encoding. You can also find the required size of buffer to hold this information by setting R1 to 0 on entry. These features are not available in RISC OS 2.

Related SWIs

None

Related vectors

None


Font_ReadInfo
(SWI &40084)

Get the font bounding box

On entry

R0 = font handle

On exit

R0 preserved
R1 = minimum x coordinate in OS units for the current mode (inclusive)
R2 = minimum y coordinate in OS units for the current mode (inclusive)
R3 = maximum x coordinate in OS units for the current mode (exclusive)
R4 = maximum y coordinate in OS units for the current mode (exclusive)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call returns the minimal area covering every character in the font. This is called the font bounding box.

You should use the SWI Font_CharBBox (see Font_CharBBox) in preference to this one.

Related SWIs

Font_CharBBox, Font_StringBBox

Related vectors

None


Font_StringWidth
(SWI &40085)

Calculate how wide a string would be in the current font

On entry

R1 = pointer to string
R2 = maximum x offset before termination in millipoints
R3 = maximum y offset before termination in millipoints
R4 = character code of 'split' character (-1 for none); eg 32 for space
R5 = index of character to terminate by

On exit

R1 = pointer to character where the scan terminated
R2 = x offset after printing string (up to termination)
R3 = y offset after printing string (up to termination)
R4 = no of 'split' characters in string (up to termination)
R5 = index into string giving point at which the scan terminated

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call is used to calculate how wide a string would be in the current font.

The 'split' character is one at which the string can be split if any of the limits are exceeded. If R4 contains -1 on entry, then on exit it contains the number of printable (as opposed to 'split') characters found.

The string is allowed to contain control sequences, including font-change (26,font_handle) and colour-change (17,colour). After the call, the current font foreground and background call are unaffected, but a call can be made to Font_FutureFont to find out what the current font would be after a call to Font_Paint.

The string width function terminates as soon as R2, R3 or R5 are exceeded, or the end of the string is reached. It then returns the state it had reached, either:

  • just before the last 'split' char reached
  • if the 'split' char is -1, then before the last char reached
  • if R2, R3 or R5 are not exceeded, then at the end of the string.

By varying the entry parameters, the string width function can be used for any of the following purposes:

  • finding the caret position in a string if you know the coordinates (although Font_FindCaret is better for this)
  • finding the caret coordinates if you know the position
  • working out where to split lines when formatting (set R4=32)
  • finding the length of a string (eg for right-justify)
  • working out the data for justification (as the Font Manager does).

You should use the SWI Font_ScanString in preference to this one - except under RISC OS 2, where it is not available.

Related SWIs

Font_FutureFont, Font_ScanString

Related vectors

None


Font_Paint
(SWI &40086)

Write a string to the screen

On entry

R0 = initial font handle (1 - 255) or 0 for current handle - if bit 8 of R2 is set
R1 = pointer to string
R2 = plot type:

bit 0 set => use graphics cursor justification coordinates (bit 5 must be clear); else use R5 to justify (if bit 5 is set) or don't justify
bit 1 set => plot rubout box using either graphics cursor rubout coordinates (if bit 5 is clear) or R5 (if bit 5 is set); else don't plot rubout box
bits 2, 3 reserved (must be zero)
bit 4 set => coordinates are in OS units; else in millipoints
bit 5 set => use R5 as indicated below (bits 0, 4 must be clear)
bit 6 set => use R6 as indicated below (bit 4 must be clear)
bit 7 set => use R7 as indicated below
bit 8 set => use R0 as indicated above
bit 9 set => perform kerning on the string
bit 10 set => writing direction is right to left; else left to right
R3 = start x coordinate (in OS coordinates or millipoints, depending on bit 4 of R2)
R4 = start y coordinate (in OS coordinates or millipoints, depending on bit 4 of R2)
R5 = pointer to coordinate block - if bit 5 of R2 is set
R6 = pointer to transformation matrix - if bit 6 of R2 is set
R7 = length of string - if bit 7 of R2 is set

On exit

R1 - R7 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call writes a string to the screen, optionally justifying it, backing it with a rubout box, transforming it, and/or applying kerning to its characters.

RISC OS 2 ignores the values of R0 and of R5 - R7, and behaves as though bits 2,3 and 5 - 31 inclusive of R2 are clear.

Justification

Justification can be done in one of two ways, depending on the value of bits 0 and 5 of R2:

  • If bit 0 of R2 is set (in which case bit 5 must be clear), the text is justified between the start coordinates (given in R3, R4) and the last position of the graphics cursor (see below).
  • If bit 0 of R2 is clear and bit 5 set (in which case bit 4 must be clear), the text is justified by adding additional spacing between words and letters. These additional offsets are specified in a coordinate block pointed to by R5.

If both bits 0 and 5 of R2 are clear then the string isn't justified.

The rubout box

Similarly, there are two different ways to plot a rubout box. Bit 1 of R2 must be set; then:

  • If bit 5 of R2 is clear, the rubout box is defined by two points previously visited by the graphics cursor (see below).
  • If bit 5 of R2 is set, then two coordinate pairs held in the block pointed to by R5 are used instead.

    In this case pixels are filled only if the pixel centre is enclosed, as in Draw_Fill.

Setting coordinates using the graphics cursor

To set the justification coordinates using the graphics cursor, you must have previously called a VDU 25 move command. Likewise, to set the rubout coordinates using the graphics cursor you must also have called VDU 25 twice, to describe the rectangle to clear: first the lower-left coordinate (which is inclusive), then the upper-right coordinate (which is exclusive). Thus, to specify both the justification and rubout coordinates, you must have made three VDU 25 moves, with the justify coordinates being last. The Font Manager rounds all these coordinates to the nearest pixel.

Using the coordinate block

The coordinate block pointed to by R5 contains eight words: these give additional spacing to use to achieve justification, and coordinates for the rubout box. The values are in millipoints (since bit 4 of R2 must be clear):

Offset Value
0 additional x, y offset on space
8 additional x, y offset between each letter
16 x, y coordinates for bottom left of rubout box (inclusive)
24 x, y coordinates for top right of rubout box (exclusive)
Transformation matrices

If bit 6 of R2 is set (in which case bit 4 must be clear), the buffer pointed to by R6 contains a transformation matrix, held as six words. The first four words are 32-bit signed numbers, with a fixed point after bit 16 (ie 1 is represented by 1 << 16, which is 65536). The translations are in millipoints (since bit 4 of R2 must be clear):

Offset Value
0 four fixed point multipliers of transformation matrix
16 x, y coordinates for translation element of transformation matrix

Subsequent matrices can be included within the string (not in RISC OS 2); they alter the matrix to the specified value, rather than being concatenated with any previous matrix. Such changes are made by including one of the following control sequences:

align, m1, m2, m3, m4
28, align, m1, m2, m3, m4, m5, m6

where align means 'sufficient null bytes for subsequent values to be word-aligned'. The equation for this is:

number of null bytes = (address of align + 3) AND NOT 3

m1 - m4 are little-endian 32-bit signed numbers with a fixed point after bit 16 (ie 1 is represented as 1 << 16, which is 65536).

m5 and m6 are the offsets, which - since bit 4 of R2 must be clear - are in millipoints. These values are assumed to be 0 if the 27,m1...m4 code is used.

To restore the unit matrix, use 27,align,65536,0,0,65536.

Note that underlining and rubout do not work correctly if the x axis is transformed so that it is no longer on the output x axis, or has its direction reversed. The effect when doing this should not be relied on.

Text direction

If bit 10 of R2 is set, then text is written right to left, rather than left to right. In this case the width of each character is subtracted from the position of the current point before painting the character, rather than the width being added after painting it. Rubout and underline are also filled in from right to left.

When kerning, the kern pairs stored in the metrics file indicate the left and right hand characters of a pair, and the additional offset to be applied between the characters if this pair is found. Note that if the main writing direction is right to left, then the right hand character is encountered first, and the left hand one is encountered next.

String length

Normally the string is painted up to its terminator. However, you can paint a substring by setting bit 7 of R2, and specifying the length of the substring in R7.

Note that the character at [R1,R7] may be accessed, to determine the character offset due to kerning (which in turn affects the underline width). This will not be a problem if the string has a terminator, and the R7=length facility is used only to extract substrings.

Changing colour

You can change the colour used by including this control sequence in the string:

19,r,g,b,R,G,B,max

This results in a call to ColourTrans_SetFontColours. Again, RISC OS 2 does not support this control sequence; but it does still provide ColourTrans_SetFontColours, which you should use in preference to 17,... or 18,... control sequences.

After the call, the current colours are updated to the last values set by this control sequences.

Other control sequences

There are other control sequences that are supported by all versions of RISC OS, and that are similar to certain VDU sequences:

9,dx_low,dx_middle,dx_high
11,dy_low,dy_middle,dy_high
17,foreground_colour (+&80 for background colour)
18,background,foreground,font_colour_offset
21,comment_string,terminator (any Ctrl char)
25,underline_position,underline_thickness
26,font_handle

After the call, the current font and colours are updated to the last values set by control sequences.

Control sequences 9 and 11 allow for movement within a string. This is useful for printing superscripts and subscripts, as well as tabs, in some cases. They are each followed by a 3-byte sequence specifying a number (low byte first, last byte sign-extended), which is the amount to move by in millipoints. Subsequent characters are plotted from the new position onwards.

An example of moving in the Y direction (character 11) would look like the following example, where chr() is a function that converts a number into a character and move is the movement in millipoints:

MoveString = chr(11) +
             chr(move AND &FF) +
             chr((move AND &FF00) >> 8) +
             chr((move AND &FF0000) >> 16)

Control sequence 17 will act as if the foreground or background parameters passed to Font_SetFontColours had been changed. Control sequence 18 allows all three parameters to that SWI to be set. See that SWI for a description of these parameters.

The underline position within control sequence 25 is the position of the top of the underline relative to the baseline of the current font, in units of 1/256th of the current font size. It is a sign-extended 8 bit number, so an underline below the baseline can be achieved by setting the underline position to a value greater than 127. The underline thickness is in the same units, although it is not sign-extended.

Note that when the underline position and height are set up, the position of the underline remains unchanged thereafter, even if the font in use changes. For example, you do not want the thickness of the underline to change just because some of the text is in italics. If you actually want the thickness of the underline to change, then another underline-defining sequence must be inserted at the relevant point. Note that the underline is always printed in the same colour as the text, and that to turn it off you must set the underline thickness to zero.

Subpixel scaling

This is quite simple if neither x or y scaling is performed, and also if both x and y scaling is performed: the subpixel scaling directions relate to the output device axes.

When just horizontal or just vertical subpixel scaling is performed, it is sometimes necessary to swap over the sense of which is horizontal and which is vertical, in order to determine the 'size' of the font.

This goes for the other FontMaxn thresholds too, such as FontMax2, which determines whether characters should be anti-aliased. FontMax3 determines whether characters should be cached or not, and this must relate to the amount of memory taken up by the bitmaps.

Scaffolding

Clearly it is not possible to apply scaffolding to characters which are transformed such that its new axes do not lie on the old ones. However, if the axes are mapped onto each other (eg a scale, rotation or reflection about an axis or 45-degree line) then scaffolding can still be applied. This can involve swapping over the x and y scaffolding. If a font is sheared, then scaffolding may be applied in one direction but not the other.

Bounding boxes

The bounding box of a transformed character cannot be determined purely by transforming the original bounding box of the character outline. This is because bounding boxes are axis-aligned rectangles, and character outlines are not, so the bounding box of the transformed character is typically smaller than that of the transformed bounding box.

Taking the bounding box of the transformed original bounding box is sufficient to work out a large enough box for outline to bitmap conversion, since not much memory is wasted (only one character is done at a time, and the character is 'shrink-wrapped' after conversion).

Bitmap fonts

If a font has an encoding applied to it, then Font_Paint looks inside fontidentifier.encoding to find the bitmap files. This is because bitmap files are specific to one encoding.

Note that Font_MakeBitmap also generates its bitmap files inside the appropriate encoding subdirectory.

If the font has no encoding applied, the bitmap files are inside the font directory, as before.

Note that this means that encoding names must not clash with any of the filenames that normally reside within font directories, ie:

IntMetrics[n] n is optional and the prefix is truncated so it all fits in 10 characters
Outlines[n]
x90y45
bnxn n is a number from 1 - 9999
fnxn
Related SWIs

Font_StringWidth, Font_ScanString

Related vectors

None


Font_Caret
(SWI &40087)

Define text cursor for Font Manager

On entry

R0 = colour (exclusive ORd onto screen)
R1 = height (in OS coordinates)
R2

bit 4 = 0 => R3, R4 in millipoints
= 1 => R3, R4 in OS coordinates
R3 = x coordinate (in OS coordinates or millipoints)
R4 = y coordinate (in OS coordinates or millipoints)

On exit

R0 - R4 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

The 'caret' is a symbol used as a text cursor when dealing with anti-aliased fonts. The height of the symbol, which is a vertical bar with 'loops' on the end, can be varied to suit the height of the text, or the line spacing.

The colour is in fact Exclusive ORd onto the screen, so in 256-colour modes it is equal to the values used in a 256-colour sprite. You can get these colours by calling ColourTrans_ReturnColourNumber.

Related SWIs

ColourTrans_ReturnColourNumber

Related vectors

None


Font_ConverttoOS
(SWI &40088)

Convert internal coordinates to OS coordinates

On entry

R1 = x coordinate (in millipoints)
R2 = y coordinate (in millipoints)

On exit

R1 = x coordinate (in OS units)
R2 = y coordinate (in OS units)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call converts a pair of coordinates from millipoints to OS units, using the current scale factor. (The default is 400 millipoints per OS unit.)

Related SWIs

Font_Converttopoints, Font_ReadScaleFactor,
Font_SetScaleFactor

Related vectors

None


Font_Converttopoints
(SWI &40089)

Convert OS coordinates to internal coordinates

On entry

R1 = x coordinate (in OS units)
R2 = y coordinate (in OS units)

On exit

R0 is corrupted
R1 = x coordinate (in millipoints)
R2 = y coordinate (in millipoints)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call converts a pair of coordinates from OS units to millipoints, using the current scale factor. (The default is 400 millipoints per OS unit.)

Related SWIs

Font_ConverttoOS, Font_ReadScaleFactor,
Font_SetScaleFactor

Related vectors

None


Font_SetFont
(SWI &4008A)

Select the font to be subsequently used

On entry

R0 = handle of font to be selected

On exit

R0 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call sets up the font which is used for subsequent painting or size-requesting calls (unless overridden by a command 26,font sequence in a string passed to Font_Paint).

You can also set the font by passing its handle in R0 when calling Font_Paint (see Font_Paint). Where possible, you should do so in preference to using this SWI.

Related SWIs

Font_Paint, Font_CurrentFont, Font_SetFontColours

Related vectors

None


Font_CurrentFont
(SWI &4008B)

Get current font handle and colours

On entry

--

On exit

R0 = handle of currently selected font
R1 = current background logical colour
R2 = current foreground logical colour
R3 = foreground colour offset

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call returns the state of the Font Manager's internal characteristics which will apply at the next call to Font_Paint.

The value in R3 gives the number of colours that will be used in anti-aliasing. The colours are f, f+1... f+offset, where 'f' is the foreground colour returned in R2, and offset is the value returned in R3. This can be negative, in which case the colours are f, f-1... f-|offset|. Negative offsets are useful for inverse anti-aliased fonts.

Offsets can range between -14 and +14. This gives a maximum of 15 foreground colours, plus one for the font background colour. If the offset is 0, just two colours are used: those returned in R1 and R2.

The font colours, and number of anti-alias levels, can be altered using Font_SetFontColours, Font_SetPalette, Font_SetThresholds and Font_Paint.

Related SWIs

Font_Paint, Font_SetFont, Font_SetFontColours, Font_SetPalette, Font_SetThresholds

Related vectors

None


Font_FutureFont
(SWI &4008C)

Check font characteristics after Font_StringWidth

On entry

--

On exit

R0 = handle of font which would be selected
R1 = future background logical colour
R2 = future foreground logical colour
R3 = foreground colour offset

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call can be made after a Font_StringWidth to discover the font characteristics after a call to Font_Paint, without actually having to paint the characters.

Related SWIs

Font_StringWidth, Font_Paint

Related vectors

None


Font_FindCaret
(SWI &4008D)

Find where the caret is in the string

On entry

R1 = pointer to string
R2 = x offset in millipoints
R3 = y offset in millipoints

On exit

R1 = pointer to character where the search terminated
R2 = x offset after printing string (up to termination)
R3 = y offset after printing string (up to termination)
R4 = number of printable characters in string (up to termination)
R5 = index into string giving point at which it terminated

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

On exit, the registers give the nearest point in the string to the caret position specified on entry. This call effectively makes two calls to Font_StringWidth to discover which character is nearest the caret position. It is recommended that you use this call, rather than perform the calculations yourself using Font_StringWidth, though this is also possible.

You should use the SWI Font_ScanString in preference to this one - except under RISC OS 2, where it is not available.

Related SWIs

Font_StringWidth, Font_FindCaretJ, Font_ScanString

Related vectors

None


Font_CharBBox
(SWI &4008E)

Get the bounding box of a character

On entry

R0 = font handle
R1 = ASCII character code
R2 = flags (bit 4 set => return OS coordinates, else millipoints)

On exit

R0 preserved
R1 = minimum x of bounding box (inclusive)
R2 = minimum y of bounding box (inclusive)
R3 = maximum x of bounding box (exclusive)
R4 = maximum y of bounding box (exclusive)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

You can use this call to discover the bounding box of any character from a given font. If OS coordinates are used and the font has been scaled, the box may be surrounded by an area of blank pixels, so the size returned will not be exactly accurate. For this reason, you should use millipoints for computing, for example, line spacing on paper. However, the millipoint bounding box is not guaranteed to cover the character when it is painted on the screen, so the OS unit bounding box should be used for this purpose.

Related SWIs

Font_ReadInfo, Font_StringBBox

Related vectors

None


Font_ReadScaleFactor
(SWI &4008F)

Read the internal to OS conversion factor

On entry

--

On exit

R1 = x scale factor
R2 = y scale factor

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

The x and y scale factors are the numbers used by the Font Manager for converting between OS coordinates and millipoints. The default value is 400 millipoints per OS unit. This call allows the current values to be read.

Related SWIs

Font_ConverttoOS, Font_Converttopoints, Font_SetScaleFactor

Related vectors

None


Font_SetScaleFactor
(SWI &40090)

Set the internal to OS conversion factor

On entry

R1 = x scale factor
R2 = y scale factor

On exit

R1, R2 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

Applications that run under the Desktop should not use this call, as other applications may be relying on the current settings. If you must change the values, you should read the current values beforehand, and restore them afterwards. The default value is 400 millipoints per OS unit.

Related SWIs

Font_ConverttoOS, Font_Converttopoints, Font_ReadScaleFactor

Related vectors

None


Font_ListFonts
(SWI &40091)

Scan for fonts, returning their identifiers one at a time; or build a menu of fonts

On entry

R1 = pointer to buffer for font identifier, or for menu definition (0 to return required size of buffer)
R2 = counter and flags:
bits 0 - 15 = counter (0 on first call)
bits 16 - 31 = 0 => RISC OS 2-compatible mode (see below)
bit 16 set => return font identifier in buffer pointed to by R1 (or required size of buffer for next identifier if R1 = 0)
bit 17 set => return local font name in buffer pointed to by R4 (or required size of buffer for next name if R4 = 0)
bit 18 set => terminate strings with character 13, rather than character 0
bit 19 set => return font menu definition in buffer pointed to by R1, and indirected menu data in buffer pointed to by R4 (or required sizes of buffers if R1 and R4 = 0)
bit 20 set => put 'System font' at head of menu
bit 21 set => tick font indicated by R6, and its submenu parent
bit 22 set => return list of encodings, rather than list of fonts
bits 23 - 31 reserved (must be zero)
R3 = size of buffer pointed to by R1 (if R1 [NOT EQUAL] 0)
R4 = pointer to buffer for font name, or for indirected menu data (0 to return required size of buffer)
R5 = size of buffer pointed to by R4 (if R4 [NOT EQUAL] 0)
R6 = pointer to identifier of font to tick (0 => NO TICK_ 1 => tick 'System font')

On exit

R1 preserved

R2 = updated counter and preserved flags if listing identifiers/names (-1 if no more to be listed); or preserved if building menu
R3 = required size of buffer pointed to by R1 (if R1 = 0 on entry); or 0 if building a font menu, and the menu is null; else length of data placed in buffer
R4 preserved
R5 = required size of buffer pointed to by R4 (if R4 = 0 on entry); else length of data placed in buffer

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call has two possible uses:

  1. Return a list of font/encoding names and/or local names known to the Font Manager, and cache the list. The names are returned in alphabetical order, regardless of the order in which they are found. ('Local names' are the names translated to the language of the current territory, if possible.)

    In this case you should first initialise R2. Only bits 16-18 and bit 22 may be set; all other bits must be clear. Then for each font/encoding you must call this SWI twice: the first time with the buffers set up to receive the name(s) of that font/encoding. Do not alter the value of R2 between calls. When R2 is -1 on exit, the last font/encoding has already been found, and any returned name(s) are invalid.

  2. Build a menu definition of all fonts known to the Font Manager. The definition is suitable for passing to Wimp_CreateMenu.

    In this case you may only set bits 19-21 of R2 on entry. You should make the call twice: the first time with R1 and R4 set to zero to find the required sizes of buffers, and the second time with the buffers set up to receive the manu definition.

Fonts are found by searching the path given by the system variable Font$Path, and its subdirectories, for files ending in '.IntMetrics'. Likewise, encodings are searched for by searching the path given by the system variable Font$Path, and its subdirectories, for files of the form 'font_prefix.Encodings.encoding_id' (which are used to specify the encodings of the 'language' fonts, as opposed to the 'symbol' fonts, the encoding of which is fixed).

When such a file is found, the full name of the subdirectory is put in the buffer, terminated by a carriage return or null. If the same font/encoding name is found via different paths, only the first one will be reported. The local name is found from a Messages file, if present.

Possible errors are 'Buffer overflow' (R3 and/or R5 was too small), or 'Bad parameters' (the flags in R2 were invalid). If an error is returned, R2 = -1 on exit (ie listing fonts/encodings is terminated).

The Font Manager command *FontCat calls this SWI internally.

Notes on RISC OS 3

The Font Manager in the RISC OS 3 ROMs (ie Font Manager 3.07 or earlier) has a bug in its handling of indirected menu titles. To work around this, you must use MessageTrans to decode the 'FontList' token in the Fonts resource file; if its length is more than 12 characters you must set the 'indirected menu title' bit of the first menu item, and otherwise you must clear it.

Notes on RISC OS 2

In the 'RISC OS 2-compatible mode' (used if bits 16 - 31 of R2 are clear), this call works as if bits 16 and 18 of R2 were set on entry, bits 17 and 19 - 31 were clear, and R3 was 40 (irrespective of its actual value).

Under RISC OS 2, this call works as if bits 16 and 18 of R2 were set on entry, and bits 17 and 19 - 31 were clear (hence R4, R5 and R6 are ignored). However, R3 is used to point to the path to search; a value of -1 means that Font$Path is used instead.

If your program does not RMEnsure the current version of the Font Manager, you should therefore always use Font$Path to specify the path to search.

Related SWIs

None

Related vectors

None


Font_SetFontColours
(SWI &40092)

Change the current colours and (optionally) the current font

On entry

R0 = font handle (0 for current font)
R1 = background logical colour
R2 = foreground logical colour
R3 = foreground colour offset (-14 to +14)

On exit

R0 - R3 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call is used to set the current font (or leave it as it is), and change the logical colours used. In up to 16 colour modes, the three registers are used as follows:

  • R1 is the logical colour of the background
  • R2 is the logical colour of the first foreground colour to use
  • R3 specifies the offset from the first foreground colour to the last, which is used as the actual foreground colour.

The range specified must not exceed the number of logical colours available in the current screen mode, as follows:

Colours in mode Possible values of R1,R2,R3 to use all colours
2 0,1,0
4 0,1,2
16 or 256 0,1,14

In a 16 colour mode, to use the top 8 colours, which are normally flashing colours, the values 8,9,6 could be used.

Note that 16 is the maximum number of anti-alias colours. In 256-colour modes, the background colour is ignored, and the foreground colour is taken as an index into a table of pseudo-palette entries - see Font_SetPalette.

Related SWIs

Font_SetFont, Font_CurrentFont, Font_SetPalette

Related vectors

None


Font_SetPalette
(SWI &40093)

Define the anti-alias palette

On entry

R1 = background logical colour
R2 = foreground logical colour
R3 = foreground colour offset
R4 = physical colour of background
R5 = physical colour of last foreground
R6 = &65757254 ('True') to use 24 bit colours in R4 and R5

On exit

R1 - R6 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call sets the anti-alias palette.

If the program you are writing is going to run under the Wimp environment then you must not use this call. It will damage the Wimp's colour information. You must instead choose from the range of colours already available by using Wimp_SetFontColours or ColourTrans_SetFontColours instead.

The values in R1, R2 and R3 have the same use as in Font_SetFontColours. See the description of that SWI on the previous pages for the use of these parameters.

R4 and R5 contain physical colour setting information. R4 describes the background colour and R5 the foreground colour. The foreground colour is the dominant colour of the text and generally appears in the middle of each character.

The physical colours in R4 and R5 are of the form &BBGGRR00. That is, they consists of four bytes, with the palette entries for the blue, green and red guns in the upper three bytes. Bright white, for instance, would be &FFFFFF00, while half intensity cyan is &77770000. The current graphics hardware only uses the upper nibbles of these colours, but for upwards compatibility the lower nibble should contain a copy of the upper nibble.

Under RISC OS 2, this call sets the palette colour for the range described in R1, R2 and R3 using R4 and R5 to describe the colours at each end. It also sets the intermediate colours incrementally between those of R4 and R5. In non-256-colour modes, the palette is programmed so that there is a linear progression from the colour given in R4 to that in R5.

Under later versions of RISC OS, if R6 is set to the magic word 'True', this call treats the values in R4 and R5 as true 24-bit palette values (where white is &FFFFFF00, rather than &F0F0F000). Otherwise, for compatibility, palette values are processed as follows:

R4 = (R4 AND &F0F0F000) OR ((R4 AND &F0F0F000) >> 4)
R5 = (R5 AND &F0F0F000) OR ((R5 AND &F0F0F000) >> 4)

Thus the bottom nibbles of each gun are set to be copies of the top nibbles. Furthermore, this call now uses PaletteV to set palette entries in non-256-colour modes, and ColourTrans_ReturnColourNumber to match RGB values with logical colours in modes with 256 or more colours. If PaletteV is not intercepted, it calls OS_Word 12 to do so.

Related SWIs

Font_SetFontColours

Related vectors

None


Font_ReadThresholds
(SWI &40094)

Read the list of threshold values for painting

On entry

R1 = pointer to result buffer

On exit

R1 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call reads the list of threshold values that the Font Manager uses when painting characters. Fonts are defined using up to 16 anti-aliased levels. The threshold table gives a mapping from these levels to the logical colours actually used to paint the character.

The format of the data read is:

Offset Value
0 Foreground colour offset
1 1st threshold value
2 2nd threshold value
3 :
n &FF

The table is used in the following way. Suppose you want to use eight colours for anti-aliased colours, one background colour and seven foreground colours. Thus the foreground colour offset is 6 (there are 7 colours). The table would be set up as follows:

Offset Value
0 6
1 2
2 4
3 6
4 8
5 10
6 12
7 14
8 &FF

When this has been set-up (using Font_SetThresholds), the mapping from the 16 colours to the eight available will look like this:

Input Output Threshold
0 0
1 0
2 1 2
3 1
4 2 4
5 2
6 3 6
7 3
8 4 8
9 4
10 5 10
11 5
12 6 12
13 6
14 7 14
15 7

Where the output colour is 0, the font background colour is used. Where it is in the range 1 - 7, the colour f+o-1 is used, where 'f' is the font foreground colour, and 'o' is the output colour.

You can view the thresholds as the points at which the output colour 'steps up' to the next value.

Related SWIs

Font_SetFontColours, Font_SetPalette, Font_SetThresholds

Related vectors

None


Font_SetThresholds
(SWI &40095)

Defines the list of threshold values for painting

On entry

R1 = pointer to threshold data

On exit

R1 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call sets up the threshold table for a given number of foreground colours. The format of the input data, and its interpretation, is explained in the previous section.

This command should rarely be needed, because the default set will work well in most cases.

Related SWIs

Font_SetFontColours, Font_SetPalette, Font_ReadThresholds

Related vectors

None


Font_FindCaretJ
(SWI &40096)

Find where the caret is in a justified string

On entry

R1 = pointer to string
R2 = x offset in millipoints
R3 = y offset in millipoints
R4 = x justification offset
R5 = y justification offset

On exit

R1 = pointer to character where the search terminated
R2 = x offset after printing string (up to termination)
R3 = y offset after printing string (up to termination)
R4 = no of printable characters in string (up to termination)
R5 = index into string giving point at which it terminated

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

The 'justification offsets', R4 and R5, are calculated by dividing the extra gap to be filled by the justification of the number of spaces (ie character 32) in the string. If R4 and R5 are both zero, then this call is exactly the same as Font_FindCaret.

You should use the SWI Font_ScanString in preference to this one - except under RISC OS 2, where it is not available.

Related SWIs

Font_FindCaret, Font_ScanString

Related vectors

None


Font_StringBBox
(SWI &40097)

Measure the size of a string

On entry

R1 = pointer to string

On exit

R1 = bounding box minimum x in millipoints (inclusive)
R2 = bounding box minimum y in millipoints (inclusive)
R3 = bounding box maximum x in millipoints (exclusive)
R4 = bounding box maximum y in millipoints (exclusive)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call measures the size of a string without actually printing it. The string can consist of printable characters and all the usual control sequences. The bounds are given relative to the start point of the string (they might be negative due to backward move control sequences, etc).

Note that this command cannot be used to measure the screen size of a string because of rounding errors. The string must be scanned 'manually', by stepping along in millipoints, and using Font_ConverttoOS and Font_CharBBox to measure the precise position of each character on the screen. Usually this can be avoided, since text is formatted in rows, which are assumed to be high enough for it.

You should use the SWI Font_ScanString in preference to this one - except under RISC OS 2, where it is not available.

Related SWIs

Font_ReadInfo, Font_CharBBox, Font_ScanString

Related vectors

None


Font_ReadColourTable
(SWI &40098)

Read the anti-alias colour table

On entry

R1 = pointer to 16 byte area of memory

On exit

R1 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call returns the 16 entry colour table to the block pointed to by R1 on entry. This contains the 16 colours used by the anti-aliasing software when painting text - that is, the values that would be put into screen memory.

Related SWIs

Font_SetFontColours, Font_SetPalette, Font_SetThresholds

Related vectors

None


Font_MakeBitmap
(SWI &40099)

Make a font bitmap file

On entry

R1 = font handle, or pointer to font identifier
R2 = x point size × 16
R3 = y point size × 16
R4 = x dots per inch
R5 = y dots per inch
R6 = flags

On exit

--

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call allows a particular size of a font to be pre-stored in the font's directory so that it can be cached more quickly. It is especially useful if subpixel positioning is to be performed, since this takes a long time if done directly from outlines.

The flags have the following meanings:

Bit Meaning when set
0 construct f9999x9999 (else b9999x9999)
1 do horizontal subpixel positioning
2 do vertical subpixel positioning
3 just delete old file, without replacing it
4 - 31 reserved (must be 0)

Once a font file has been saved, its subpixel scaling will override the setting of FontMax4/5 currently in force (so, for example, if the font file had horizontal subpixel scaling, then when a font of that size is requested, horizontal subpixel scaling will be used even if FontMax4 is set to 0).

If the font has an encoding applied to it (ie if there was a '/E' qualifier in the Font_FindFont string, or if this is a 'language' font, which varies in encoding according to the territory), then the bitmaps are held inside a subdirectory of the font directory:

prefix.fontidentifier.encoding.

Note that Font_Paint also looks inside this directory to find the bitmaps.

Related SWIs

Font_SetFontMax

Related vectors

None


Font_UnCacheFile
(SWI &4009A)

Delete cached font information, or recache it

On entry

R1 = pointer to full filename of file to be removed
R2 = recache flag (0 or 1 - see below)

On exit

--

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

If an application such as !FontEd wishes to overwrite font files without confusing the Font Manager, it should call this SWI to ensure that any cached information about the file is deleted.

The filename pointed to by R1 must be the full filename (ie in the format used by the Filer), and must also correspond to the relevant identifier as it would have been constructed from Font$Path and the font identifier. This means that each of the elements of Font$Path must be proper full pathnames, including filing system prefix and any required special fields (eg net#fileserver:$.fonts.).

The SWI must be called twice: once to remove the old version of the data, and once to load in the new version. This is especially important in the case of IntMetrics files, since the font cache can get into an inconsistent state if the new data is not read in immediately.

The 'recache' flag in R2 determines whether the new data is to be loaded in or not, and might be used like this:

SYS "Font_UnCacheFile",,"filename",0
...                                  replace old file with new one
SYS "Font_UnCacheFile",,"filename",1

Related SWIs

None

Related vectors

None


Font_SetFontMax
(SWI &4009B)

Set the FontMax values

On entry

R0 = new value of FontMax (bytes)
R1 - R5 = new values of FontMax1 - FontMax5 (in points, or in pixels × 72 × 16 under RISC OS 2)
R6, R7 reserved (must be zero)

On exit

--

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call can be used to set the values of FontMax and FontMax1... FontMax5. Changing the configured settings will also change these internal settings, but Font_SetFontMax does not affect the configured values, which come into effect on Ctrl-Break or when the Font Manager is re-initialised.

This call also causes the Font Manager to search through the cache, checking to see if anything would have been cached differently if the new settings had been in force at the time. If so, the relevant data is discarded, and will be reloaded using the new settings when next required.

Related SWIs

Font_ReadFontMax

Related vectors

None


Font_ReadFontMax
(SWI &4009C)

Read the FontMax values

On entry

--

On exit

R0 = value of FontMax (bytes)
R1 - R5 = values of FontMax1 - FontMax5 (in points, or in pixels × 72 × 16 under RISC OS 2)
R6, R7 may be corrupted

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call can be used to read the values of FontMax and FontMax1... FontMax5. It reads the values that the Font Manager holds internally (which may have been altered from the configured values by Font_SetFontMax).

Related SWIs

Font_SetFontMax

Related vectors

None


Font_ReadFontPrefix
(SWI &4009D)

Find the directory prefix for a given font handle

On entry

R0 = font handle
R1 = pointer to buffer
R2 = length of buffer

On exit

R0 preserved
R1 = pointer to terminating null
R2 = bytes remaining in buffer

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call finds the directory prefix relating to a given font handle, which indicates where the font's IntMetrics file is, and copies it into the buffer pointed to by R1; for example:

ADFS::4.$.!Fonts.Trinity.Medium.

One use for this prefix would be to find out which sizes of a font were available pre-scaled in the font directory.

Related SWIs

None

Related vectors

None


Font_SwitchOutputToBuffer
(SWI &4009E)

Switches output to a buffer, creating a Draw file structure

On entry

R0 = flags if R1 > 0, else reserved (must be zero)
R1 = pointer to word-aligned buffer, or:

8 initially to count the space required for a buffer
0 to switch back to normal
-1 to leave state unaltered (ie enquire about current status)

On exit

R0 = previous flag settings
R1 = previous buffer pointer, incremented by space required for Draw file structure

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

After this call, any calls to Font_Paint will be redirected into the buffer, as a Draw file structure.

Each letter painted will be treated as a separate filled object, with the colours specified in the paint command.

The flags in R0 have the following meaning:

Bit Meaning when set
0 update R1, but don't store anything
1 apply 'hints' to the outlines
4 give error if bitmapped characters occur (this bit overrides bit 3)

All other bits are reserved, and must be zero.

This call is not available in RISC OS 2.

On entry, the buffer must contain the following if it is to receive output:

Size Contents
4 0 (null terminator)
4 size remaining, in bytes

The Draw file structure is placed in the file before the null terminator, between (original R1) and (final R1 - 1). R1 still points to the null terminator; the terminator and free space count do not form part of the output data itself.

If bit 0 of R0 is set, output is not actually sent to the buffer, but the pointer is updated. This allows the size of the required buffer to be computed properly before allocating the space for it. Note that if bit 0 of R0 is set, R1 must initially be greater than 0 (a value of 8 is recommended, since the buffer must allow 8 bytes for the terminator and free space counter).

The rubout box(es) and any underlining are also sent to the buffer as a series of filled outlines. These will be in the correct order so as to be behind any characters which overlap them. The output will also take into account matrix transformations, font and colour changes, explicit movements, justification and kerning.

If bit 1 of R0 is set, the character outlines have hints applied to them at the current size. This means that they are not really suitable for scaling later on.

Any characters which are only available as bitmaps will either generate an error (if bit 4 of R0 is set), or not be output.

In this way drawing programs can turn on buffering, then proceed to draw text in the appropriate position and size, and end up with a series of Draw objects which represent the same thing. The set of objects that the Font Manager produces could easily be converted into a group by wrapping them suitably.

Related SWIs

None

Related vectors

None


Font_ReadFontMetrics
(SWI &4009F)

Reads the full metrics information held in a font's IntMetrics file

On entry

R0 = font handle
R1 = pointer to buffer for bounding box information, or 0 to read size of data
R2 = pointer to buffer for x width information, or 0 to read size of data
R3 = pointer to buffer for y width information, or 0 to read size of data
R4 = pointer to buffer for miscellaneous information, or 0 to read size of data
R5 = pointer to buffer for kerning information, or 0 to read size of data
R6 = 0
R7 = 0

On exit

R0 = file flags
R1 - R5 = size of data (0 if not present in file)
R6, R7 undefined

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call reads the full metrics information held in a font's IntMetrics file.

The flags in R0 have the following meaning:

Bit Meaning when set
1 kern pairs don't have x offsets
2 kern pairs don't have y offsets
3 there are more than 255 kern pairs

All other bits are reserved, and you should ignore them.

Currently this call is not permitted on fonts which have a transformation matrix applied to them. It is recommended that the call is made on the untransformed version of the font, and the results then transformed appropriately. Note that when transforming bounding boxes, the resulting (axis-aligned) box is that which bounds all 4 transformed bounding box corners. When transforming x and y offsets (ie character widths), the last 2 numbers in the matrix (the offsets) should be ignored, since the new origin is also moved by these amounts, and they therefore cancel out.

This call is not available in RISC OS 2.

The format of the data in the buffers is as follows. Except where otherwise stated:

  • all units are millipoints (1/72000")
  • all 2-byte and 4-byte numbers are little-endian, signed
Bounding box information

array[256] of groups of 4 words (x0, y0, x1, y1)

X width information

array[256] of words

Y width information

array[256] of words

Miscellaneous information
Size Description
2 x0 maximum bounding box for font (16-bit signed)
2 y0 bottom-left (x0, y0) is inclusive
2 x1 top-right (x1, y1) is exclusive
2 y1 all coordinates are in millipoints
2 default x offset per char (if flags bit 1 is set), in millipoints (16-bit signed)
2 default y offset per char (if flags bit 2 is set), in millipoints (16-bit signed)
2 italic h-offset per em (-1000 × TAN(italic angle)) (16-bit signed)
1 underline position, in 1/256th em (signed)
1 underline thickness, in 1/256th em (unsigned)
2 CapHeight in millipoints (16-bit signed)
2 XHeight in millipoints (16-bit signed)
2 Descender in millipoints (16-bit signed)
2 Ascender in millipoints (16-bit signed)
4 reserved (must be zero)
Kerning information

The kerning information is indexed by a hash table. The hash function used is:

(first letter) EOR (second letter ROR 4)

where the rotate happens in 8 bits.

Size Description
256 × 4 hash table giving offset from table start of first kern pair for each possible value (0 - 255) of hash function
4 offset of end of all kern pairs from table start
4 flag word:
bit 0 set => no bounding boxes
bit 1 set => no x offsets
bit 2 set => no y offsets
bits 3 - 30 reserved (ignore these)
bit 31 set => 'short' kern pairs
? kern pair data

Each kern pair consists of the code of the first letter of the kern pair, followed by the x offset in millipoints (if flags bit 1 is clear) and the y offset in millipoints (if flags bit 2 is clear).

If bit 31 of the flag word is clear, then the letter code, x offset and y offset are each held in a word. If bit 31 is set, then the kern pair data is shortened by combining the letter code with the first offset word as follows:

bits 0 - 7 = character code
bits 8 - 31 = x or y offset

If necessary, the second letter can be deduced from the first letter and the hash index as follows:

2nd letter = (1st letter EOR hash table index) ROR 4

where the rotate happens in 8 bits.

The hash table indicates the point at which to start looking for a given kern pair in the list of kern pairs following the table. The entries are consecutive, so each list finishes as the next one starts. To search for a given kern pair:

  1. Work out the value n of the hash function
  2. Look up the nth and (n+1)th offsets in the hash table
  3. Search for a kern pair having the correct 1st letter, looking from the nth offset up to - but not including - the (n+1)th offset.

Once the kern offsets are obtained, they can be inserted into a Font_Paint string as character 9 and 11 move sequences. (You can also paint kerned text using Font_Paint, which may be an easier option.)

Note that if flag bits 1 and 2 are both set, then it is illegal for there to be any kern pairs.

Related SWIs

None

Related vectors

None


Font_DecodeMenu
(SWI &400A0)

Decode a selection made from a font menu

On entry

R0 = flags:

bit 0 set => encoding menu, else font menu
all other bits reserved (must be zero)
R1 = pointer to menu definition (as returned by Font_ListFonts)
R2 = pointer to menu selections (as returned by Wimp_Poll with reason code = 9)
R3 = pointer to buffer to contain answer (0 => just return size)
R4 = size of buffer (if R3 [NOT EQUAL] 0)

On exit

R0, R1 preserved
R2 = pointer to rest of menu selections (if R3 [NOT EQUAL] 0 on entry)
R3 preserved
R4 = size of buffer required to hold output string (0 => no font selected)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call decodes a selection (as returned from Wimp_Poll) made from a font menu. The definition of the font menu is passed in the same format as returned from Font_ListFonts.

This call is not available in RISC OS 2.

Bit 0 of R0 determines whether it is the font menu or the encoding menu that is being decoded. In either case, the format of the returned string depends on whether the names of the fonts/encodings have been specified in a Messagesn file inside the font directory. The name field is not present if the Font Manager has worked out the list of fonts/encodings by scanning the directory instead.

File holds: Format of returned string:
Font id, no name \Ffont_id
Font id, with name \Ffont_id\fterritory fontname
Encoding, no name \Eencoding_id
Encoding, with name \Eencoding_id\eterritory encoding_name

Since Font_DecodeMenu works by comparing the string in the menu against the Font Manager's known font names, in the case of 'System font' being selected from a menu that contained it, R4 would be returned as 0. To distinguish this from the 'no font selected' case, check for R2 pointing to 0 on entry, since 'System font' is always the first menu entry if present.

Related SWIs

Font_ListFonts

Related vectors

None


Font_ScanString
(SWI &400A1)

Return information on a string

On entry

R0 = initial font handle (1 - 255) or 0 for current handle - if bit 8 of R2 is set
R1 = pointer to string
R2 = plot type:

bits 0 - 4 reserved (must be zero)
bit 5 set => use R5 as indicated below
bit 6 set => use R6 as indicated below
bit 7 set => use R7 as indicated below
bit 8 set => use R0 as indicated above
bit 9 set => perform kerning on the string
bit 10 set => writing direction is right to left; else left to right
bits 11 - 16 reserved (must be zero)
bit 17 set => return nearest caret position; else length of string
bit 18 set => return bounding box of string in buffer pointed to by R5 (bit 5 must be set)
bit 19 set => return matrix applying at end of string in buffer pointed to by R6 (bit 6 must be set)
bit 20 => return number of split characters in R7 (bit 7 must be set)
bits 21 - 31 reserved (must be zero)
R3, R4 = offset of mouse click - if bit 17 of R2 is set; else maximum x, y coordinate offset before split point
R5 = pointer to buffer used on entry for coordinate block and split character - if bit 5 of R2 is set - and on exit for returned bounding box- if bit 18 of R2 is set
R6 = pointer to buffer used on entry for transformation matrix - if bit 6 of R2 is set - and on exit for returned transformation matrix- if bit 19 of R2 is set
R7 = length of string - if bit 7 of R2 is set

On exit

R0 preserved
R1 = pointer to point in string of caret position - if bit 17 of R2 is set; else to split point, or end of string if splitting not required
R2 preserved
R3, R4 = x, y coordinate offset to caret position - if bit 17 of R2 is set; else to split point, or end of string if splitting not required
R5, R6 preserved
R7 = number of split characters encountered - if bit 20 of R2 was set; else preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call scans a string as if it were painted to the screen using Font_Paint, and returns various information about it. It is particularly useful for finding the correct position of the caret within a string, or for finding where to split a line, if at all.

For full details of the parameters passed, and of control sequences that may be included in the string, you should see the description of Font_Paint on Font_Paint. Below we merely describe the changes and additions relative to that SWI.

This call is not available in RISC OS 2.

Coordinates

Unlike Font_Paint, this call uses millipoints for all coordinates; you may not specify OS units by setting bit 4 of R2.

R3 and R4 do not specify the start coordinates of the string. Instead they specify either the offset from the start of the string to the mouse click (used to work out where to insert the caret), or the maximum offset before the split point (ie the width and height remaining on the current line).

On exit R3 and R4 give the offset of the caret position or the split point. When scanning to determine the split point, the scan continues until the current offset is less than or greater than the limit supplied, depending on the sign of that limit. If R3 is negative on entry, the scan continues until the x offset is less than R3, while if R3 is positive, the scan continues until the x offset is greater than R3. Note that this is incompatible with the old Font_StringWidth call, which always continued until the x and y offsets were greater than R2 or R3. (Font_StringWidth still works in the old way, to ensure compatibility).

Graphics cursor coordinates

Font_ScanString does not use graphics cursor coordinates for justification, nor to specify a rubout box. Justification can still be performed using the coordinate block pointed to by R5, whereas rubout boxes are not supported at all.

The coordinate block and split character

The coordinate block pointed to by R5 differs from that used by Font_Paint in that no rubout box is given. Instead the word at offset 16 is used to specify the 'split character' on entry.

The four following words (ie starting at offset 20) are used to return the string's bounding box, if bit 18 of R2 is set on entry. This excludes the area occupied by underlining or rubout

Offset Value
0 additional x, y offset on space
8 additional x, y offset between each letter
16 split character (-1 => none)
20 returned x, y coordinates for bottom left of string bounding box (inclusive) - if bit 18 of R2 is set
28 returned x, y coordinates for top right of string bounding box (exclusive) - if bit 18 of R2 is set

If there is no split character, but bit 20 of R2 is set ('return number of split characters in R7'), then R7 will instead be used to return the number of non-control characters encountered (ie those characters with codes of 32 or more which are not part of a control sequence).

Transformation matrices

If bit 19 of R2 is set on entry, the transformation matrix pointed to by R6 is updated on exit to return the matrix applying at the end of the string.

Text direction

Where bit 10 is set (ie the main writing direction is right to left), one would normally supply a negative value of R3.

String length

Note that the character at [R1,R7] may be accessed to determine whether it is a 'split character', as well as to determine the character offset due to kerning.

Related SWIs

This SWI replaces the following deprecated (still supported, but not recommended) SWIs:

Font_StringWidth, Font_FindCaret, Font_FindCaretJ, Font_StringBBox

Related vectors

None


Font_SetColourTable
(SWI &400A2)

This call is for internal use by the ColourTrans module only. You must not use it in your own code.

This call is not available in RISC OS 2.

To set font colours you should either use ColourTrans_SetFontColours (see ColourTrans_SetFontColours) or Font_Paint control sequence 19 (see Changing colour).


Font_CurrentRGB
(SWI &400A3)

Reads the settings of colours after calling Font_Paint

On entry

--

On exit

R0 = font handle
R1 = background font colour (&BBGGRR00)
R2 = foreground font colour (&BBGGRR00)
R3 = maximum colour offset (0 => mono, else anti-aliased)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call reads the settings of the RGB foreground and background colours after calling Font_Paint.

This call is not available in RISC OS 2.

The error 'Undefined RGB font colours' is generated if the colours were not set using RGB values.

Related SWIs

None

Related vectors

None


Font_FutureRGB
(SWI &400A4)

Reads the settings of colours after calling various Font... SWIs

On entry

--

On exit

R0 = font handle
R1 = background font colour (&BBGGRR00)
R2 = foreground font colour (&BBGGRR00)
R3 = maximum colour offset (0 => mono, else anti-aliased)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call reads the settings of the RGB foreground and background colours after calling Font_ScanString, Font_StringWidth, Font_StringBBox, Font_FindCaret or Font_FindCaretJ.

This call is not available in RISC OS 2.

The error 'Undefined RGB font colours' is generated if the colours were not set using RGB values.

Related SWIs

None

Related vectors

None


Font_ReadEncodingFilename
(SWI &400A5)

Returns the filename of the encoding file used for a given font handle

On entry

R0 = font handle
R1 = pointer to buffer to receive prefix
R2 = length of buffer

On exit

R0 = pointer to encoding filename (in buffer)
R1 = pointer to terminating 0 of filename
R2 = bytes remaining in buffer

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call returns the filename of the encoding file used for a given font handle. It is primarily useful for PDriverPS to gain access to the file of identifiers that defines an encoding, in order to send it to the printer output stream.

The filename depends on whether the font has a 'public' or 'private' encoding (public encodings apply to 'language' fonts, as described in Font_ListFonts, while private encodings are not used by the Font Manager, and simply describe the PostScript names for the characters in the font).

Encoding Filename
public font_prefix.Encodings.encoding
private font_prefix.font_name.Encoding

The error 'Buffer overflow' is generated if the buffer is too small.

This call is not available in RISC OS 2.

Related SWIs

None

Related vectors

None


Font_FindField
(SWI &400A6)

Returns a pointer to a specified field within a font identifier

On entry

R1 = pointer to font identifier
R2 = character code of qualifier required

On exit

R1= pointer to value following qualifier in string (if field present); else preserved
R2 = 0 if field not present; else preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call, given a font string and a qualifier that specifies a field within that string, returns a pointer to the specified field.

The 'F' field is space-terminated, while all others are control-character terminated.

This call is not available in RISC OS 2.

Related SWIs

Font_ApplyFields

Related vectors

None


Font_ApplyFields
(SWI &400A7)

Merges a new set of fields with those already in a given font identifier

On entry

R0 = pointer to original font identifier
R1 = pointer to set of fields to be added (in format of a font identifier)
R2 = pointer to output buffer, or 0 to get required new size of buffer
R3 = size of output buffer

On exit

R0 - R2 preserved
R3 = remaining size of buffer, or incremented by the length of the output string (excluding its null terminator)

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call merges a new set of fields with those already in a given font identifier, replacing existing fields and adding new ones. You can also delete existing fields by specifying a null field to replace it.

This operation is performed in two passes:

  1. Copy fields in [R0] from [R1] if present, else [R0]
  2. Copy fields in [R1] from [R1] if not present in [R0]

This call is not available in RISC OS 2.

Related SWIs

Font_FindField

Related vectors

None


Font_LookupFont
(SWI &400A8)

Returns information about a particular font

On entry

R0 = font handle, or 0 for current handle
R1 = 0
R2 = 0

On exit

R0, R1 preserved
R2 = characteristics of font:

bit 0 set => font is old 'x90y45' bitmap format
bit 1 set => font is in ROM
bit 8 set => font is monochrome only, irrespective of value of FontMax2
bit 9 set => font is filled with non-zero rule, rather than even-odd
all other bits reserved and should be ignored
R3-R7 corrupted

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call returns information about a particular font. On exit R2 contains a set of flags describing how the font is rendering, and other characteristics.

This call is not available in RISC OS 2, nor in RISC OS 3 (version 3.00).

Related SWIs

None

Related vectors

None

*Commands


*Configure FontMax

Sets the configured maximum desirable size of the font cache

Syntax

*Configure FontMax mK|n

Parameters

mK - number of kilobytes of memory reserved
n - number of 4k chunks of memory reserved

Use

*Configure FontMax sets the configured maximum desirable size of the font cache. The difference between FontSize and FontMax is the extra amount of memory that the Font Manager will attempt to use if it needs to. If other parts of the system have already claimed all the spare memory, then FontSize is what it is forced to work with.

If FontMax is bigger than FontSize, when the Font Manager cannot obtain enough cache memory it will attempt to expand the cache by throwing away unused blocks (ie ones that belong to fonts which have had Font_FindFont called on them more often than Font_LoseFont). Once the cache has expanded up to FontMax, the Font Manager will throw away the oldest block found, even if it is in use. This can result in the Font Manager heavily using the filing system, since during a window redraw it is possible that all fonts will have to be thrown away and recached in turn.

The Font Manager has to keep permanently in its cache some information on each font in use. Consequently, if many more fonts are in use than are reasonable for the configured FontMax, the Font Manager may be forced to let the cache grow past this point.

Example

*Configure FontMax 256K

Related commands

*Configure FontSize

Related SWIs

Font_CacheAddr, Font_SetFontMax, Font_ReadFontMax

Related vectors

None


*Configure FontMax1

Sets the maximum height at which to scale from a bitmap font

Syntax

*Configure FontMax1 max_pointsize

Parameters

max_height - maximum height of font at which to scale from a bitmap font; units are points, except under RISC OS 2, which uses pixel height (see below)

Use

*Configure FontMax1 sets the maximum height at which to scale from a bitmap font rather than from an outline font - but only if 4 bit per pixel output is possible.

When the Font Manager can use 4 bits per pixel, it first looks for an f9999x9999 file of the correct size; then it looks for an x90y45 font of the correct size. Next it considers the values of FontMax2 and 3, and then of FontMax4 and 5. Only if the above fail to produce output does it then consider the value of FontMax1:

  • If the font height is less than or equal to the value specified in FontMax1, or if there is no Outlines file, the Font Manager looks for the x90y45 file to determine which bitmap font to scale. If the x90y45 file contains the name of an f9999x9999 file, then that file is scaled; else one of the fonts in the x90y45 file is scaled.
  • Otherwise the Font Manager scales the Outlines file to give an anti-aliased (4 bits per pixel) bitmap.

The height is set in points, except under RISC OS 2 which uses pixel height:

pixel height = height in points × pixels (or dots) per inch / 72

The pixel height corresponds to different point sizes on different resolution output devices.

Example

*Configure FontMax1 25

Related commands

*Configure FontMax2

Related SWIs

Font_SetFontMax, Font_ReadFontMax

Related vectors

None


*Configure FontMax2

Sets the maximum height at which to scale from outlines to anti-aliased bitmaps

Syntax

*Configure FontMax2 max_height

Parameters

max_height - maximum height of font at which to scale from outlines to anti-aliased bitmaps; units are points, except under RISC OS 2, which uses pixel height (see below)

Use

*Configure FontMax2 sets the maximum height at which to scale from outlines to anti-aliased bitmaps, rather than to 1 bit per pixel bitmaps.

When the Font Manager can use 4 bits per pixel, it first looks for an f9999x9999 file of the correct size; then it looks for an x90y45 font of the correct size. Only if the above fail to produce output does it then consider the value of FontMax2:

  • If the font height is less than or equal to the heights specified in both FontMax2 and 3, the Font Manager goes on to consider the values of FontMax4 and 5, and then of FontMax1. Any bitmaps it produces from outlines will be anti-aliased.
  • Otherwise, the Font Manager uses 1 bit per pixel bitmaps. It first looks for a b9999x9999 file of the correct size.

    If it fails to find one it uses the Outlines file to paint a 1 bit per pixel bitmap. The value of FontMax3 determines whether the Font Manager caches the bitmap or the outline.

The height is set in points, except under RISC OS 2 which uses pixel height:

pixel height = height in points × pixels (or dots) per inch / 72

The pixel height corresponds to different point sizes on different resolution output devices.

Example

*Configure FontMax2 20

Related commands

*Configure FontMax1, *Configure FontMax3

Related SWIs

Font_SetFontMax, Font_ReadFontMax

Related vectors

None


*Configure FontMax3

Sets the maximum height at which to retain bitmaps in the cache

Syntax

*Configure FontMax3 max_height

Parameters

max_height - maximum height of font at which to retain bitmaps in the cache; units are points, except under RISC OS 2, which uses pixel height (see below)

Use

*Configure FontMax3 sets the maximum height at which to retain bitmaps in the cache, rather than the outlines from which they were converted.

Unlike the other FontMaxn values, FontMax3 affects the Font Manager both when it can use 4 bits per pixel, and when it can only use 1 bit per pixel.

4 bits per pixel

When the Font Manager can use 4 bits per pixel, it first looks for an f9999x9999 file of the correct size; then it looks for an x90y45 font of the correct size. Only if the above fail to produce output does it then consider the value of FontMax3:

  • If the font pixel height is less than or equal to the heights specified in both FontMax2 and 3, the Font Manager goes on to consider the values of FontMax4 and 5, and then of FontMax1. Any bitmaps it produces will be cached.

    Otherwise, the Font Manager first looks for a b9999x9999 file of the correct size.

    If it fails to find one it uses the Outlined file to paint a 1 bit per pixel bitmap. The value of FontMax3 determines whether the Font Manager caches the bitmap or the outline:

      • If the font pixel height is less than or equal to the height specified in FontMax3, the Font Manager retains the resultant bitmap in the cache.
      • If the font pixel height is greater than the height specified in FontMax3, the Font Manager will not cache the bitmaps, but will instead cache the outlines themselves.

        It draws the outlines directly onto the destination using the Draw module; consequently they are not anti-aliased. The Font Manager sets up the appropriate GCOL and TINT settings for this, and resets them afterwards.

1 bit per pixel

If the Font Manager can only use 1 bit per pixel, it first looks for a b9999x9999 file of the correct size.

If it fails to find one it looks for the Outlines file, scaling it to give a 1 bit per pixel bitmap. The value of FontMax3 determines whether the Font Manager caches the bitmap or the outline:

  • If the font pixel height is less than or equal to the height specified in FontMax3, the Font Manager retains the resultant bitmap in the cache.
  • If the font pixel height is greater than the height specified in FontMax3, the Font Manager will not cache the bitmaps, but will instead cache the outlines themselves.

    It draws the outlines directly onto the destination using the Draw module; consequently they are not anti-aliased. The Font Manager sets up the appropriate GCOL and TINT settings for this, and resets them afterwards.

If there is no Outlines file, the Font Manager then looks for an f9999x9999 file of the correct size; then it looks for an x90y45 font of the correct size. Finally it uses the x90y45 file to determine which bitmap font to scale. If the x90y45 file contains the name of an f9999x9999 file, then that file is scaled; else one of the fonts in the x90y45 file is scaled.

The height is set in points, except under RISC OS 2 which uses pixel height:

pixel height = height in points × pixels (or dots) per inch / 72

The pixel height corresponds to different point sizes on different resolution output devices.

Example

*Configure FontMax3 35

Related commands

*Configure FontMax2

Related SWIs

Font_SetFontMax, Font_ReadFontMax

Related vectors

None


*Configure FontMax4

Sets the maximum width at which to use horizontal subpixel anti-aliasing

Syntax

*Configure FontMax4 max_width

Parameters

max_width - maximum width of font at which to use horizontal subpixel anti-aliasing; units are points, except under RISC OS 2, which uses pixel width (see below)

Use

*Configure FontMax4 sets the maximum width at which to use horizontal subpixel anti-aliasing.

When the Font Manager can use 4 bits per pixel, it first looks for an f9999x9999 file of the correct size (note that this bitmap may have been constructed with subpixel anti-aliasing already performed - see Font_MakeBitmap); then it looks for an x90y45 font of the correct size. Next it considers the values of FontMax2 and 3. Only if the above fail to produce output does it then consider the value of FontMax4 and 5:

  • If the font pixel width is less than or equal to the width specified in FontMax4, the Font Manager will look for the Outlines file, and will construct 4 anti-aliased bitmaps for each character, corresponding to 4 possible horizontal subpixel alignments on the screen.

    Likewise, if the font pixel wheight is less than or equal to the height specified in FontMax5, the Font Manager will perform vertical subpixel anti-aliaing. Thus if both horizontal and vertical subpixel anti-aliasing occurs, 16 bitmaps will be constructed.

    When painting the text, the Font Manager will use the bitmap which corresponds most closely the the required alignment.

  • Otherwise the Font Manager goes on to consider the value of FontMax1; it will not use subpixel anti-aliasing.

The width is set in points, except under RISC OS 2 which uses pixel width:

pixel height = height in points × pixels (or dots) per inch / 72

The pixel width corresponds to different point sizes on different resolution output devices.

Example

*Configure FontMax4 0

Related commands

*Configure FontMax5

Related SWIs

Font_SetFontMax, Font_ReadFontMax

Related vectors

None


*Configure FontMax5

Sets the maximum height at which to use vertical subpixel anti-aliasing

Syntax

*Configure FontMax5 max_height

Parameters

max_height - maximum font pixel height at which to use vertical subpixel anti-aliasing

Use

*Configure FontMax5 sets the maximum height at which to use vertical subpixel anti-aliasing.

When the Font Manager can use 4 bits per pixel, it first looks for an f9999x9999 file of the correct size (note that this bitmap may have been constructed with subpixel anti-aliasing already performed - see Font_MakeBitmap); then it looks for an x90y45 font of the correct size. Next it considers the values of FontMax2 and 3. Only if the above fail to produce output does it then consider the value of FontMax4 and 5:

  • If the font pixel height is less than or equal to the height specified in FontMax5, the Font Manager will look for the Outlines file, and will construct 4 anti-aliased bitmaps for each character, corresponding to 4 possible vertical subpixel alignments on the screen.

Likewise, if the font pixel wheight is less than or equal to the height specified in FontMax5, the Font Manager will perform horizontal subpixel anti-aliaing. Thus if both horizontal and vertical subpixel anti-aliasing occurs, 16 bitmaps will be constructed.

When painting the text, the Font Manager will use the bitmap which corresponds most closely the the required alignment.

  • Otherwise the Font Manager goes on to consider the value of FontMax1; it will not use subpixel anti-aliasing.

The height is set in points, except under RISC OS 2 which uses pixel height:

pixel height = height in points × pixels (or dots) per inch / 72

The pixel height corresponds to different point sizes on different resolution output devices.

Example

*Configure FontMax4 0

Related commands

*Configure FontMax5

Related SWIs

Font_SetFontMax, Font_ReadFontMax

Related vectors

None


*Configure FontSize

Sets the configured amount of memory reserved for the font cache

Syntax

*Configure FontSize sizeK

Parameters

size - number of kilobytes to allocate

Use

*Configure FontSize sets the configured amount of memory reserved for the font cache. This is claimed when the Font Manager is first initialised. If insufficient memory is free, the Font Manager starts running using what is available.

The Font Manager will never shrink its cache below this configured size.

The minimum cache size can also be changed from the Task Manager, by dragging the font cache bar directly, although this is not remembered after a Control-reset.

Example

*Configure FontSize 32K

Related commands

*Configure FontMax

Related SWIs

Font_CacheAddr

Related vectors

None


*FontCat

Lists the fonts available in a directory

Syntax

*FontCat [directory]

Parameters

directory - pathname of a directory to search for fonts

Use

*FontCat lists the fonts available in the given directory. If no directory is given, then the directory specified in the system variable Font$Path is used.

Font_FindFont uses the same variable when it searches for a font.

Example

*FontCat ADFS:$.Fonts.  The last '.' is essential
Corpus.Medium
Portrhouse.Standard
Trinity.Medium

Related commands

None

Related SWIs

Font_FindFont, Font_ListFonts

Related vectors

None


*FontInstall

Adds a directory to the list of those scanned for fonts

Syntax

*FontInstall [directory]

Parameters

directory - pathname of a directory to add to Font$Path

Use

*FontInstall adds a directory to the list of those scanned for fonts. It does so by altering the system variable Font$Path so that the given pathname appears before any others, and is not repeated. It also rescans the directory, even if it was already known to the Font Manager.

If no pathname is given, all directories in Font$Path are rescanned.

FontInstall will only rescan a directory already on the path if it moves to the head of the path. The best way to force a re-scan after changing a directory known to the Font Manager is to call *FontRemvoe, then *FontInstall.

Service_FontsChanged is issued whenever a directory is scanned.

This command is not available in RISC OS 2.

Example

*FontInstall RAM:$.Fonts.  The last '.' is essential

Related commands

*FontRemove

Related SWIs

None

Related vectors

None


*FontLibrary

Sets a directory as the font library, replacing the previous library

Syntax

*FontLibrary directory

Parameters

directory - a valid pathname specifying a directory

Use

*FontLibrary sets a directory as the font library, replacing the previous library in the list of those scanned for fonts. It does so by altering the system variable Font$Prefix to the given directory, and ensures that the string '<Font$Prefix>.' appears on the front of the system variable Font$Path.

Note however that if the previous font library had also been explicitly added to Font$Path (say by *FontInstall), it will still be scanned.

This command is not available in RISC OS 2.

Example

*FontLibrary SCSIFS::MyDisc.$.FontLib

Related commands

None

Related SWIs

None

Related vectors

None


*FontList

Displays the fonts in the font cache, its size, and its free space

Syntax

*FontList

Parameters

None

Use

*FontList displays the fonts currently in the font cache. For each font, its identifier is given, together with its point size, its resolution, the number of times it is being used by various applications, and the amount of memory it is using.

The size of the font cache and the amount of free space (in Kbytes) is also given.

Example

*FontList
    Name                    Size               Dots/inch    Use  Cache memory
    ----                    ----               ---------    ---  ------------
  1.Homerton.Medium         12 point            90x45         3      4 Kbytes
  2.Homerton.Medium         master ROM outlines               1    696 bytes
  
Cache size:  32 Kbytes
      free:  24 Kbytes

Related commands

None

Related SWIs

Font_ListFonts

Related vectors

None


*FontRemove

Removes a directory from the list of those scanned for fonts

Syntax

*FontRemove [directory]

Parameters

directory - pathname of a directory to remove from Font$Path

Use

*FontRemove removes a directory from the list of those scanned for fonts. It does so by removing the given pathname from the system variable Font$Path.

This command is not available in RISC OS 2.

Example

*FontRemove RAM:$.Fonts.  The last '.' is essential

Related commands

*FontInstall

Related SWIs

None

Related vectors

None


*LoadFontCache

Loads a file back into the font cache

Syntax

*LoadFontCache filename

Parameters

filename - a valid pathname specifying a file previously saved using *SaveFontCache

Use

*LoadFontCache loads a file that was previously saved using *SaveFontCache back into the font cache.

An error is generated if any fonts are currently claimed, or if the font cache format cannot be read by the current Font Manager (ie it was created by a version of the Font Manager that used an incompatible font cache format).

The size of the font cache slot will - if necessary - be increased to accommodate the new cache data; but it will not be decreased, even if the new cache data is smaller than the current cache slot size.

This command is useful for setting up the font cache to a predefined state, to save time scaling fonts later on.

Note: A saved font cache is only valid if RMA usage is the same as when it was saved, since it contains absolute pointers into modules and their workspace. If RMA usage has altered (eg the cache is loaded to a different address, or the Font Manager's workspace is in a different location) you will get no error on loading the cache; but you will get many subsequent errors. This call (and SaveFontCache) is therefore deprecated.

This command is not available in RISC OS 2.

Example

*LoadFontCache SCSIFS::MyDisc.$.FontCache

Related commands

*SaveFontCache

Related SWIs

None

Related vectors

None


*SaveFontCache

Saves the font cache to a file

Syntax

*SaveFontCache filename

Parameters

filename - a valid pathname specifying a file

Use

*SaveFontCache saves the current contents of the font cache, with certain extra header information, to a file of type &FCF (FontCache). The Run alias for this filetype executes *LoadFontCache, which loads the file back into the font cache.

Note: A saved font cache is only valid if RMA usage is the same as when it was saved, since it contains absolute pointers into modules and their workspace. If RMA usage has altered (eg the cache is loaded to a different address, or the Font Manager's workspace is in a different location) you will get no error on loading the cache; but you will get many subsequent errors. This call (and LoadFontCache) is therefore deprecated.

This command is not available in RISC OS 2.

Example

*SaveFontCache SCSIFS::MyDisc.$.FontCache

Related commands

*LoadFontCache

Related SWIs

None

Related vectors

None

Application Notes

BASIC example of justified text

100 SYS "Font_FindFont",,"Trinity.Medium",320,320,0,0 TO HAN%
110 REM sets font handle
120 SYS "Font_SetPalette",,8,9,6,&FFFFFF00,&00000000
130 REM Set the palette to use colours 8-15 as white to black
140 MOVE 800,500
150 REM Set the right hand side of justification
160 SYS "Font_Paint",,"This is a test",&11,0,500
170 SYS "Font_LoseFont",HAN%

On line 160, Font_Paint is being told to use OS coordinates and justify, starting at location 0,500. 800,500 has been declared as the right hand side of justification by line 140.

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015