RISCOS.com

www.riscos.com Technical Support:
Toolbox

 


Colour Menu class


A Colour Menu object is used to show a menu giving the 16 desktop colours (and an optional None entry), and to allow the user to select one of these colours by clicking on its menu entry.

User interface

The Colour Menu allows the user to select from the set of available desktop colours (and an optional None entry which appears at the bottom). The menu is displayed showing the 16 desktop colours. Optionally any one of the colours can be shown as selected (with a tick against it).

COLMENU-2.PNG

When a hit is received for the Colour Menu, a Toolbox event is returned to the client. This contains the colour number of the selected colour. The selected colour is shown as ticked in the Colour Menu, when the menu is next shown (or immediately if Adjust is held down).

Application Program Interface

Attributes

A Colour Menu object has the following attributes which are specified in its object template and can be manipulated at run-time by the client application:

Attribute Description
flags word Bit Meaning
0 when set, this bit indicates that a ColourMenu_AboutToBeShown event should be raised when SWI Toolbox_ShowObject is called for this Colour Menu
1 when set, this bit indicates that a ColourMenu_HasBeenHidden event should be raised when the Menu has been removed from the screen
2 when set, include a None entry in the menu (will appear with None as its last entry)
menu title this gives an alternative string to use instead of the string 'Colour' in the title bar of the menu
max title length this gives the maximum length in bytes of title text which will be used for this Colour Menu.
colour this is an indication of which colour is selected when the Colour Menu is first created. Possible values are:
0-15 for the desktop colours
16 for 'None'
-1 to indicate that no colour should be selected
Manipulating a Colour Menu object
Creating and deleting a Colour Menu

A Colour Menu object is created using SWI Toolbox_CreateObject.

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

A Colour Menu object is deleted using SWI Toolbox_DeleteObject.

The setting of the non-recursive delete bit does not have a meaning for Colour menus.

Showing a Colour Menu

When a Colour menu 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 menu is shown

When the client calls Toolbox_ShowObject, a ColourMenu_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 colours should be shown as the currently selected one, when it receives this event.

Setting and getting the selected colour

For a Colour Menu, one of the colour entries can be designated the selected colour (indicated by a tick against it in the menu). Colours within the menu are numbered like the Wimp colours from 0-15 (with 16 meaning 'None', and -1 meaning 'nothing selected').

The currently selected colour entry can be set and read dynamically using the ColourMenu_SetColour/ColourMenu_GetColour methods.

Note that when the user clicks on a colour entry, that will become the selected colour automatically without calling ColourMenu_SetColour. As will be seen later, a user click results in a Toolbox event being delivered to the client, indicating which colour was selected.

The client can dynamically set whether a None entry is given, by using the ColourMenu_SetNoneAvailable method (and read whether it is available using the ColourMenu_GetNoneAvailable method).

Processing a colour selection

Whenever the user clicks on a colour entry a ColourMenu_Selection Toolbox event is raised to indicate which colour was chosen (one of 0-15, or 16 to indicate 'None').

Getting the underlying menu object id

The object id of the underlying menu object used to implement a Colour Menu can be obtained using the ColourMenu_GetMenuID method (normally you would not need to do this).

Colour Menu methods

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

R0 holding a flags word
R1 being a Colour Menu id
R2 being the method code which distinguishes this method
R3-R9 potentially holding method-specific data.
ColourMenu_SetColour 0
On entry
R0 flags
R1 Colour Menu object id
R2 0
R3 Wimp colour (0-15, or 16 for 'None', or -1 for 'nothing selected')
On exit
R1-R9 preserved
Use

This method selects a colour as being the currently selected one for this Colour Menu, and places a tick next to it. Note that this change will only be visible when the Colour Menu is next shown.

C veneer

extern _kernel_oserror *colourmenu_set_colour ( unsigned int flags,
                                                ObjectId colourmenu,
                                                int wimp_colour
                                              );

ColourMenu_GetColour 1
On entry
R0 = flags
R1 = Colour Menu object id
R2 = 1
On exit
R0 = Wimp colour selected (0-15, or 16 for 'None', or -1 for 'nothing selected')
Use

This method returns the Wimp colour which is currently selected for this Colour Menu.

C veneer

extern _kernel_oserror *colourmenu_get_colour ( unsigned int flags,
                                                ObjectId colourmenu,
                                                int *wimp_colour
                                              );

ColourMenu_SetNoneAvailable 2
On entry
R0 = flags
R1 = Colour Menu object id
R2 = 2
R3 = non-zero means allow a 'None' entry
On exit
R1-R9 preserved
Use

This method sets whether there is a 'None' entry for this Colour Menu.

C veneer

extern _kernel_oserror *colourmenu_set_none_available ( unsigned int flags,
                                                        ObjectId colourmenu,
                                                        int none
                                                      );

ColourMenu_GetNoneAvailable 3
On entry
R0 = flags
R1 = Colour Menu object id
R2 = 3
On exit
R0 = non-zero means there is a 'None' entry
Use

This method returns whether this Colour Menu has a 'None' entry.

C veneer

extern _kernel_oserror *colourmenu_get_none_available ( unsigned int flags,
                                                        ObjectId colourmenu,
                                                        int *none
                                                      );

ColourMenu_SetTitle 4
On entry
R0 = flags
R1 = Colour Menu object id
R2 = 4
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 Colour Menu.

C veneer

extern _kernel_oserror *colourmenu_set_title ( unsigned int flags,
                                               ObjectId colourmenu,
                                               char *title
                                             );

ColourMenu_GetTitle 5
On entry
R0 = flags
R1 = Colour Menu object id
R2 = 5
R3 = pointer to buffer to return the text in (or 0)
R4 = size of buffer
On exit
R4 = 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 Colour Menu's title bar.

C veneer

extern _kernel_oserror *colourmenu_get_title ( unsigned int flags,
                                               ObjectId colourmenu,
                                               char *buffer,
                                               int buff_size,
                                               int *nbytes
                                             );

Colour Menu events

There are a number of Toolbox Events which are generated by the Colour Menu module:

ColourMenu_AboutToBeShown (0x82980)
Block
+ 8 0x82980
+ 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 Menu object
Use

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

C data type

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

ColourMenu_HasBeenHidden (0x82981)
Block
+ 8 0x82981
Use

This Toolbox Event is raised by the Toolbox when Toolbox_HideObject is called on a Colour 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;
} ColourMenuHasBeenHiddenEvent;

ColourMenu_Selection (0x82982)
Block
+ 8 0x82982
+ 16 Wimp colour selected (0-15, or 16 for 'None')
Use

This Toolbox event is raised when the user has clicked on one of the Colour entries in the Colour Menu. The colour value returned is in the range 0-15 for the desktop colours, or 16 for 'None'.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  int                colour;
} ColourMenuSelectionEvent;

Colour Menu templates

The layout of a Colour 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
title 4 MsgReference
max-title 4 word
colour 4 word

Colour Menu Wimp event handling

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

Wimp event Action
Menu Selection The colour number corresponding to the menu selection is sent back to the client via a ColourMenu_Selection 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 Colour Menu object)

If a help message is attached to this Colour Menu, then a reply is sent on the application's behalf.

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