RISCOS.com

www.riscos.com Technical Support:
Toolbox

 


Iconbar icon class


Objects of the Iconbar icon class are used to display an application icon on the Iconbar.

User interface

An Iconbar object is normally used to show that an application is running, by placing an icon on the RISC OS Iconbar.

ICONBAR-2.GIF

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.

Application Program Interface

Attributes

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
Manipulating an Iconbar icon object
Creating and deleting an Iconbar icon object

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):

  • menu
  • select show
  • adjust show.

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.

Showing an Iconbar icon object

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.

The Iconbar icon's position and priority

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.

The Iconbar icon's menu

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.

Select and Adjust click events

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.

Help messages

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.

Iconbar icon methods

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
Iconbar_GetIconHandle 0
On entry
R0 = flags
R1 = Iconbar object id
R2 = 0
On exit
R0 = Wimp icon handle for this Iconbar object
Use

This method returns the handle of the underlying Wimp icon used to implement this Iconbar object.

C veneer

extern _kernel_oserror *iconbar_get_icon_handle ( unsigned int flags,
                                                  ObjectId iconbar,
                                                  int *icon_handle
                                                );


Iconbar_SetMenu 1
On entry
R0 = flags
R1 = Iconbar object id
R2 = 1
R3 = menu id
On exit
R1-R9 preserved
Use

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.

C veneer

extern _kernel_oserror *iconbar_set_menu ( unsigned int flags,
                                           ObjectId iconbar,
                                           ObjectId menu_id
                                         );


Iconbar_GetMenu 2
On entry
R0 = flags
R1 = Iconbar object id
R2 = 2
On exit
R0 = Menu id
Use

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.

C veneer

extern _kernel_oserror *iconbar_get_menu ( unsigned int flags,
                                           ObjectId iconbar,
                                           ObjectId *menu_id
                                         );


Iconbar_SetEvent 3
On entry
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
On exit
R1-R9 preserved
Use

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.

C veneer

extern _kernel_oserror *iconbar_set_event ( unsigned int flags,
                                            ObjectId iconbar,
                                            int select_event,
                                            int adjust_event
                                          );


Iconbar_GetEvent 4
On entry
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
On exit
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
Use

This method reads the Toolbox Event to be raised when the user clicks Select or Adjust on the Iconbar icon.

C veneer

extern _kernel_oserror *iconbar_get_event ( unsigned int flags,
                                            ObjectId iconbar,
                                            int *select_event,
                                            int *adjust_event
                                          );


Iconbar_SetShow 5
On entry
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
On exit
R1-R9 preserved
Use

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.

C veneer

extern _kernel_oserror *iconbar_set_show ( unsigned int flags,
                                           ObjectId iconbar,
                                           ObjectId select,
                                           ObjectId adjust
                                         );


Iconbar_GetShow 6
On entry
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
On exit
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
Use

This method reads the ids of the objects to be shown when the user clicks Select or Adjust on the Iconbar icon.

C veneer

extern _kernel_oserror *iconbar_get_show ( unsigned int flags,
                                           ObjectId iconbar,
                                           ObjectId *select,
                                           ObjectId *adjust
                                         );


Iconbar_SetHelpMessage 7
On entry
R0 = flags
R1 = Iconbar object id
R2 = 7
R3 = pointer to message text
On exit
R1-R9 preserved
Use

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.

C veneer

extern _kernel_oserror *iconbar_set_help_message ( unsigned int flags,
                                                   ObjectId iconbar,
                                                   char *message_text
                                                 );


Iconbar_GetHelpMessage 8
On entry
R0 = flags
R1 = Iconbar object id
R2 = 8
R3 = pointer to buffer (or 0)
R4 = size of buffer to hold message text
On exit
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
Use

This method is used to read the help message which will be returned when a Help Request message is received for this Iconbar object.

C veneer

extern _kernel_oserror *iconbar_get_help_message ( unsigned int flags,
                                                   ObjectId iconbar,
                                                   char *buffer,
                                                   int buff_size,
                                                   int *nbytes
                                                 );


Iconbar_SetText 9
On entry
R0 = flags
R1 = Iconbar object id
R2 = 9
R3 = pointer to text string to use
On exit
R1-R9 preserved
Use

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.

C veneer

extern _kernel_oserror *iconbar_set_text ( unsigned int flags,
                                           ObjectId iconbar,
                                           char *text
                                         );


Iconbar_GetText 10
On entry
R0 = flags
R1 = Iconbar object id
R2 = 10
R3 = pointer to buffer to return the text in (or 0)
R4 = size of buffer
On exit
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
Use

This method is used for a text&sprite Iconbar object. It returns the text string displayed for that object.

C veneer

extern _kernel_oserror *iconbar_get_text ( unsigned int flags,
                                           ObjectId iconbar,
                                           char *buffer,
                                           int buff_size,
                                           int *nbytes
                                         );


Iconbar_SetSprite 11
On entry
R0 = flags
R1 = Iconbar object id
R2 = 11
R3 = pointer to name of sprite to use
On exit
R1-R9 preserved
Use

This method sets the sprite which is to be used in the Iconbar object.

C veneer

extern _kernel_oserror *iconbar_set_sprite ( unsigned int flags,
                                             ObjectId iconbar,
                                             char *sprite_name
                                           );


Iconbar_GetSprite 12
On entry
R0 = flags
R1 = Iconbar object id
R2 = 12
R3 = pointer to buffer to return the sprite name in (or 0)
R4 = size of buffer
On exit
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
Use

This method returns the name of the sprite used for the Iconbar object.

C veneer

extern _kernel_oserror *iconbar_get_sprite ( unsigned int flags,
                                             ObjectId iconbar,
                                             char *buffer,
                                             int buff_len,
                                             int *nbytes
                                           );


Iconbar icon events

Iconbar_Clicked (0x82900)
Block
+ 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
Use

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.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
} IconbarClickedEvent;


Iconbar_SelectAboutToBeShown (0x82901)
Block
+ 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).
Use

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.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  ObjectId           id;
} IconbarAboutToBeShownEvent;


Iconbar_AdjustAboutToBeShown (0x82902)
Block
+ 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).
Use

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.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  ObjectId           id;
} IconbarAboutToBeShownEvent;


Iconbar icon templates

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

Iconbar icon Wimp event handling

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.

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