|
www.riscos.com Technical Support: |
The Font Dialogue box can be broken down into the following components:
Note that the strings which appear in the font, weight and style display fields may be localised for the current territory, but the strings used to communicate font selections between the client and the Toolbox are always the 'real' font id of the font (e.g. Corpus.Bold.Oblique).
A Font Dialogue object has the following attributes which are specified in its object template and can be manipulated at run-time by the client application:
| Attributes | Description | |
|---|---|---|
| flags word | Bit | Meaning |
| 0 | when set, this bit indicates that a FontDbox_AboutToBeShown event should be raised when SWI Toolbox_ShowObject is called for this object. | |
| 1 | when set, this bit indicates that a FontDbox_DialogueCompleted event should be raised when the Font Dialogue object has been removed from the screen. | |
| 2 | when set, include a System font entry in the list of fonts. | |
| title | an alternative title for the dialogue box instead of 'Type style' (0 means use default title) | |
| max title length | the maximum length in bytes of title text which will be used for this object | |
| initial font | the font id to be displayed in the dialogue box as the selected font, on creation. If 0, the default is to display the first font in the list of currently available fonts. | |
| initial height | the initial height value when the dialogue box is created | |
| initial aspect | the initial aspect ratio value when the dialogue box is created | |
| try string | an alternative string to use in the Try writable field, instead of 'The quick brown fox jumps over the lazy dog' | |
| window | an alternative window template to use instead of the default one. | |
A Font Dialogue object is created using SWI Toolbox_CreateObject.
When this object is created it has no attached objects (see Attached objects).
A Font Dialogue object is deleted using SWI Toolbox_DeleteObject.
The setting of the non-recursive delete bit does not have a meaning for Font Dialogue objects.
When a Font Dialogue object is displayed on the screen using SWI Toolbox_ShowObject it has the following behaviour:
| Show type | Position | ||
|---|---|---|---|
| 0 (default) | the underlying window is shown at the last place shown on the screen, or the coordinates given in its template, if it has not already been shown | ||
| 1 (full spec) | R3 + 0 | visible area minimum x coordinate | |
| R3 + 4 | visible area minimum y coordinate | ||
| R3 + 8 | visible area maximum x coordinate | ||
| R3 + 12 | visible area maximum y coordinate | ||
| R3 + 16 | scroll x offset relative to work area | ||
| R3 + 20 | scroll y offset relative to work area | ||
| R3 + 24 | Wimp window handle of window to open behind | ||
| -1 | means top of stack | ||
| -2 | means bottom of stack | ||
| -3 | means the window behind the Wimp's backwindow | ||
| 2 (topleft) | R3 + 0 | visible area minimum x coordinate | |
| R3 + 4 | visible area minimum y coordinate | ||
When the client calls Toolbox_ShowObject, a FontDbox_AboutToBeShown Toolbox event is raised (if the appropriate flags bit is set), allowing the client to take any last minute action. Typically, a client will indicate which of the fonts should be shown as the currently selected one, when it receives this event.
The currently selected font id can be set and read at run-time using the FontDbox_SetFont and FontDbox_GetFont methods. These use a font id which assumes a <name>.<weight>.<style> structure (i.e. the first component appears in the Font field, the second in the Weight field, and the third in the Style field).
The size (both height and aspect ratio components) are set and read using the FontDbox_SetSize/FontDbox_GetSize methods respectively.
The Try string can be set and read using the FontDbox_SetTryString and FontDbox_GetTryString methods.
When the user clicks the Apply button (or presses the Return key when the Font Dialogue box has the input focus), the client application is sent a FontDbox_ApplyFont Toolbox event. This event gives the font id of the currently selected font.
When the dialogue box is closed, either because Apply or Cancel has been clicked, or Escape has been pressed, a FontDbox_DialogueCompleted Toolbox event is raised for the client, with an indication of whether a font was selected during the dialogue.
The following methods are all invoked by calling SWI Toolbox_MiscOp with:
| R0 | holding a flags word |
| R1 | being a Font Dialogue Box id |
| R2 | being the method code which distinguishes this method |
| R3-R9 | potentially holding method-specific data |
| R0 | = | flags |
| R1 | = | FontDbox object id |
| R2 | = | 0 |
| R0 | = | Window object id for this FontDbox object |
This method returns the id of the underlying Window object used to implement this FontDbox object.
extern _kernel_oserror *fontdbox_get_window_id( unsigned int flags,
ObjectId fontdbox,
ObjectId *window
);
| R0 | = | flags |
| R1 | = | Font Dbox object id |
| R2 | = | 1 |
| R3 | = | pointer to font id of font to select (0 means none) |
| R1-R9 preserved |
This method selects a font as being the currently selected one for this Font Dialogue box, and displays its name appropriately in the Font/Weight/Style display fields.
The special font id 'SystemFont' is used to indicate that the System entry should be selected.
extern _kernel_oserror *fontdbox_set_font ( unsigned int flags,
ObjectId fontdbox,
char *font_id
);
| R0 | = | flags |
| R1 | = | Font Dbox object id |
| R2 | = | 2 |
| R3 | = | pointer to buffer to hold font id |
| R4 | = | buffer size for font id |
| R4 | = | size of buffer required (if R3 was 0) else buffer pointed at by R3 holds font id R4 holds number of bytes written to buffer |
This method returns the font id for the font which was last specified in a FontDbox_SetFont call, or was last chosen by a user choice from a pop-up menu.
The special font id 'SystemFont' is used to indicate that the System entry is selected.
extern _kernel_oserror *fontdbox_get_font ( unsigned int flags,
ObjectId fontdbox,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags bit 0 set means change the height value bit 1 set means change the aspect ratio |
| R1 | = | Font Dbox object id |
| R2 | = | 3 |
| R3 | = | height value |
| R4 | = | aspect ratio value |
| R1-R9 preserved |
This method sets the height value and/or the aspect ratio displayed in the Font Dialogue box.
extern _kernel_oserror *fontdbox_set_size ( unsigned int flags,
ObjectId fontdbox,
int height,
int aspect_ratio
);
| R0 | = | flags |
| R1 | = | Font Dbox object id |
| R2 | = | 4 |
| R0 | = | height value |
| R1 | = | aspect ratio |
This method returns the height value and/or aspect ratio currently displayed in the Font Dialogue box.
extern _kernel_oserror *fontdbox_get_size ( unsigned int flags,
ObjectId fontdbox,
int *height,
int *aspect_ratio
);
| R0 | = | flags |
| R1 | = | Font Dbox object id |
| R2 | = | 5 |
| R3 | = | pointer to 'try' string to use |
| R1-R9 preserved |
This method sets the string used in the Try writable field of a Font Dialogue box. If the string is longer than 64 characters, an error is returned.
extern _kernel_oserror *fontdbox_set_try_string ( unsigned int flags,
ObjectId fontdbox,
char *try_string
);
| R0 | = | flags |
| R1 | = | Font Dbox object id |
| R2 | = | 6 |
| R3 | = | pointer to buffer to hold try string |
| R4 | = | buffer size for try string |
| R4 | = | size of buffer required (if R3 was 0) else buffer pointed at by R3 holds try string R4 holds number of bytes written to buffer |
This method returns the string currently displayed in the Try writable field of the Font Dialogue box.
extern _kernel_oserror *fontdbox_get_try_string ( unsigned int flags,
ObjectId fontdbox,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Font Dbox object id |
| R2 | = | 7 |
| R3 | = | pointer to text string to use |
| R1-R9 preserved |
This method sets the text which is to be used in the title bar of the given Font dialogue box.
extern _kernel_oserror *fontdbox_set_title ( unsigned int flags,
ObjectId fontdbox,
char *title
);
| R0 | = | flags |
| R1 | = | Font Dbox object id |
| R2 | = | 8 |
| R3 | = | pointer to buffer to return the text in (or 0) |
| R4 | = | size of buffer |
| R4 | = | the size of buffer required to hold the text (if R3 was 0) else Buffer pointed to by R3 contains title text R4 holds number of bytes written to buffer |
This method returns the text string used in a Font dialogue's title bar.
extern _kernel_oserror *fontdbox_get_title ( unsigned int flags,
ObjectId fontdbox,
char *buffer,
int buff_size,
int *nbytes
);
There are a number of Toolbox events which are generated by the Font Dialogue box module.
| + 8 | 0x82a00 |
| + 12 | flags (as passed in to Toolbox_ShowObject) |
| + 16 | value which will be passed in R2 to ToolBox_ShowObject |
| + 20... | block which will be passed in R3 to ToolBox_ShowObject for the underlying dialogue box |
This Toolbox Event is raised when SWI Toolbox_ShowObject has been called for a Font Dialogue Box object. It gives the application the opportunity to set the selected font before the dialogue box actually appears on the screen.
typedef struct
{
ToolboxEventHeader hdr;
int show_type;
union
{
TopLeft pos;
WindowShowObjectBlock full;
} info;
} FontDboxAboutToBeShownEvent;
| + 8 | 0x82a01 |
| + 12 | flags |
This Toolbox Event is raised after the Font Dialogue object has been hidden, either by a Cancel click, or by a click on Apply. It allows the client to tidy up its own state associated with this dialogue.
Note that if the dialogue was cancelled, a font selection may still have been made, for example if the user clicked Adjust on Apply, and then cancelled the dialogue.
typedef struct
{
ToolboxEventHeader hdr;
} FontDboxDialogueCompletedEvent;
| + 8 | 0x82a02 |
| + 16 | font height |
| + 20 | aspect ratio |
| + 24... | font id |
This Toolbox Event informs the client that a Font Dialogue box selection has been made.
The special font id SystemFont is used to indicate that the System entry is selected.
typedef struct
{
ToolboxEventHeader hdr;
unsigned int height;
unsigned int aspect;
char font[208];
} FontDboxApplyFontEvent;
The layout of a Font Dialogue box template is shown below. Fields which have types MsgReference and StringReference are those which will require relocation when they are loaded from a resource file. If the template is being constructed in memory, then these fields should be real pointers (i.e. they do not require relocation).
For more details on relocation, see Resource File Formats.
| Field | Size in bytes | Type |
|---|---|---|
| flags | 4 | word |
| title | 4 | MsgReference |
| max_title | 4 | word |
| initial_font | 4 | StringReference |
| initial_height | 4 | word |
| initial_aspect | 4 | word |
| try_string | 4 | MsgReference |
| window | 4 | StringReference |
The Window object used to implement a Font Dialogue has the following characteristics. These must be reproduced if the Window is replaced by a client-specified alternative Window template:
Title bar must be indirected.
Component ids are derived by adding to 0x82a000
| Component id | Details | |
|---|---|---|
| 0 | action button (Apply) | must be marked as the 'default' action button |
| 1 | action button (Cancel) | must be marked as the 'cancel' action button |
| 2 | action button (Try) | must be marked as a 'local' action button |
| 3 | writable field (Try string) | buffer must be 64 bytes |
| 4 | number range (Aspect ratio) | |
| 5 | number range (Height) | |
| 6-15 | action buttons (Standard sizes) | these should all be local action buttons containing the text 8, 10 12, 14, 18, 24, 28, 36, 48 72 respectively. |
| 16 | string set (Style) | non-writable, with pop-up menu |
| 17 | string set (Weight) | non-writable, with pop-up menu |
| 18 | string set (Font) | non-writable, with pop-up menu |
| 19 | label box (Font) | |
| 20 | label box (Style) | |
| 21 | label (Height) | |
| 22 | label (Aspect) | |
| 23 | label (%) | |
| 24 | label (Font) | |
| 25 | label (Weight) | |
| 26 | label (Style) | |
The Font Dialogue box class responds to certain Wimp events and takes the actions as described below:
| Wimp event | Action |
|---|---|
| Mouse Click | on Apply, deliver a FontDbox_ApplyFont event
on Cancel, deliver a FontDbox_DialogueCompleted event on one of the pop-up menu buttons, a menu is displayed on one of the 'standard sizes', this size is entered into the Height writable field on one of the arrow keys, increment/decrement the value of its associated writable field (either height or aspect ratio) |
| Key Pressed | if Return then act as if Apply button had been clicked
if Escape, then act as if Cancel button had been clicked |