RISCOS.com

www.riscos.com Technical Support:
Toolbox

 


Font Dialogue box class


A Font Dialogue box shows font, weight and style of the currently selected font, together with a chosen height and aspect ratio. The dialogue box also has a writable field in which a test string in the chosen font is displayed.

User interface

The Font Dialogue box can be broken down into the following components:

FONTDBOX-2.GIF

  • A boxed area for setting the font, which contains three labels giving the font's name, weight and style; with three accompanying string sets (each string set contains a display field and a pop-up menu, which gives viable values for these fields, based on the list of currently available fonts). The pop-up menus are built and processed by the Toolbox, and do not require (or allow) any client intervention. The Toolbox deals with ensuring that only valid font id's are available to be chosen.
  • Another boxed area, in which the user can set the height and aspect ratio used to plot the selected font. There are a number of standard sizes which can be chosen by clicking action buttons, and a number range into which a non-standard size can be entered. The aspect ratio used is specified by the contents of another number range.
  • At the bottom of the dialogue box, there is a writable field which by default contains the string, 'The quick brown fox jumps over the lazy dog'. When the user clicks on the Try button, this string is rendered in the selected font (and height and aspect ratio). The try string is limited to 64 characters long.
  • The user can cancel the dialogue by clicking on the Cancel action button, or can apply the font selection by clicking on Apply.

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

Application Program Interface

Attributes

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.
Manipulating a Font Dialogue object
Creating and deleting a Font Dialogue object

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.

Showing a Font Dialogue object

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
Before the Font Dialogue box is shown

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.

Setting and getting the current selection

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.

Receiving a font selection

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.

Completing a Font Dialogue

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.

Font Dialogue methods

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
FontDbox_GetWindowID 0
On entry
R0 = flags
R1 = FontDbox object id
R2 = 0
On exit
R0 = Window object id for this FontDbox object
Use

This method returns the id of the underlying Window object used to implement this FontDbox object.

C veneer

extern _kernel_oserror *fontdbox_get_window_id( unsigned int flags,
                                                ObjectId fontdbox,
                                                ObjectId *window
                                              );


FontDbox_SetFont 1
On entry
R0 = flags
R1 = Font Dbox object id
R2 = 1
R3 = pointer to font id of font to select (0 means none)
On exit
R1-R9 preserved
Use

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.

C veneer

extern _kernel_oserror *fontdbox_set_font ( unsigned int flags,
                                            ObjectId fontdbox,
                                            char *font_id
                                          );


FontDbox_GetFont 2
On entry
R0 = flags
R1 = Font Dbox object id
R2 = 2
R3 = pointer to buffer to hold font id
R4 = buffer size for font id
On exit
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
Use

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.

C veneer

extern _kernel_oserror *fontdbox_get_font ( unsigned int flags,
                                            ObjectId fontdbox,
                                            char *buffer,
                                            int buff_size,
                                            int *nbytes
                                          );


FontDbox_SetSize 3
On entry
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
On exit
R1-R9 preserved
Use

This method sets the height value and/or the aspect ratio displayed in the Font Dialogue box.

C veneer

extern _kernel_oserror *fontdbox_set_size ( unsigned int flags,
                                            ObjectId fontdbox,
                                            int height,
                                            int aspect_ratio
                                          );


FontDbox_GetSize 4
On entry
R0 = flags
R1 = Font Dbox object id
R2 = 4
On exit
R0 = height value
R1 = aspect ratio
Use

This method returns the height value and/or aspect ratio currently displayed in the Font Dialogue box.

C veneer

extern _kernel_oserror *fontdbox_get_size ( unsigned int flags,
                                            ObjectId fontdbox,
                                            int *height,
                                            int *aspect_ratio
                                          );


FontDbox_SetTryString 5
On entry
R0 = flags
R1 = Font Dbox object id
R2 = 5
R3 = pointer to 'try' string to use
On exit
R1-R9 preserved
Use

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.

C veneer

extern _kernel_oserror *fontdbox_set_try_string ( unsigned int flags,
                                                  ObjectId fontdbox,
                                                  char *try_string
                                                );


FontDbox_GetTryString 6
On entry
R0 = flags
R1 = Font Dbox object id
R2 = 6
R3 = pointer to buffer to hold try string
R4 = buffer size for try string
On exit
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
Use

This method returns the string currently displayed in the Try writable field of the Font Dialogue box.

C veneer

extern _kernel_oserror *fontdbox_get_try_string ( unsigned int flags,
                                                  ObjectId fontdbox,
                                                  char *buffer,
                                                  int buff_size,
                                                  int *nbytes
                                                );


FontDbox_SetTitle 7
On entry
R0 = flags
R1 = Font Dbox object id
R2 = 7
R3 = pointer to text string to use
On exit
R1-R9 preserved
Use

This method sets the text which is to be used in the title bar of the given Font dialogue box.

C veneer

extern _kernel_oserror *fontdbox_set_title ( unsigned int flags,
                                             ObjectId fontdbox,
                                             char *title
                                           );


FontDbox_GetTitle 8
On entry
R0 = flags
R1 = Font Dbox object id
R2 = 8
R3 = pointer to buffer to return the text in (or 0)
R4 = size of buffer
On exit
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
Use

This method returns the text string used in a Font dialogue's title bar.

C veneer

extern _kernel_oserror *fontdbox_get_title ( unsigned int flags,
                                             ObjectId fontdbox,
                                             char *buffer,
                                             int buff_size,
                                             int *nbytes
                                           );


Font Dialogue events

There are a number of Toolbox events which are generated by the Font Dialogue box module.

FontDbox_AboutToBeShown (0x82a00)
Block
+ 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
Use

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.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  int                show_type;
  union
  {
    TopLeft               pos;
    WindowShowObjectBlock full;
  } info;
} FontDboxAboutToBeShownEvent;


FontDbox_DialogueCompleted (0x82a01)
Block
+ 8 0x82a01
+ 12 flags
Use

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.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
} FontDboxDialogueCompletedEvent;


FontDbox_ApplyFont (0x82a02)
Block
+ 8 0x82a02
+ 16 font height
+ 20 aspect ratio
+ 24... font id
Use

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.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  unsigned int       height;
  unsigned int       aspect;
  char               font[208];
} FontDboxApplyFontEvent;


Font Dialogue Templates

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
Underlying Window template

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.

Gadgets

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)

Font Dialogue Wimp event handling

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

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