RISCOS.com

www.riscos.com Technical Support:
Toolbox

 


Font Menu class


A Font Menu is a menu which shows the currently selected font, and allows the user to set this from a list of font names, and submenus which give styles and weights.

User interface

A typical Font Menu might look as follows:

FONTMENU-2.GIF

When a hit is received for the Font Menu, it is decoded by the Font Menu module, and a Toolbox event is returned to the client. This contains the font id of the selected font (see SWI Font_DecodeMenu). The chosen font is shown as ticked in the font menu when the menu is next shown (or immediately if Adjust is held down).

Application Program Interface

The RISC OS Font manager provides a facility of building a font menu from the current fontlist.

A Font Menu object is an abstraction on this facility. A Font Menu is built for the client using the Font manager.

Attributes

A Font Menu 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 FontMenu_AboutToBeShown event should be raised when SWI Toolbox_ShowObject is called for this object
1 when set, this bit indicates that a FontMenu_HasBeenHidden event should be raised when the Font Menu object has been removed from the screen
2 when set, include a System font entry at head of menu
ticked_font font id of the font to tick in the Font Menu when it is first created

The special font id 'SystemFont' is used to indicate that the System entry should be ticked.

Manipulating a Font Menu object
Creating and deleting a Font Menu object

A Font Menu object is created using SWI Toolbox_CreateObject.

When this object is created it has no attached objects (see Attached objects).

A Font Menu object is deleted using SWI Toolbox_DeleteObject.

The setting of the non-recursive delete bit does not have a meaning for Font Menu objects.

Showing a Font Menu object

When a Font Menu object is displayed on the screen using SWI Toolbox_ShowObject it has the following behaviour:

Show type Position
0 (default) 64 OS units to the left of the mouse pointer
1 (full spec) R3 + 0 gives x coordinate of top-left corner of Menu
R3 + 4 gives y coordinate of top-left corner of Menu
2 (topleft) R3 + 0 gives x coordinate of top-left corner of Menu
R3 + 4 gives y coordinate of top-left corner of Menu
Before the Font Menu is shown

When the client calls Toolbox_ShowObject, a FontMenu_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.

Selecting a font

The currently selected font is shown ticked in the Font Menu. The selected font can be set using FontMenu_SetFont, and can be read using FontMenu_GetFont. Note that the string passed to these methods is the font id, not the translated string.

Receiving a font selection

When the user makes a Font selection from the Font Menu, a FontMenu_FontSelection Toolbox event is raised. This gives the font id of the font which has been chosen from the Font Menu.

Font Menu methods

The following methods are all invoked by calling SWI Toolbox_MiscOp with:

R0 holding a flags word
R1 being a Font Menu id
R2 being the method code which distinguishes this method
R3-R9 potentially holding method-specific data
FontMenu_SetFont 0
On entry
R0 = flags
R1 = Font Menu object id
R2 = 0
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 Menu, and places a tick next to it. The special font id 'SystemFont' is used to indicate that the System entry should be ticked.

C veneer

extern _kernel_oserror *fontmenu_set_font ( unsigned int flags,
                                            ObjectId fontmenu,
                                            char *font_id
                                          );


FontMenu_GetFont 1
On entry
R0 = flags
R1 = Font Menu object id
R2 = 1
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 FontMenu_SetFont call, or was last chosen by a user mouse click (i.e. the one which is ticked). The special font id 'SystemFont' is used to indicate that the System entry was last chosen.

C veneer

extern _kernel_oserror *fontmenu_get_font ( unsigned int flags,
                                            ObjectId fontmenu,
                                            char *buffer,
                                            int buff_size,
                                            int *nbytes
                                          );


Font Menu events

There are a number of Toolbox events which are generated by the Font Menu module:

FontMenu_AboutToBeShown (0x82a40)
Block
+ 8 0x82a40
+ 12 flags (as passed in to Toolbox_ShowObject)
+ 16 value which will be passed in R2 to ToolBox_ShowObject
+ 20... lock which will be passed in R3 to ToolBox_ShowObject for the underlying Menu Object
Use

This Toolbox event is raised when SWI Toolbox_ShowObject has been called for a Font Menu object. It gives the application the opportunity to set the selected font before the Menu actually appears on the screen.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  int                show_type;
  TopLeft            pos;
} FontMenuAboutToBeShownEvent;


FontMenu_HasBeenHidden (0x82a41)
Block
+ 8 0x82a41
Use

This Toolbox Event is raised by the Toolbox when Toolbox_HideObject is called on a Font Menu which has the appropriate bit set in its template flags word. It enables a client application to clear up after a menu has been closed. It is also raised when clicking outside a menu or hitting Escape.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
} FontMenuHasBeenHiddenEvent;


FontMenu_FontSelection (0x82a42)
Block
+ 8 0x82a42
+ 16... font id
Use

This Toolbox Event informs the client that a Font Menu selection has been made.

The special font id 'SystemFont' is used to indicate that the System entry was last chosen.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  char               font_id[216];
} FontMenuSelectionEvent;


Font Menu templates

The layout of a Font Menu 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
ticked_font 4 StringReference

Font Menu Wimp event handling

The Font Menu class responds to certain Wimp events and takes the actions as described below:

Wimp event Action
Menu Selection The font id corresponding to the menu selection is sent back to the client via a FontMenu_FontSelection event.

If Adjust is held down, then the currently open Menu is re-opened in the same place.

User Msg Message_HelpRequest (while the pointer is over a Font Menu object) A reply is sent on the application's behalf.

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