|
www.riscos.com Technical Support: |
An Iconbar object is normally used to show that an application is running, by placing an icon on the RISC OS Iconbar.
An Iconbar object can either be a sprite icon or a text&sprite icon. It does not appear on the Iconbar until the application has called Toolbox_ShowObject or if the auto-show bit has been set in its flags word. When the Toolbox places the icon on the Iconbar, it positions the icon in a Style Guide compliant manner, including placement of the text in a text&sprite icon. The bounding box used for the icon is taken from the sprite used for that icon, also taking into consideration the text used, if the iconbar object is text&sprite. If the application supports many icons on the Iconbar this can be achieved by creating many Iconbar objects.
The Toolbox supports handling of a Menu click over the icon, Select and Adjust clicks.
An Iconbar icon 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 | Bit | Meaning |
| 0 | when set, generate an Iconbar_SelectAboutToBeShown event before the object which has been associated with a Select click is shown | |
| 1 | when set, generate an Iconbar_AdjustAboutToBeShown event before the object which has been associated with an Adjust click is shown | |
| 2 | when set, show the select_show object as a transient (i.e. with the semantics of Wimp_CreateMenu) | |
| 3 | when set, show the adjust_show object as a transient (i.e. with the semantics of Wimp_CreateMenu) | |
| 4 | reserved | |
| 5 | when set, generate an Iconbar_Clicked (or client-specified) event when Select is clicked | |
| 6 | when set, generate an Iconbar_Clicked (or client-specified) event when Adjust is clicked | |
| position | a negative integer giving the position of the icon on the Iconbar (as specified in SWI Wimp_CreateIcon) | |
| priority | gives priority of this icon on the Iconbar (as specified in SWI Wimp_CreateIcon) | |
| sprite name | the name of the sprite to use for this Iconbar icon | |
| max sprite name | the maximum length of sprite name to be used | |
| text | an optional string which will be used for a Text&Sprite Iconbar icon (i.e. the text that will appear underneath the icon on the Iconbar) | |
| max text length | if the Iconbar icon has text, then this is a Text&Sprite Iconbar icon, and this field gives the maximum length of a text string which will be used for it | |
| menu | the name of the template to use to create a Menu object for this Iconbar icon | |
| select event | the Toolbox Event code to be raised when the user clicks Select on the Iconbar icon (if 0 then Iconbar_Clicked is raised) | |
| adjust event | the Toolbox event code to be raised when the user clicks Adjust on the Iconbar icon (if 0 then Iconbar_Clicked is raised) | |
| select show | the name of a template to use to show an object when the user clicks Select on the Iconbar icon | |
| adjust show | the name of a template to use to show an object when the user clicks Adjust on the Iconbar icon | |
| help message | the message to respond to a help request with, instead of the default | |
| max help | the maximum length of help message to be used | |
An Iconbar icon object is created using SWI Toolbox_CreateObject.
When an Iconbar Icon Object is created, the following attached objects (see Attached objects) will be created (if specified):
See the attributes table above for an explanation of what these objects are.
An Iconbar object is deleted using SWI Toolbox_DeleteObject. If it has any attached objects (see above), these are also deleted, unless the non-recursive bit is set for this SWI.
When a Iconbar icon object is displayed on the screen using SWI Toolbox_ShowObject it has the following behaviour:
| Show type | Position | |
|---|---|---|
| 0 (default) | display on the Iconbar in a place specified by the object's template's position and priority fields. | |
| 1 (full spec) | R3 + 0 | icon handle of icon to show icon to the left (-3) or right (-4) of its position. |
If the Iconbar icon's position is any other value than -3 or -4, then R3 should just be 0.
An Iconbar icon is hidden by using SWI Toolbox_HideObject.
An Iconbar icon is created with a position and a priority. These are integer values as specified in SWI Wimp_CreateIcon. Note that these values are fixed at create-time, but are only used when the Iconbar icon is 'shown', either by explicitly calling Toolbox_ShowObject, or by setting the auto-show bit in the object template's flags.
The semantics of position and priority are as documented in Wimp_CreateIcon. Applications will mostly just use a position of -1 for the right of the iconbar.
Note that positions of -3 and -4 cannot be used in conjunction with the auto-show bit. Such an Iconbar icon must be explicitly shown using Toolbox_ShowObject to allow the client to pass the Wimp handle of the icon to whose left/right this icon should be placed.
An Iconbar icon's position and priority cannot be changed at run-time.
Each Iconbar object can optionally have attached to it a Menu object. The Iconbar object holds the object id of this Menu object.
Whenever the user of the application presses the Menu mouse button over an Iconbar icon, the Iconbar class module opens its attached Menu object, by making a SWI Toolbox_ShowObject passing the attached Menu's id.
If the application wishes to perform some operations on the Menu before it is opened (ticking some entries for example), then by setting the appropriate bit in the Menu's flags word, the application can request that a special Toolbox event (Menu_AboutToBeShown) is delivered to it before the Menu is actually shown. The precise details of this Toolbox event are described on Menu_AboutToBeShown (0x828c0). On receipt of such a Toolbox event, the client application is expected to make any changes it wants to the Menu object, and then return to its SWI Wimp_Poll loop.
When an Iconbar icon is created, if the client has specified the name of a Menu template for that Iconbar icon, then a Menu object is created from that template, and the id of that Menu is held in the Iconbar object. This id will be used to show the Menu when the user presses the Menu button over the Iconbar icon.
In most cases a Menu is attached to the Iconbar icon at resource editing time by entering the name of the template to use for this Iconbar icon's Menu. If the application wishes to dynamically attach and detach the Menu for a given Iconbar icon, then this can be done using the Iconbar_SetMenu method described on Iconbar_SetMenu 1.
The id of the Menu attached to an Iconbar icon can be read by using the Iconbar_GetMenu method.
The client application can specify a Toolbox event to be raised when the user clicks Select and/or one to be raised when the user clicks Adjust on the Iconbar icon.
This event will only be raised if the appropriate flags bits have been set for Select and Adjust clicks.
Normally this is specified in the application's resource file, but it can be set and read using the Iconbar_SetEvent/Iconbar_GetEvent methods.
Each Iconbar object can optionally have attached to it a Help Message.
Whenever the Wimp delivers a HelpRequest message to the client application for this Iconbar icon, the attached Help Message is sent back automatically by the Toolbox.
In most cases a help message is attached to the Iconbar object at resource editing time. An Iconbar icon's Help Message can be set dynamically using the Iconbar_SetHelpMessage method described on Iconbar_SetHelpMessage 7.
The text of the Help Message can be read using the Iconbar_GetHelpMessage method.
The following methods are all invoked by calling SWI Toolbox_ObjectMiscOp with:
| R0 | holding a flags word |
| R1 | being an Iconbar object id |
| R2 | being the method code which distinguishes this method |
| R3-R9 | potentially holding method-specific data |
| R0 | = | flags |
| R1 | = | Iconbar object id |
| R2 | = | 0 |
| R0 | = | Wimp icon handle for this Iconbar object |
This method returns the handle of the underlying Wimp icon used to implement this Iconbar object.
extern _kernel_oserror *iconbar_get_icon_handle ( unsigned int flags,
ObjectId iconbar,
int *icon_handle
);
| R0 | = | flags |
| R1 | = | Iconbar object id |
| R2 | = | 1 |
| R3 | = | menu id |
| R1-R9 preserved |
This method is used to set the menu which will be displayed when the Menu button is pressed over this Iconbar object. The Toolbox handles opening the menu for you.
If R3 is 0, then the menu for this Iconbar object is detached.
extern _kernel_oserror *iconbar_set_menu ( unsigned int flags,
ObjectId iconbar,
ObjectId menu_id
);
| R0 | = | flags |
| R1 | = | Iconbar object id |
| R2 | = | 2 |
| R0 | = | Menu id |
This method is used to get the id of the menu which will be displayed when the Menu button is pressed over this Iconbar object.
extern _kernel_oserror *iconbar_get_menu ( unsigned int flags,
ObjectId iconbar,
ObjectId *menu_id
);
| R0 | = | flags bit 0 set means raise the event code specified in R3 when Select is clicked bit 1 set means raise the event code specified in R4 when Adjust is clicked |
| R1 | = | Iconbar object id |
| R2 | = | 3 |
| R3 | = | Toolbox Event code to raise for Select |
| R4 | = | Toolbox Event code to raise for Adjust |
| R1-R9 preserved |
This method specifies a Toolbox event to be raised when the user clicks Select and/or Adjust on the Iconbar icon.
If R3 or R4 is 0, then an IconBar_Clicked Toolbox event will be raised instead.
extern _kernel_oserror *iconbar_set_event ( unsigned int flags,
ObjectId iconbar,
int select_event,
int adjust_event
);
| R0 | = | flags bit 0 set means return the event code which will be raised when Select is clicked bit 1 set means return the event code which will be raised when Adjust is clicked |
| R1 | = | Iconbar object id |
| R2 | = | 4 |
| R0 | = | Toolbox event code raised when Select is clicked on the Iconbar icon |
| R1 | = | Toolbox event code raised when Adjust is clicked on the Iconbar icon |
This method reads the Toolbox Event to be raised when the user clicks Select or Adjust on the Iconbar icon.
extern _kernel_oserror *iconbar_get_event ( unsigned int flags,
ObjectId iconbar,
int *select_event,
int *adjust_event
);
| R0 | = | flags bit 0 set means show the object whose id is given in R3 when Select is clicked bit 1 set means show the object whose id is given in R4 when Adjust is clicked |
| R1 | = | Iconbar object id |
| R2 | = | 5 |
| R3 | = | id of object to show for Select |
| R4 | = | id of object to show for Adjust |
| R1-R9 preserved |
This method specifies an object to be shown when the user clicks Select and/or Adjust on the Iconbar icon.
If R3 or R4 is 0, then no object will be shown.
extern _kernel_oserror *iconbar_set_show ( unsigned int flags,
ObjectId iconbar,
ObjectId select,
ObjectId adjust
);
| R0 | = | flags bit 0 set means return the id of the object which will be shown when Select is clicked bit 1 set means return the id of the object which will be shown when Adjust is clicked |
| R1 | = | Iconbar object id |
| R2 | = | 6 |
| R0 | = | id of object which will be shown when Select is clicked on the Iconbar icon |
| R1 | = | id of object which will be shown when Adjust is clicked on the Iconbar icon |
This method reads the ids of the objects to be shown when the user clicks Select or Adjust on the Iconbar icon.
extern _kernel_oserror *iconbar_get_show ( unsigned int flags,
ObjectId iconbar,
ObjectId *select,
ObjectId *adjust
);
| R0 | = | flags |
| R1 | = | Iconbar object id |
| R2 | = | 7 |
| 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 Iconbar object. The Toolbox handles the reply message for you.
If R3 is 0, then the Help Message for this Iconbar object is detached.
extern _kernel_oserror *iconbar_set_help_message ( unsigned int flags,
ObjectId iconbar,
char *message_text
);
| R0 | = | flags |
| R1 | = | Iconbar object id |
| R2 | = | 8 |
| R3 | = | pointer to buffer (or 0) |
| R4 | = | size of buffer to hold message text |
| R4 | = | holds 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 Iconbar object.
extern _kernel_oserror *iconbar_get_help_message ( unsigned int flags,
ObjectId iconbar,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Iconbar object id |
| R2 | = | 9 |
| R3 | = | pointer to text string to use |
| R1-R9 preserved |
This method sets the text which is to be used in a text&sprite Iconbar object. If the text is longer than the maximum size specified when the Iconbar icon was created, then an error is returned.
extern _kernel_oserror *iconbar_set_text ( unsigned int flags,
ObjectId iconbar,
char *text
);
| R0 | = | flags |
| R1 | = | Iconbar object id |
| R2 | = | 10 |
| 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 icon's text R4 holds number of bytes written to buffer |
This method is used for a text&sprite Iconbar object. It returns the text string displayed for that object.
extern _kernel_oserror *iconbar_get_text ( unsigned int flags,
ObjectId iconbar,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Iconbar object id |
| R2 | = | 11 |
| R3 | = | pointer to name of sprite to use |
| R1-R9 preserved |
This method sets the sprite which is to be used in the Iconbar object.
extern _kernel_oserror *iconbar_set_sprite ( unsigned int flags,
ObjectId iconbar,
char *sprite_name
);
| R0 | = | flags |
| R1 | = | Iconbar object id |
| R2 | = | 12 |
| R3 | = | pointer to buffer to return the sprite name in (or 0) |
| R4 | = | size of buffer |
| R4 | = | holds size of buffer required for sprite name (if R3 was 0) else Buffer pointed at by R3 holds sprite name R4 holds number of bytes written to buffer |
This method returns the name of the sprite used for the Iconbar object.
extern _kernel_oserror *iconbar_get_sprite ( unsigned int flags,
ObjectId iconbar,
char *buffer,
int buff_len,
int *nbytes
);
| + 8 | 0x82900 | |
| + 12 | flags | |
| bits 0, 1 and 2 show how the activation was done: | ||
| bit 0 | set means Adjust was clicked | |
| bit 1 | reserved | |
| bit 2 | set means Select was clicked | |
This Toolbox event is raised when the user clicks Select or Adjust on an Iconbar object, and the client application has not associated any other Toolbox event with this event.
typedef struct
{
ToolboxEventHeader hdr;
} IconbarClickedEvent;
| + 8 | 0x82901 |
| + 16 | object id of the object which will be shown (note that the 'self' field in the id block will be for the Iconbar object). |
This Toolbox event is raised just before Toolbox_ShowObject is called for the object to be shown on a Select click. Note that on receipt of this event, the client could call Iconbar_SetShow to give the object id of a different object to be shown.
typedef struct
{
ToolboxEventHeader hdr;
ObjectId id;
} IconbarAboutToBeShownEvent;
| + 8 | 0x82902 |
| + 16 | object id of the object which will be shown (note that the 'self' field in the id block will be for the Iconbar object). |
This Toolbox event is raised just before Toolbox_ShowObject is called for the object to be shown on a Adjust click. Note that on receipt of this event, the client could call Iconbar_SetShow to give the object id of a different object to be shown.
Note: This event and the Iconbar_SelectAboutToBeShown event both share the same typedef.
typedef struct
{
ToolboxEventHeader hdr;
ObjectId id;
} IconbarAboutToBeShownEvent;
The layout of an Iconbar icon 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 |
| position | 4 | word |
| priority | 4 | word |
| sprite_name | 4 | StringReference |
| max_sprite_name | 4 | word |
| text | 4 | MsgReference |
| max_text_len | 4 | word |
| menu | 4 | StringReference |
| select_event | 4 | word |
| adjust_event | 4 | word |
| select_show | 4 | StringReference |
| adjust_show | 4 | StringReference |
| help_message | 4 | MsgReference |
| max_help | 4 | word |
Certain Wimp events for an Iconbar icon are fielded by the Iconbar class, and either acted upon for the client, or result in a Toolbox event being raised. Such events are listed below:
| Wimp event | Action |
|---|---|
| Mouse Click | If the Menu button has been pressed, and there is a Menu object attached to this Iconbar icon, then the Menu is shown using Toolbox_ShowObject.
If the Select or Adjust buttons have been pressed and this Iconbar icon has a Toolbox event associated with this, then that Toolbox event is raised, and any attached object is also shown using Toolbox_ShowObject. |
| User Msg | Message_HelpRequest (for this Iconbar icon) If a help message is attached to this Iconbar icon, then a reply is sent on the application's behalf. |