|
www.riscos.com Technical Support: |
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).
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).
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 | |
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.
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 |
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.
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).
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').
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).
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. |
| R0 | flags | |
| R1 | Colour Menu object id | |
| R2 | 0 | |
| R3 | Wimp colour (0-15, or 16 for 'None', or -1 for 'nothing selected') |
| R1-R9 preserved |
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.
extern _kernel_oserror *colourmenu_set_colour ( unsigned int flags,
ObjectId colourmenu,
int wimp_colour
);
| R0 | = | flags |
| R1 | = | Colour Menu object id |
| R2 | = | 1 |
| R0 | = | Wimp colour selected (0-15, or 16 for 'None', or -1 for 'nothing selected') |
This method returns the Wimp colour which is currently selected for this Colour Menu.
extern _kernel_oserror *colourmenu_get_colour ( unsigned int flags,
ObjectId colourmenu,
int *wimp_colour
);
| R0 | = | flags |
| R1 | = | Colour Menu object id |
| R2 | = | 2 |
| R3 | = | non-zero means allow a 'None' entry |
| R1-R9 preserved |
This method sets whether there is a 'None' entry for this Colour Menu.
extern _kernel_oserror *colourmenu_set_none_available ( unsigned int flags,
ObjectId colourmenu,
int none
);
| R0 | = | flags |
| R1 | = | Colour Menu object id |
| R2 | = | 3 |
| R0 | = | non-zero means there is a 'None' entry |
This method returns whether this Colour Menu has a 'None' entry.
extern _kernel_oserror *colourmenu_get_none_available ( unsigned int flags,
ObjectId colourmenu,
int *none
);
| R0 | = | flags |
| R1 | = | Colour Menu object id |
| R2 | = | 4 |
| 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 Colour Menu.
extern _kernel_oserror *colourmenu_set_title ( unsigned int flags,
ObjectId colourmenu,
char *title
);
| R0 | = | flags |
| R1 | = | Colour Menu object id |
| R2 | = | 5 |
| R3 | = | pointer to buffer to return the text in (or 0) |
| R4 | = | size of buffer |
| 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 |
This method returns the text string used in a Colour Menu's title bar.
extern _kernel_oserror *colourmenu_get_title ( unsigned int flags,
ObjectId colourmenu,
char *buffer,
int buff_size,
int *nbytes
);
There are a number of Toolbox Events which are generated by the Colour Menu module:
| + 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 |
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.
typedef struct
{
ToolboxEventHeader hdr;
int show_type;
TopLeft pos;
} ColourMenuAboutToBeShownEvent;
| + 8 | 0x82981 |
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.
typedef struct
{
ToolboxEventHeader hdr;
} ColourMenuHasBeenHiddenEvent;
| + 8 | 0x82982 |
| + 16 | Wimp colour selected (0-15, or 16 for 'None') |
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'.
typedef struct
{
ToolboxEventHeader hdr;
int colour;
} ColourMenuSelectionEvent;
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 |
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. |