|
www.riscos.com Technical Support: |
A menu should appear on the screen either when the user clicks the Menu mouse button, or clicks on a Pop-up menu button. The menu will disappear again when the user clicks outside the menu or presses Escape (or the client application hides it or the user opens another menu).
When the user clicks on a menu entry the client application will typically perform some task. The menu will then disappear, unless the selection was made using the Adjust button in which case it will persist on the screen.
When a Menu object is created, the Toolbox deals with ensuring that the colours used for the Menu are Style Guide compliant. Each menu entry is set with a height of 44 OS units (or 68 if it has a dotted line separator), and the width of the menu is calculated from details of its entries on the application's behalf.
The Menu module deals with keeping the menu tree displayed when a selection is made with Adjust.
A 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 an event should be raised when SWI Toolbox_ShowObject is called for this Menu. | |
| 1 | when set, this bit indicates that an event should be raised when the Menu has been removed from the screen. | |
| menu title | gives a text string which will appear in the menu's title bar
(0 means no title, an empty string means no titlebar) | |
| max title length | gives the maximum length in bytes of title text which will be used for this Menu. | |
| help message | when a HelpRequest message is received on this menu, then this text message is sent in a HelpReply message. Note that this help message is only sent if the menu entry for which the request was received has not got a help message of its own. | |
| max help length | gives the maximum length in bytes of help text which will be used for this Menu. | |
| show event | this is a Toolbox event code which will be raised when SWI Toolbox_ShowObject is called for this menu.
If its value is -1, then the default Menu_AboutToBeShown event is raised. An event is only raised if the appropriate bit is set in the menu's flags word. | |
| hide event | this is a Toolbox event code which will be raised when this menu has been removed from the screen (either as a result of an explicit call to SWI Toolbox_HideObject or because the Wimp has removed the menu).
If its value is -1, then the default Menu_HasBeenHidden event is raised. An event is only raised if the appropriate bit is set in the menu's flags word. | |
A Menu also has a list of 'entries'. Each entry has its own component id which uniquely identifies it within this menu. An entry has the following attributes:
| Attribute | Description | |
|---|---|---|
| flags | Bit | Meaning |
| 0 | when set, this entry is ticked. | |
| 1 | when set, this entry has a dotted line immediately after it. | |
| 2-7 | must be 0. | |
| 8 | when set, this entry is faded. | |
| 9 | when set, this entry is a sprite (default is a text menu entry). | |
| 10 | when set, this entry has a submenu (ie a submenu arrow appears next to the entry). | |
| 11 | when set, an event (either Menu_SubMenu or client-specified) is raised when the user traverses this entry's submenu arrow with the mouse pointer (if bit 10 is set). | |
| 12 | when set, if there is an object to be shown when this entry is selected, then it will be shown with Wimp_CreateMenu semantics. The default is to show persistently. | |
| component id | identifies this entry uniquely within this menu. -1 and -2 are invalid component ids | |
| text | depending on whether this is a text or sprite entry (as indicated by bit 9 of the flags word), this is either:
| |
| max length | gives the maximum length in bytes of entry text or sprite name | |
| click show | the name of the template for an object to show, when the user clicks on this entry.
0 means there is no object to be shown | |
| submenu show | the name of the template for an object to show, when the user moves the pointer over the submenu arrow (if the entry has a submenu).
0 means there is no object to be shown | |
| submenu event | a Toolbox event code which will be raised when the user moves the pointer over the submenu arrow (if the entry has a submenu and bit 11 of the flags word is set)
if its value is 0 then the default Menu_Submenu event is raised | |
| click event | a Toolbox event code which will be raised when the user clicks on this entry
if its value is 0 then the default Menu_Selection event is raised | |
| help message | when a HelpRequest message is received on this entry of this menu then this text string is sent in a HelpReply message
0 means that the help message for the menu will be sent (if such exists) | |
| max help length | gives the maximum length in bytes of the entry's help message | |
Since there can only be one Menu visible on the screen at any one time, it is usual for the client application to mark Menu templates as 'shared' so that only one copy will exist in memory. The application receives a Menu_AboutToBeShown Toolbox event just before the Menu is shown, to allow it to set any attributes like ticks and fades, which may differ depending on where the Menu is being shown; for example, in a multi-document editor a single menu can be maintained for all document Windows; when the Toolbox receives a Menu button click event from the Wimp, it will show the Menu associated with the Window over which the mouse click occurred; when the application receives the Menu_AboutToBeShown Toolbox event, it can tick and fade entries in the Menu depending on the state of the document Window.
Another alternative for supporting multi-document editors is to create a Menu object for each Window object. In this case it will not be necessary to use the Menu_AboutToBeShown Toolbox event to make last minute changes to the menu, since these can be made on a per-window basis as the changes occur. Whether this method is used, or the above 'shared' scheme is really one of personal taste, and memory usage.
It is possible to associate a client handle with a Menu using the Toolbox_SetClientHandle method, but normally an application will simply wish to use the client handle of the object to which a Menu is attached (via the parent_id or the ancestor_id in the id block).
A Menu object is created using SWI Toolbox_CreateObject.
When a Menu object is created, the following attached objects (see Attached objects) are also created for each menu entry for which they are defined:
The Menu entry attributes table on Menu entry attributes describes these objects.
Attached objects are also created when a menu entry is added to the Menu, if they are referenced by the menu entry (and deleted when the menu entry is removed).
A Menu object is deleted using SWI Toolbox_DeleteObject. If it has any attached objects these are also deleted, unless the non-recursive bit is set for this SWI.
Note: Menus must not be mutually recursive (i.e. in a menu hierarchy, a menu entry may not have, as a submenu, a menu further up the hierarchy). The menu module does not check for such a case, so it is the client application's responsibility to check for correctness.
When a 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 | |
The client application should not need to make this call, since it is made automatically by the Window and Iconbar modules for objects which have a Menu attached to them.The Window module will display the menu in its default place when the Menu button is clicked, or in the case of a pop-up menu directly to the right of the pop-up icon; the Iconbar module displays the menu with its base 96 OS units from the bottom of the screen, and 64 OS units to the right of the mouse pointer.
Normally the set of entries in a Menu will be specified in the application's resource file. If, however, the application wishes to add and remove Menu entries dynamically at run-time, this is done using the Menu_AddEntry and Menu_RemoveEntry methods.
A given Menu entry can either contain text or a sprite. Normally these will be fixed when the menu is created, but they can be set and read dynamically using the Menu_SetEntryText, Menu_GetEntryText, Menu_SetEntrySprite, and Menu_GetEntrySprite methods.
Each Menu entry can be optionally 'ticked' (i.e. have a tick displayed to the left of it), and/or 'faded' (i.e. displayed in light grey, and unselectable).
A given Menu entry can be ticked/unticked, faded/unfaded using the Menu_SetTick/Menu_SetFade methods.
The client can determine the state of a particular entry using the Menu_GetTick/Menu_GetFade methods.
Normally an application's Menu structure is fully specified statically in its resource file, but occasionally an application may wish to build a submenu at run-time, and attach it at a particular point in the Menu tree.
This is achieved by creating the submenu object, and using the Menu_SetSubMenuShow method already mentioned (and detailed on Menu_SetSubMenuShow 8).
Each Menu entry can have a specified Toolbox event which will be raised when a menu selection is made on that entry (i.e. the Wimp has returned a Menu Selection event to the application).
Normally this Toolbox event is specified in the client application's resource file, but it can be read and set dynamically using the Menu_SetClickEvent and Menu_GetClickEvent methods.
The client can also specify the name of a template of an object which should be shown when the menu hit happens. The main use for this is to supply the name of the template of a persistent dialogue box, on a Menu entry with an ellipsis (...). The object is only shown after the 'Menu hit event' has been delivered to the client. The show type value passed in R2 to Toolbox_ShowObject will be 0 (default place).
It is possible to specify at run-time the object id of an object which should be shown when a Menu hit happens, using the Menu_SetClickShow method (and the object id can be read using the Menu_GetClickShow method).
If neither of the above is specified, then the Toolbox raises the Menu_Selection Toolbox event, as described on Menu_Selection (0x828c3). This Toolbox event reports which entry was selected.
When the user of the client application clicks Adjust on a Menu entry or on a Gadget in a dialogue box which has been opened from a Menu, it is conventional for the Menu tree to remain on the screen.
The Toolbox handles this automatically on behalf of the application, so the client does not have to look for Adjust clicks; the client's code just responds to the Toolbox events raised by the user's interaction with the Menu.
Note that the Toolbox 're-shows' the Menu when the application next calls SWI Wimp_Poll, after the Menu selection, so any ticking/fading etc of Menu entries, must be done in response to the Toolbox event which was raised when a menu selection was made.
Each Menu entry can have a specified Toolbox event which will be raised when the user moves the mouse pointer over the submenu arrow, which is displayed on all Menu entries which have a submenu.
Normally this Toolbox event is specified in the client application's resource file, but it can be read and set dynamically using the Menu_SetSubMenuEvent and Menu_GetSubMenuEvent methods.
The client can also specify the name of a template of an object which should be shown when the user moves the mouse pointer over the submenu arrow. The main use for this is to supply the name of the template of a transient dialogue box or a submenu. The object is only shown after the Menu_SubMenu event has been delivered to the client.
It is possible to specify at run-time the object id of an object which should be shown when the user moves the pointer over the submenu arrow, using the Menu_SetSubMenuShow method (and the object id can be read using the Menu_GetSubMenuShow method).
If neither of the above is specified, then the Toolbox raises the Menu_SubMenu Toolbox event. This Toolbox event reports the entry over which the mouse pointer has moved.
Each Menu has an optional Help Message associated with it. When the client application receives a HelpRequest for the Menu, the Toolbox replies automatically with this Help Message.
Normally the Menu's Help Message will be specified in the application's resource file, however the client can set and read the message dynamically using the Menu_SetHelpMessage/Menu_GetHelpMessage methods.
Each Menu entry can also have a Help Message. If no such message is specified, then the Toolbox will return the Menu's Help Message instead. Normally, again, an entry's Help Message will have been specified in the resource file, but it can be read and set using the Menu_SetEntryHelpMessage and Menu_GetEntryHelpMessage methods (described on Menu_SetEntryHelpMessage 18).
Writable menu entries as seen in older applications are not supported by the Toolbox as these are not Style Guide compliant. Instead you should use small dialogues. For example:
The following methods are all invoked by calling SWI Toolbox_MiscOp with:
| R0 | holding a flags word |
| R1 | being a Menu id |
| R2 | being the method code which distinguishes this method |
| R3-R9 | potentially holding method-specific data |
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 0 |
| R3 | = | component id of entry |
| R4 | = | value 0 means 'untick' non-zero means 'tick' |
| R1-R9 preserved |
This method affects the tick state of a Menu entry.
extern _kernel_oserror *menu_set_tick ( unsigned int flags,
ObjectId menu,
ComponentId entry,
int tick
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 0 |
| R3 | = | component id of entry |
| R0 | = | tick state non-zero means ticked 0 means unticked |
This method returns the tick state of a Menu entry.
extern _kernel_oserror *menu_get_tick ( unsigned int flags,
ObjectId menu,
ComponentId entry,
int *ticked
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 2 |
| R3 | = | component id of entry |
| R4 | = | value 0 means unfade non-zero means fade |
| R1-R9 preserved |
This method affects the fade state of a Menu entry.
extern _kernel_oserror *menu_set_fade ( unsigned int flags,
ObjectId menu,
ComponentId entry,
int fade
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 3 |
| R3 | = | component id of entry |
| R0 | = | fade state 0 means unfaded non-zero means faded |
This method returns the fade state of a Menu entry.
extern _kernel_oserror *menu_get_fade ( unsigned int flags,
ObjectId menu,
ComponentId entry,
int *faded
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 4 |
| R3 | = | component id of entry |
| R4 | = | pointer to text string to use |
| R1-R9 preserved |
This method sets the text which is to be used in the named text Menu entry.
An error is returned if the entry's text buffer is not large enough to hold the supplied text.
An error is returned if this SWI is called on an entry which is a sprite.
extern _kernel_oserror *menu_set_entry_text ( unsigned int flags,
ObjectId menu,
ComponentId entry,
char *text
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 5 |
| R3 | = | component id of entry |
| R4 | = | pointer to buffer to return the text in (or 0) |
| R5 | = | size of buffer |
| R5 | = | the size of buffer required to hold the text (if R4 was 0) else Buffer pointed to by R4 contains entry text R5 holds number of bytes written to buffer |
This method is used for a text Menu entry. It returns the text string displayed for that entry.
extern _kernel_oserror *menu_get_entry_text ( unsigned int flags,
ObjectId menu,
ComponentId entry,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 6 |
| R3 | = | component id of entry |
| R4 | = | pointer to name of sprite to use |
| R1-R9 preserved |
This method sets the sprite which is to be used in the named sprite Menu entry.
An error is returned if the entry's sprite name buffer is not large enough to hold the supplied sprite name.
An error is returned if this SWI is called on a text entry.
extern _kernel_oserror *menu_set_entry_sprite ( unsigned int flags,
ObjectId menu,
ComponentId entry,
char *sprite_name
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 7 |
| R3 | = | component id of entry |
| R4 | = | pointer to buffer to return the sprite name in (or 0) |
| R5 | = | size of buffer |
| R5 | = | the size of buffer required to hold the sprite name (if R4 was 0) else Buffer pointed to by R4 contains sprite name R5 holds number of bytes written to buffer |
This method is used for a sprite Menu entry. It returns the name of the sprite displayed for that entry.
extern _kernel_oserror *menu_get_entry_sprite ( unsigned int flags,
ObjectId menu,
ComponentId entry,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 8 |
| R3 | = | component id of entry where submenu should be attached |
| R4 | = | object id of the submenu (or 0) |
| R1-R9 preserved |
This method allows the client to specify the object id of an object to show when the user moves the pointer over the submenu arrow.
If R4 is 0, then no object should be shown.
Calling this SWI also causes the submenu to be shown or hidden as appropriate.
extern _kernel_oserror *menu_set_sub_menu_show ( unsigned int flags,
ObjectId menu,
ComponentId entry,
ObjectId sub_menu
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 9 |
| R3 | = | component id |
| R0 | = | id of object to be shown |
This method returns the object id of the object which will be shown when the user moves the pointer over the submenu arrow.
extern _kernel_oserror *menu_get_sub_menu_show ( unsigned int flags,
ObjectId menu,
ComponentId entry,
ObjectId *sub_menu
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 10 |
| R3 | = | component id of entry |
| R4 | = | Toolbox event code to raise |
| R1-R9 preserved |
This method specifies a Toolbox event to be raised when the user moves the mouse over this entry's submenu arrow.
If R4 is 0, then a Menu_SubMenu Toolbox event will be raised instead.
Calling this SWI also causes the submenu to be shown or hidden as appropriate.
extern _kernel_oserror *menu_set_sub_menu_event ( unsigned int flags,
ObjectId menu,
ComponentId entry,
int toolbox_event
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 11 |
| R3 | = | component id of entry |
| R4 | = | Toolbox event code |
This method reads the Toolbox event to be raised when the user moves the mouse over this entry's submenu arrow.
If no event has been specified, then 0 is returned.
extern _kernel_oserror *menu_get_sub_menu_event ( unsigned int flags,
ObjectId menu,
ComponentId entry,
int *toolbox_event
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 12 |
| R3 | = | component id of entry |
| R4 | = | object id to show |
| R5 | = | show flags: bit 0 if clear show persistently if set show transiently |
| R1-R9 preserved |
This method allows the client to specify the object id of an object to show when the user selects this Menu entry. By setting bit 0 of R5 it is possible to control whether the show is persistent or not.
If R4 is 0, then no object should be shown.
extern _kernel_oserror *menu_set_click_show ( unsigned int flags,
ObjectId menu,
ComponentId entry,
ObjectId object,
int show_flags
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 13 |
| R3 | = | component id |
| R0 | = | id of object to be shown |
| R1 | = | show flags |
This method returns the object id of the object which will be shown when the user selects this Menu entry. If bit 0 of R1 is set on exit, it means that the object will be shown transiently.
If no object has been specified, then 0 is returned in R0.
extern _kernel_oserror *menu_get_click_show ( unsigned int flags,
ObjectId menu,
ComponentId entry,
ObjectId *object,
int *show_flags
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 14 |
| R3 | = | component id of entry |
| R4 | = | Toolbox event code to raise |
| R1-R9 preserved |
This method specifies a Toolbox event to be raised when the user selects the given Menu entry.
If R4 is 0, then a Menu_Selection Toolbox event will be raised instead.
extern _kernel_oserror *menu_set_click_event ( unsigned int flags,
ObjectId menu,
ComponentId entry,
int toolbox_event
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 15 |
| R3 | = | component id of entry |
| R4 | = | Toolbox event code |
This method reads the Toolbox event to be raised when the user selects the given Menu entry.
If no event has been specified, then 0 is returned.
extern _kernel_oserror *menu_get_click_event ( unsigned int flags,
ObjectId menu,
ComponentId entry,
int *toolbox_event
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 16 |
| R3 | = | pointer to message text |
| R1-R9 preserved |
This method is used to set the help message which will be returned when a Help Request message is received for this Menu object. The Toolbox handles the reply message for you.
If R3 is 0, then the Help Message for this Menu is detached.
extern _kernel_oserror *menu_set_help_message ( unsigned int flags,
ObjectId menu,
char *help_message
);
| R1 | = | Menu object id |
| R2 | = | 17 |
| R3 | = | pointer to buffer |
| R4 | = | size of buffer to hold message text |
| R4 | = | size of buffer required for message text (if R3 was 0) else Buffer pointed at by R3 holds message text R4 holds number of bytes written to buffer |
This method is used to read the help message which will be returned when a Help Request message is received for this Menu object.
extern _kernel_oserror *menu_get_help_message ( unsigned int flags,
ObjectId menu,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 18 |
| R3 | = | component id of entry |
| R4 | = | pointer to message text |
| R1-R9 preserved |
This method is used to set the help message which will be returned when a Help Request message is received for this Menu entry. The Toolbox handles the reply message for you.
If R4 is 0, then the Help Message for this Menu entry is detached.
extern _kernel_oserror *menu_set_entry_help_message ( unsigned int flags,
ObjectId menu,
ComponentId entry,
char *help_message
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 19 |
| R3 | = | component id of entry |
| R4 | = | pointer to buffer |
| R5 | = | size of buffer to hold message text |
| R5 | = | size of buffer required for message text (if R4 was 0) else Buffer pointed at by R4 holds message text R5 holds number of bytes written to buffer |
This method is used to read the help message which will be returned when a Help Request message is received for this Menu object.
extern _kernel_oserror *menu_get_entry_help_message ( unsigned int flags,
ObjectId menu,
ComponentId entry,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags (bit 0 set means add the entry before the specified entry) |
| R1 | = | Menu object id |
| R2 | = | 20 |
| R3 | = | component id of entry after/before which to add this entry (or -1 to mean at the beginning, -2 to mean at the end) |
| R4 | = | pointer to buffer containing a description of the new entry |
| R0 | = | component id of added entry |
| R1-R9 preserved | ||
This method adds a new Menu entry at the specified place in the Menu. The description of the Menu entry should have a format as specified under the Menu Templates section.
By default the entry is added after the specified entry whose id is passed in R3, but the client can specify that it is added before that entry, by setting bit 0 of the flags word.
If the component id in the template of the Menu entry was specified as -1, then the Toolbox uses the lowest numbered component id available for this Menu.
extern _kernel_oserror *menu_add_entry ( unsigned int flags,
ObjectId menu,
ComponentId at_entry,
char *entry_description,
ComponentId *new_entry
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 21 |
| R3 | = | component id of the entry |
| R1-R9 preserved |
This method removes a Menu entry
extern _kernel_oserror *menu_remove_entry ( unsigned int flags,
ObjectId menu,
ComponentId entry
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 22 |
| R0 | = | height of menu work area in OS Units |
| R1-R9 preserved | ||
This method returns the height of the work area of the given Menu (in OS Units). It takes into account whether items in the Menu have dashed line separators. This can be used to accurately position the Menu in a call to Toolbox_ShowObject.
extern _kernel_oserror *menu_get_height ( unsigned int flags,
ObjectId menu,
int *height
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 23 |
| R0 | = | width of menu work area in OS Units |
| R1-R9 preserved | ||
This method returns the width of the work area of the given Menu (in OS Units).
extern _kernel_oserror *menu_get_width ( unsigned int flags,
ObjectId menu,
int *width
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 24 |
| 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 Menu. Note that this has no immediate effect if the Menu is currently being displayed.
extern _kernel_oserror *menu_set_title ( unsigned int flags,
ObjectId menu,
char *title
);
| R0 | = | flags |
| R1 | = | Menu object id |
| R2 | = | 25 |
| 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 Menu's title bar.
extern _kernel_oserror *menu_get_title ( unsigned int flags,
ObjectId menu,
char *buffer,
int buff_size,
int *nbytes
);
| + 8 | 0x828c0 (or client specified event - see Menu Templates) |
| + 12 | flags (as passed in to Toolbox_ShowObject) |
| + 16 | value as passed in R2 to ToolBox_ShowObject |
| + 20... | block as passed in R3 to ToolBox_ShowObject |
This Toolbox event is raised due to a call to SWI Toolbox_ShowObject on a Menu object which has bit 0 of its flags word set. It gives the application the opportunity to tick, fade or change the text/sprite of any Menu entries before the Menu actually appears on the screen.
This is useful where a shared Menu is being used by many Window objects, each of which has a state which is reflected in the Menu state.
typedef struct
{
ToolboxEventHeader hdr;
int show_type;
TopLeft pos;
} MenuAboutToBeShownEvent;
| + 8 | 0x828c1 (or client specified event - see Menu Templates) |
This Toolbox event is raised by the Toolbox when Toolbox_HideObject is called on a 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;
} MenuHasBeenHiddenEvent;
| + 8 | 0x828c2 |
| + 16 | x coordinate where the submenu will be shown |
| + 20 | y coordinate where the submenu will be shown |
This Toolbox event is raised when the user moves the mouse over a Menu entry's submenu arrow, and the client application has not associated any other Toolbox event with this event. The event is only delivered if the appropriate bit is set in the menu entry's flags word.
This Toolbox event is raised by the Menu class.
typedef struct
{
ToolboxEventHeader hdr;
TopLeft pos;
} MenuSubMenuEvent;
| + 8 | 0x828c3 |
This Toolbox event is raised when the user makes a selection on a Menu object, and the client application has not associated any other Toolbox event with this event.
This Toolbox event is raised by the Menu class.
typedef struct
{
ToolboxEventHeader hdr;
} MenuSelectionEvent;
The layout of a 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).
The current version for Menu templates is 102.
For more details on relocation, see Resource File Formats.
| Field | Size in bytes | Type |
|---|---|---|
| flags | 4 | word |
| title | 4 | MsgReference |
| max_title | 4 | word |
| help_message | 4 | MsgReference |
| max_help | 4 | word |
| show_event | 4 | word |
| hide_event | 4 | word |
| num_entries | 4 | word |
Followed by a list of menu entries, where each entry is:
| Field | Size in bytes | Type |
|---|---|---|
| flags | 4 | word |
| component_id | 4 | word |
| text | 4 | MsgReference or StringReference |
| max_text | 4 | word |
| click_show | 4 | StringReference |
| submenu_show | 4 | StringReference |
| submenu_event | 4 | word |
| click_event | 4 | word |
| help_message | 4 | MsgReference |
| max_entry_help | 4 | word |
The Menu class responds to certain Wimp events and takes the actions as described below:
| Wimp event | Action |
|---|---|
| Menu Selection | If there is a click event associated with the given Menu entry, then that Toolbox event is raised;
If Adjust is held down, then the currently open Menu is re-opened in the same place. |
| Mouse Click | (on a dialogue box attached to the Menu) 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 Menu object) If a help message is attached to this Menu or Menu entry, then a reply is sent on the application's behalf. Message_MenuWarning
Message_MenusDeleted |