RISCOS.com

www.riscos.com Technical Support:
Toolbox

 


Window class


Objects of the Window class are used by the client application to display its document windows, dialogue boxes etc.

User interface

A Window is essentially an extension of a Wimp window (in fact part of the Window object definition is a Wimp window definition):

WINDOWS-2.GIF

Many Wimp events which are delivered to this Window are dealt with automatically by the Toolbox, based on the attributes of the Window. In this chapter we give further details of exactly what a Window consists of, and the semantics attached to Wimp events for a Window.

The client application is always able to get the Wimp window handle of the underlying Wimp window used to implement this Window object, and can perform all the usual Wimp SWIs on that window (within reason, e.g. deleting an icon belonging to a gadget may have undesirable efects).

Application Program Interface

Attributes

A Window 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, generate a Window_AboutToBeShown event before showing the underlying Wimp window
1 when set, automatically open this Window when a Wimp OpenWindowRequest is received
(when set the client will not see the underlying Wimp requests)
2 when set, automatically close this Window when a Wimp CloseWindowRequest is received
(when set the client will not see the underlying Wimp requests)
3 when set, generate a Window_HasBeenHidden Event after hiding the underlying Wimp window
4 when set, indicates that this template is of a toolbar (see Toolbars)
help message when a HelpRequest is received for this Window, then this text is sent in a HelpReply message. Note that this Help message is only sent if the gadget (see later) for which the request was received has not got a Help message of its own, or if the pointer is not over any gadget.
max help maximum length in bytes of help message
pointer shape this gives the name of a sprite to use as the pointer shape, when a Pointer Entering Window event is received for this Window (0 means do not change the pointer shape).
max pointer shape maximum length in bytes of sprite name
pointer x hot
pointer y hot
the x and y coordinates of the pointer's hot spot. These are relative pixels from the top left corner of the sprite.
menu the name of the template to use to create a Menu object for this Window
num keyboard shortcuts the number of keyboard short-cuts which are associated with this Window
keyboard shortcuts the pointer to the list of keyboard short-cuts for this Window
num gadgets the number of gadgets which are to appear in this Window
gadgets the pointer to the list of gadgets for this Window.
default focus the Component Id of the gadget which is given input focus when the window is shown.

If this field is -1 then no gadget will be given input focus

if -2 then window will be given input focus (but no caret) allowing keyboard short-cuts to work without having any writables.

window 88-byte structure is the standard block which is passed to Wimp_CreateWindow. The window is shown to contain no icons, since these are implemented by gadgets.
internal_bl the window template to be used for this toolbar. Anchored to the bottom left corner inside the window. †
internal_tl the window template to be used for this toolbar. Anchored to the top left corner inside the window. †
external_bl the window template to be used for this toolbar. Anchored to the bottom left corner outside the window. †
external_tl the window template to be used for this toolbar. Anchored to the top left corner outside the window. †
show_event the event code to be raised when the window is shown.
hide_event the event code to be raised after the window has been hidden.

† these templates must have the Toolbar bit set.

Keyboard short-cut

The attributes of a Keyboard short-cut are as follows:

Attributes Description
flags word Bit Meaning
0 when set, show attached object as 'transient'
wimp key code the key code returned by the Wimp in a Key Pressed event block, for this keyboard short-cut
key event this is the Toolbox event to be raised when the Wimp delivers a Key Pressed event with this Wimp key code.

0 means deliver no event

key show the name of the template for an object to create and show when the Wimp delivers a Key Pressed event with this Wimp key code.

0 means show no object

Note that because keyboard short-cuts work on Wimp key codes, certain key combinations (such as Shift-Ctrl-P) will require the client to provide extra code.

Gadget

All gadgets have a common header, followed immediately by a body which is gadget-specific. The header is described on Attributes, and the gadget-specific bodies are described in their own sections.

Manipulating a Window object
Creating and deleting a Window object

A Window object is created using SWI Toolbox_CreateObject.

When a Window object is created, the following attached objects (see Attached objects) will be created (if specified):

  • menu
  • key show (for each keyboard short-cut)
  • Toolbars.

See the attributes table above for an explanation of what these objects are.

There are also attached objects which are associated with gadgets in a Window (see later):

  • click show (for an action button)
  • menu (for a Pop-up menu).

These attached objects are also created when such a gadget is added to the Window, and deleted when the gadget is removed.

A Window 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 a Window

When a Window object is displayed on the screen using SWI Toolbox_ShowObject it has the following behaviour:

Show type Position
0 (default) the underlying window is shown at the last place shown on the screen, or the coordinates given in its template, if it has not already been shown
1 (full spec) R3 + 0 visible area minimum x coordinate
R3 + 4 visible area minimum y coordinate
R3 + 8 visible area maximum x coordinate
R3 + 12 visible area maximum y coordinate
R3 + 16 scroll x offset relative to work area
R3 + 20 scroll y offset relative to work area
R3 + 24 Wimp window handle of window to open behind
-1 means top of stack
-2 means bottom of stack
-3 means the window behind the Wimp's backwindow
2 (topleft) R3 + 0 visible area minimum x coordinate
R3 + 4 visible area minimum y coordinate
The Window's menu

Each Window object can optionally have attached to it a Menu object. The Window object holds the unique id of this Menu object.

When a Window is created, if the client has specified the name of a Menu template for that Window, then a Menu object is created from that template, and the id of that Menu is held in the Window object. This id will be used to show the Menu when the user presses the Menu button over the Window.

Whenever the user of the application presses the Menu mouse button over a Window, the Window 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 in Menu events. 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.

In most cases a Menu is attached to the Window at resource editing time by entering the name of the template to use for this Window's Menu. If the application wishes dynamically to attach and detach the menu for a given Window (maybe based on a mode of operation which is defined by the application, e.g. display mode or editing mode), then this can be done using the Window_SetMenu method described on Window_SetMenu 3.

The id of the Menu attached to a Window can be read by using the Window_GetMenu method.

Window_SetMenu can only be used when a menu is not already being shown for this Window.

Gadgets in a window

A Window object can optionally contain a number of gadgets. Typically this is used to create dialogue boxes.

There are many kinds of gadget. The Toolbox provides facilities to allow the client application to manipulate a particular gadget in a manner which is appropriate to that gadget, rather than in 'low-level' terms like setting the state of a Wimp icon. The set of gadgets is defined to fit in with the RISC OS 3 Style Guide, and thus to encourage a standard look and feel across dialogue boxes.

Gadgets are normally specified as part of a Window object template, but they can be added to and removed from Window's dynamically at run-time using the Window_AddGadget and Window_RemoveGadget methods respectively.

Each gadget type defines its own set of methods, and many will have a number of Toolbox events associated with them. This allows the application to receive Toolbox events from user actions, rather than having to deal with mouse clicks and drags on Wimp icons. Much of the low-level Wimp operations are handled automatically by the Toolbox.

Gadgets are described in Gadgets.

Keyboard short-cuts

Each Window object can optionally define a set of mappings from Wimp key codes to Toolbox events. This is particularly useful in allowing the client application to respond identically to a keystroke or an equivalent menu hit, by giving both the same Toolbox event. When a given keystroke is returned by the Wimp for the Window object, the corresponding Toolbox event is raised.

Note that Shift-Ctrl-letter combinations are not allowed.

It is also possible to provide the name of a template for an object which will be created and shown, when a particular keystroke happens. For example the client may wish to display a dialogue box when F4 is pressed. If bit 0 of the keyboard short-cut's flags word is set, then the object is shown with the 'Show with Wimp CreateMenu semantics' bit set in the R0 passed to Toolbox_ShowObject.

Sets of Keyboard short-cuts will normally be defined by the client application in its resource file, but they can also be added and removed dynamically using the Window_AddKeyboardShortcuts (Window_AddKeyboardShortcuts 9) and Window_RemoveKeyboardShortcuts (Window_RemoveKeyboardShortcuts 10) methods, passing as an argument an array of mappings.

Pointer shapes

Each Window object can optionally have a pointer shape defined, giving the name of a sprite to use and its hot spot.

Whenever the Wimp pointer enters this Window, causing a PointerEnteringWindow event, the Toolbox changes the pointer shape appropriately.

In most cases a pointer shape is attached to the Window at resource editing time by entering the name of the sprite to be used, and the pointer's hot spot. If the application wishes dynamically to change the pointer for a given Window (maybe based on a mode of operation which is defined by the application, e.g. display mode or editing mode), then this can be done using the Window_SetPointer method described in Window_SetPointer 5.

The name of the sprite used for the Window's pointer shape and its hot spot can be read by using the Window_GetPointer method described in Window_GetPointer 6.

Help messages

Each Window object can optionally have attached to it a Help message.

Whenever the Wimp delivers a HelpRequest message to the client application for this Window, the attached Help message is sent back automatically by the Toolbox.

In most cases a help message is attached to the Window at resource editing time. A Window's Help message can be set dynamically using the
Window_SetHelpMessage 7 described on Window_SetHelpMessage 7.

The text of the Help message can be read using the Window_GetHelpMessage method.

Changing a window's title

One of the attributes of a Window which is specified in the template for that Window is the text which appears in its title bar.

A Window's title can be changed dynamically at run-time using the Window_SetTitle method.

The current title string can be read using the Window_GetTitle method.

Getting and setting a Window's client handle

The client handle for a Window is set and read using SWI Toolbox_SetClientHandle and SWI Toolbox_GetClientHandle respectively.

A typical use of this client handle would be to hold a pointer to a data structure containing the state of a document which is being displayed in this Window in a multi-document editor.

Window methods

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

R0 holding a flags word
R1 being a Window id
R2 being the method code which distinguishes this method
R3-R9 potentially holding method-specific data
Window_GetWimpHandle 0
On entry
R0 = flags
R1 = Window object id
R2 = 0
On exit
R0 = Wimp window handle for this window
Use

This method returns the handle of the underlying Wimp window used to implement this Window object.

C veneer

extern _kernel_oserror *window_get_wimp_handle ( unsigned int flags,
                                                 ObjectId window,
                                                 int *window_handle
                                               );

Window_AddGadget 1
On entry
R0 = flags
R1 = Window object id
R2 = 1
R3 = pointer to description block for gadget
On exit
R0 = component id
R1-R9 preserved
Use

This method adds a gadget to the list of gadgets for this Window object. The format of the description block depends on the type of gadget being added.

If the Window is currently open on the screen, then the gadget will immediately be visible in the Window.

If the gadget's component id is specified as -1, then the Toolbox wil allocate an unused component id.

C veneer

extern _kernel_oserror *window_add_gadget ( unsigned int flags,
                                            ObjectId window,
                                            Gadget *gadget,
                                            ComponentId *gadget_component
                                          );

Window_RemoveGadget 2
On entry
R0 = flags
R1 = Window object id
R2 = 2
R3 = component id
On exit
R1-R9 preserved
Use

This method removes a gadget from a Window object. If the Window is currently displayed on the screen, then this removal results in a redraw of the Window by the Toolbox.

C veneer

extern _kernel_oserror *window_remove_gadget ( unsigned int flags,
                                               ObjectId window,
                                               ComponentId gadget
                                             );

Window_SetMenu 3
On entry
R0 = flags
R1 = Window object id
R2 = 3
R3 = menu object 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 Window object. The Toolbox handles opening the Menu for you.

If R3 is 0, then the Menu for this Window is detached.

C veneer

extern _kernel_oserror *window_set_menu ( unsigned int flags,
                                          ObjectId window,
                                          ObjectId menu_id
                                        );

Window_GetMenu 4
On entry
R0 = flags
R1 = Window object id
R2 = 4
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 Window object.

C veneer

extern _kernel_oserror *window_get_menu ( unsigned int flags,
                                          ObjectId window,
                                          ObjectId *menu_id
                                        );

Window_SetPointer 5
On entry
R0 = flags
R1 = Window object id
R2 = 5
R3 = pointer to name of sprite to use for pointer
R4 = x hot spot
R5 = y hot spot
On exit
R1-R9 preserved
Use

This method is used to set the Pointer shape which will be used when the pointer enters this Window object. The Toolbox handles setting the Wimp Pointer shape for you.

If R3 is 0, then the Pointer for this Window is detached.

C veneer

extern _kernel_oserror *window_set_pointer ( unsigned int flags,
                                             ObjectId window,
                                             char *sprite_name,
                                             int x_hot_spot,
                                             int y_hot_spot
                                           );

Window_GetPointer 6
On entry
R0 = flags
R1 = Window object id
R2 = 6
R3 = pointer to buffer
R4 = size of buffer to hold sprite name
R5 = x hot spot
R6 = y hot spot
On exit
R4 = 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 is used to get the name of the sprite which will be used when the pointer enters this Window object, and to get the pointer's hot spot.

C veneer

extern _kernel_oserror *window_get_pointer ( unsigned int flags,
                                             ObjectId window,
                                             char *buffer,
                                             int buff_size,
                                             int *nbytes,
                                             int *x_hot_spot,
                                             int *y_hot_spot
                                           );

Window_SetHelpMessage 7
On entry
R0 = flags
R1 = Window 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 Window object. The Toolbox handles the reply message for you.

If R3 is 0, then the Help Message for this Window is removed.

C veneer

extern _kernel_oserror *window_set_help_message ( unsigned int flags,
                                                  ObjectId window,
                                                  char *message_text
                                                );

Window_GetHelpMessage 8
On entry
R0 = flags
R1 = Window object id
R2 = 8
R3 = pointer to buffer
R4 = size of buffer to hold message text
On exit
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
Use

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

C veneer

extern _kernel_oserror *window_get_help_message ( unsigned int flags,
                                                  ObjectId window,
                                                  char *buffer,
                                                  int buff_len,
                                                  int *nbytes
                                                );

Window_AddKeyboardShortcuts 9
On entry
R0 = flags
R1 = Window object id
R2 = 9
R3 = number of short-cuts to add
R4 = pointer to memory block containing an array of description blocks for the keyboard short-cuts. Each block is laid out in memory as described in Window templates
On exit
R1-R9 preserved
Use

This method adds a number of keyboard short-cuts to the list of keyboard short-cuts for this Window object. When a Key Pressed event is received for this Window, the given Toolbox event is raised as the next Wimp event for the client application.

If any of the keyboard short-cuts are already defined for this Window, then they are replaced by the new short-cuts.

C veneer

extern _kernel_oserror *window_add_keyboard_shortcuts ( unsigned int flags,
                                                        ObjectId window,
                                                        int no_shortcuts,
                                                        KeyboardShortcut *shortcuts
                                                      );

Window_RemoveKeyboardShortcuts 10
On entry
R0 = flags
R1 = Window object id
R2 = 10
R3 = -1 means remove all keyboard short-cuts
or R3 = number of short-cuts to remove
R4 = pointer to an array of key short-cuts to be removed
(number given in R3)
On exit
R1-R9 preserved
Use

This method removes a number of keyboard short-cuts which have been associated with this Window using the Window_AddKeyboardShortcuts method.

C veneer

extern _kernel_oserror *window_remove_keyboard_shortcuts ( unsigned int flags,
                                                           ObjectId window,
                                                           int no_remove,
                                                           KeyboardShortcut *shortcuts
                                                         );

Window_SetTitle 11
On entry
R0 = flags
R1 = Window object id
R2 = 11
R3 = pointer to new text for title bar
On exit
R1-R9 preserved
Use

This method changes the text in a Window's title bar. If the string is too long for the title bar's buffer, an error is returned.

C veneer

extern _kernel_oserror *window_set_title ( unsigned int flags,
                                           ObjectId window,
                                           char *title
                                         );

Window_GetTitle 12
On entry
R0 = flags
R1 = Window object id
R2 = 12
R3 = pointer to buffer to hold title text (or 0)
R4 = size of buffer
On exit
R4 = size of buffer required (if R3 was 0)
else Buffer pointed at by R3 holds title text
R4 holds number of bytes written to buffer
Use

This method returns the string currently used in a Window's title bar.

C veneer

extern _kernel_oserror *window_get_title ( unsigned int flags,
                                           ObjectId window,
                                           char *buffer,
                                           int buff_size,
                                           int *nbytes
                                         );

Window_SetDefaultFocus 13
On entry
R0 = flags
R1 = Window object id
R2 = 13
R3 = component id
On exit
R1-R9 preserved
Use

This method sets the default focus component for a window. As with the template, a value of -1 means no default focus, and -2 means put the focus in the window.

Note that this sets the default, i.e. only takes effect when next shown.

C veneer

extern _kernel_oserror *window_set_default_focus ( unsigned int flags,
                                                   ObjectId window,
                                                   ComponentId focus
                                                 );

Window_GetDefaultFocus 14
On entry
R0 = flags
R1 = Window object id
R2 = 14
On exit
R0 = component id
R1-R9 preserved
Use

This method returns the default focus component of a window.

C veneer

extern _kernel_oserror *window_get_default_focus ( unsigned int flags,
                                                   ObjectId window,
                                                   ComponentId *focus
                                                 );

Window_SetExtent 15
On entry
R0 = flags
R1 = Window object id
R2 = 15
R3 = pointer to extent bounding box:
+ 0 minimum x coordinate
+ 4 minimum y coordinate
+ 8 maximum x coordinate
+ 12 maximum y coordinate
On exit
R1-R9 preserved
Use

This method changes the extent of the underlying Wimp window.

C veneer

extern _kernel_oserror *window_set_extent ( unsigned int flags,
                                            ObjectId window,
                                            BBox *extent
                                          );

Window_GetExtent 16
On entry
R0 = flags
R1 = Window object id
R2 = 16
R3 = pointer to four word block to hold extent
On exit
R1-R9 preserved and block pointed to by R3 updated:
+ 0 minimum x coordinate
+ 4 minimum y coordinate
+ 8 maximum x coordinate
+ 12 maximum y coordinate
Use

This method returns the extent of the underlying Wimp window.

C veneer

extern _kernel_oserror *window_get_extent ( unsigned int flags,
                                            ObjectId window,
                                            BBox *extent
                                          );

Window_ForceRedraw 17
On entry
R0 = flags
R1 = Window object id
R2 = 17
R3 = pointer to area to redraw:
+ 0 minimum x coordinate
+ 4 minimum y coordinate
+ 8 maximum x coordinate
+ 12 maximum y coordinate
On exit
R1-R9 preserved
Use

This method forces a redraw on the area of the window given by the work area coordinates pointed to by R3.

C veneer

extern _kernel_oserror *window_force_redraw ( unsigned int flags,
                                              ObjectId window,
                                              BBox *redraw_box
                                            );

Window_SetToolBars 18
On entry
R0 = mask
bit 0 set means set internal bl toolbar
bit 1 set means set internal tl toolbar
bit 2 set means set external bl toolbar
bit 3 set means set external tl toolbar
R3 = object id of internal bl toolbar
R4 = object id of internal tl toolbar
R5 = object id of external bl toolbar
R6 = object id of external tl toolbar
Use

This method sets the object ids of the toolbars that are attached to a particular window object. If the object is showing then the new toolbars will be shown, and any toolbars of the same type will be hidden (it is not possible to have more than one toolbar of each type). The mask allows selective setting of toolbars.

Passing an Id of zero means that there is no toolbar of that type.

C veneer

extern _kernel_oserror *window_set_tool_bars ( unsigned int flags,
                                               ObjectId window,
                                               ObjectId ibl,
                                               ObjectId itl,
                                               ObjectId ebl,
                                               ObjectId etl
                                             );

Window_GetToolBars 19
On entry
R0 = mask
bit 0 set means return internal bl toolbar
bit 1 set means return internal tl toolbarv
bit 2 set means return external bl toolbar
bit 3 set means return external tl toolbar
On exit
R0 = object id of internal bl toolbar
R1 = object id of internal tl toolbar
R2 = object id of external bl toolbar
R3 = object id of external tl toolbar
Use

This method returns the object ids of the toolbars that are attached to a window object. By setting the mask it is possible to control which ids are returned.

C veneer

extern _kernel_oserror *window_get_tool_bars ( unsigned int flags,
                                               ObjectId window,
                                               ObjectId *ibl,
                                               ObjectId *itl,
                                               ObjectId *ebl,
                                               ObjectId *etl
                                             );

Other SWIs

SWI Window_GetPointerInfo (0x82883)
On entry
R0 = flags
On exit
R0 = x position
R1 = y position
R2 = buttons
bit set
0 adjust
1 menu
2 select
8 not over a toolbox window
R3 = Window id, or Wimp window handle if bit 8 set in R2
R4 = component id, or icon handle if bit 8 of R2 set
Use

This SWI is analogous to Wimp_GetPointerInfo, but returns Object ids and Component ids if the pointer is over a toolbox window.

C veneer

extern _kernel_oserror *window_get_pointer_info ( unsigned int flags,
                                                  int *x_pos,
                                                  int *y_pos,
                                                  int *buttons,
                                                  ObjectId *window,
                                                  ComponentId *component
                                                );

SWI Window_WimpToToolbox (0x82884)
On entry
R0 = flags
R1 = Wimp window handle
R2 = icon handle
On exit
R0 = toolbox object handle for window
R1 = component id
Use

This SWI returns the object handle and component id that contains the specified icon.

If the Wimp handle is not known by the toolbox, then the returned object id is 0.

Note that this only applies to Window objects.

C veneer

extern _kernel_oserror *window_wimp_to_toolbox ( unsigned int flags,
                                                 int window_handle,
                                                 int icon_handle,
                                                 ObjectId *object,
                                                 ComponentId *component
                                               );

SWI Window_ExtractGadgetInfo (0x828be)
On entry
R0 = flags
R1 = pointer window template
R2 = component id to match
On exit
R0 = pointer to Gadget
R1 = size of gadget
Use

This SWI returns a pointer to a block of memory suitable for passing to Window_AddGadget. It is typically used in conjunction with Toolbox_LookupTemplate and intended to be used for dynamic windows such as the Print dialogue box, or a task manager type application.

Note that the returned area should be copied as it cannot be guaranteed to persist for the duration of the task.

See Implementing hotspots for an example of using this SWI.

C veneer

extern _kernel_oserror *window_extract_gadget_info ( unsigned int flags,
                                             ObjectTemplateHeader *templ,
                                             ComponentId gadget,
                                             void **desc,
                                             int *size
                                             );

Window events

The Window class generates the following Toolbox events:

Window_AboutToBeShown (0x82880)
Block
+ 8 0x82880
+ 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
Use

This Toolbox event is raised by the Toolbox when Toolbox_ShowObject is called on a Window which has the appropriate bit set in its template flags word. It enables a client application to set any appropriate attributes of the Window, before it appears on the screen.

C data type

typedef struct
{
  ToolboxEventHeader  hdr;
  int                 show_type;
  union
  {
    TopLeft                 top_left;
    WindowShowObjectBlock   full_spec;
  } info;
} WindowAboutToBeShownEvent;

Window_HasBeenHidden (0x82890)
Block
+ 8 0x82890
Use

This Toolbox event is raised by the Toolbox when Toolbox_HideObject is called on a Window which has the appropriate bit set in its template flags word. It enables a client application to clear up after a window has been closed. It is also raised when clicking a non-local action button or clicking outside a window that was opened with 'CreateMenu' semantics.

C data type

typedef struct
{
  ToolboxEventHeader  hdr;
} WindowHasBeenHiddenEvent;

Window templates

The layout of a Window 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). Note that the version in the object header should be 102.

For more details on relocation, see Resource File Formats.

Field Size in bytes Type
flags 4 word
help_message 4 MsgReference
max_help 4 word
pointer_shape 4 StringReference
max_pointer_shape 4 word
pointer_x_hot 4 word
pointer_y_hot 4 word
menu 4 StringReference
num_keyboard_shortcuts 4 word
keyboard_shortcuts 4 ObjectOffset
num_gadgets 4 word
gadgets 4 ObjectOffset
default_focus 4 word
show_event 4 word
internal_bl 4 StringReference
internal_tl 4 StringReference
external_bl 4 StringReference
external_tl 4 StringReference
hide_event 4 word
window 88 WimpWindow
data variable array of bytes

A WimpWindow is an 88-byte structure with the following fields:

Field Size in bytes Type
vis_xmin 4 word
vis_ymin 4 word
vis_xmax 4 word
vis_ymax 4 word
scroll_x 4 word
scroll_y 4 word
behind 4 word
window_flags 4 word
title_fore 1 byte
title_back 1 byte
work_fore 1 byte
work_back 1 byte
scroll_outer 1 byte
scroll_inner 1 byte
title_inputfocus 1 byte
filler 1 byte (must be 0)
work_xmin 4 word
work_ymin 4 word
work_xmax 4 word
work_ymax 4 word
title_flags 4 word
button_type 4 word
sprite_area 4 SpriteAreaReference
min_width 2 half-word
min_height 2 half-word
title_text 4 MsgReference
title_validation 4 StringReference
title_buflen 4 word
num_icons 4 word (must be zero)
Keyboard short-cut
Field Size in bytes Type
flags 4 word
wimp_key_code 4 word
key_event 4 word
key_show 4 StringReference
Gadget
Field Size in bytes Type
flags 4 word
type/size 4 word
xmin 4 word
ymin 4 word
xmax 4 word
ymax 4 word
component_id 4 word
help_text 4 MsgReference
max_help 4 word
data variable array of bytes

Window Wimp event handling

Certain Wimp events for a Window are handled by the Window class, and either acted upon for you, or result in the raising of a Toolbox event. Such events are listed below:

Wimp event Action
Open Window Request if the 'auto-open' bit is set for this Window object, then Toolbox_ShowObject is called for this Window
Close Window Request if the 'auto-close' bit is set for this Window object, then Toolbox_HideObject is called for this Window
Pointer Leaving Window if there is a pointer shape defined for this Window, then the pointer is set back to its default shape
Pointer Entering Window if there is a pointer shape defined for this Window, then the pointer is set to that shape
Mouse Click if the Menu button has been pressed, and there is a Menu object attached to this Window, then the Menu is shown using Toolbox_ShowObject
Key Pressed if a keyboard short-cut for the given Wimp key code is attached to this Window, then its Toolbox event is raised as the next Wimp event for the client application
User Msg Message_HelpRequest

if a help message is attached to this Window, then a reply is sent on the application's behalf

Toolbars

Toolbars are attachments to windows, and are used mainly as tool boxes and status lines. They cannot exist purely by themselves. By using the toolbars supplied by the Window module, applications will have a consistent mechanism for displaying/accessing such functionality. It is not intended that they be used for anything beyond this.

User interface

A toolbar is a restricted window object - it cannot have any window furniture (such as a title bar), nor does it have an absolute position when shown on the screen. It is anchored either to the bottom left or to the top left of the parent's visible area; i.e. it does not move or scroll when the parent scrolls its work area.

WINDOWS-3.GIF

A toolbar can be considered to be either internal (in which case its size will be clipped when the parent resizes) or external (i.e. lying entirely outside the parent's visible area). On moving a window with an external toolbar close to the extremities of the screen, the bar will 'bounce' over the window until the window itself moves off screen.

Toolbars are displayed in a definite order:

  • external toolbars will always be displayed above internal ones
  • top left toolbars will always be displayed above bottom left ones.

Usually, this will only be noticed when reducing the size of a window.

For example, when moving a window to the left of the screen, the external toolbar will be displayed above any toolbar inside the window.

Use of toolbars
Application tool box

It is anticipated that the top left variety of toolbars will be used as application tool boxes, i.e. they will consist of gadgets that are used to control the behaviour of the application. The decision as to whether an internal or external one is used would typically depend on the number of 'tools' that are required.

Status lines

Internal bottom left toolbars are usually for status lines. For example:

The data is loading, 50% complete

and external bottom left toolbars for toolboxes that require width (e.g. because they contain a writable) but are unlikely to be as wide as the work area (in which case they would leave an irregular work space).

Note that if a toolbar contains a non-local action button then clicking on it will hide that toolbar.

Application program interface

Attributes

Toolbar object attributes are described in the window attributes section on Attributes.

Note that a toolbar should not have toolbars itself.

Manipulating a toolbar
Creating and deleting a toolbar object

Toolbar objects are created and deleted using the standard Toolbox_CreateObject and Toolbox_DeleteObject methods.

Showing and Hiding

A toolbar can only be shown whilst its parent is showing. The only defined show type is ShowAsDefault. This will make the window module show the toolbar in the place appropriate for its type. It is possible to hide a toolbar without hiding its parent. If a toolbar is hidden, then this is 'remembered' such that hiding then showing the parent will result in the toolbar still being hidden.

When a toolbar object is displayed on the screen using SWI Toolbox_ShowObject it behaves in the same way as shown in User interface.

Toolbar methods

Toolbars use the same methods as windows (see Window methods).
However, the behaviour of the following methods are undefined:

Window_SetTitle
Window_GetTitle
Window_SetToolBars
Window_GetToolBars
Window_AddKeyboardShortcuts
Window_RemoveKeyboardShortcuts

Getting and setting the toolbars associated with a window object are described in Window_GetToolBars 19 and Window_SetToolBars 18.

Normally this would be done using ResEd.

Gadgets

Application Program Interface

Gadgets are not objects in their own right, but exist only as a component of a Window object. Within that object they have unique component ids.

A gadget is essentially a part of a Window which provides functionality (for example, a button or a slider), and is usually implemented using Wimp icons. The use of icons is transparent to the client, who manipulates the gadgets using higher-level, abstract methods which are appropriate to the particular gadget type.

Wherever a gadget is implemented as a set of Wimp icons, the client can access these using low-level Wimp SWIs, but in the vast majority of cases this should not prove necessary.

Some gadgets are 'Composite' in that they consist of gadgets themselves. These are identifiable by the client as they have a NULL icon list. The client will receive toolbox events on both the composite gadget and the gadgets that make them up, but will generally only be interested in the former. Certain gadgets have methods for accessing the component ids of the gadgets that make them up, e.g. NumberRange_GetComponents.

Some gadgets support anti-aliased fonts in place of the system font (which may itself be an outline font on RISC OS 3 (version 3.5). When this is the case, the Window module handles mode changes and losing fonts on the client's behalf.

The window module reserves all component ids greater than 0xffffff. Standard dialogues use the range 0x800000 to 0xffffff, leaving 0 to 0x7fffff free for the client.

There are many kinds of gadget. The Toolbox provides facilities to allow the client application to manipulate a particular gadget in a manner which is appropriate to that gadget, rather than in 'low-level' terms like setting the state of a Wimp icon. The set of gadgets is defined to fit in with the RISC OS 3 Style Guide, and thus to encourage a standard look and feel across dialogue boxes.

The available set of gadgets is currently:

Action buttonsAdjuster arrowsButton gadgetDisplay fieldsDraggable gadgets
LabelsLabelled boxesNumber rangesOption buttonsPop-up menus
Radio buttonsSlidersString setsWritable fields
Attributes

All gadgets have the following attributes which are specified in a window template, and most can be manipulated at run-time by the client application:

Attribute Description
flags word Bit Meaning
30 when set, gadget is at the back, i.e. created first
31 when set, gadget is 'faded'
type/size this holds the size of the gadget's template (including its header) in its top two bytes, and the type of the gadget in its lower two bytes. The list of currently known gadget types is given below.
xmin the minimum x coordinate of the gadget's bounding box (in window work area coordinates).
ymin the minimum y coordinate of the gadget's bounding box (in window work area coordinates).
xmax the maximum x coordinate of the gadget's bounding box (in window work area coordinates).
ymax the maximum y coordinate of the gadget's bounding box (in window work area coordinates).
component id this identifies the gadget uniquely within this Window
help message when a HelpRequest message is received for this gadget, then this string is sent back in a HelpReply message. If 0, then the help message for the Window will be sent.
max help maximum length in bytes of the gadget's help message.

Note that for the gadgets listed below, the size is 'built in' to the Window module, and so the size can be set to zero though gadgets.h defines gadget_Type which includes the size.

The type of a gadget is one of:

Gadget type Type field
Action Button 128
Option Button 192
Labelled Box 256
Label 320
Radio Button 384
Display Field 448
Writable Field 512
Slider 576
Draggable 640
PopUp Menu 704
Adjuster Arrow 768
Number Range 832
String Set 896
Button 960
Manipulating a Gadget

Each gadget type defines its own set of methods, and many will have a number of Toolbox events associated with them. This allows the application to receive Toolbox events from user actions, rather than having to deal with mouse clicks and drags on Wimp icons. Most of the low-level Wimp operations are handled automatically by the Toolbox.

Normally all of the gadgets in a particular Window object will be specified in the template for that Window in the resource file, but the Toolbox provides two methods for adding and removing gadgets from a Window object dynamically, namely Window_AddGadget and Window_RemoveGadget.

All gadgets have standard attributes, which give the gadget's component id in this Window, the gadget's bounding box, and the help message to be associated with this gadget. These attributes are normally specified in the application's resource file; the Help messages can be changed and read using the methods Gadget_SetHelpMessage/Gadget_GetHelpMessage. Sending back a help message is automatically handled by the Toolbox.

Each gadget has a flags word which defines the behaviour of that gadget; the exact list of bit settings in this flags word depends on the type of gadget. The client can read and set this word using the Gadget_GetFlags and Gadget_SetFlags methods. The top 8 bits of this flags word are generic flags of relevance to all gadgets. The other 24 bits are used to hold Gadget-specific flags. Currently the defined generic flags are:

Bit Meaning when set
30 Gadget is at the back, i.e. created first
31 Gadget is 'faded'

There is a gadget method which returns a list of Wimp icon numbers for the icons used to implement the gadget. The details of this list and the way in which icon numbers map to the individual components of the gadget are specific to each gadget, and this mapping is documented below for each gadget type. The method is called Gadget_GetIconList.

This is implementation specific and subject to change in future releases of the window module:

Gadget type Number of icon numbers returned Icon list
action button 1 the icon for the action button
option button 2 the icon for the sprite
the icon for the text
labelled box 2 the icon for the label
the icon for the box
label 1 the icon for the label
radio button 2 the icon for the sprite
the icon for the text
display field 1 the icon for the display field
writable field 1 the icon for the writable field
slider 3 the icon for the 'well'
the icon for the 'background'
the icon for the 'bar'
draggable 1 the icon for the draggable
pop-up menu 1 the icon for the PopUp's button
adjuster arrow 1 the icon for the arrow
number range 0 composite
string set 0 composite
button 1

Composite gadgets have specific methods to get the component ids of their constituent gadgets. In this way run time methods (e.g. the colour of a slider in a number range) may be applied to the underlying gadgets. It is unlikely however that this will be particularly useful and could in fact affect the behaviour of the toolbox.

Generic gadget methods

In all of the methods on gadgets

R0 is used as a flags word
R1 holds the object id of this gadget's parent Window object
R2 holds the method code
R3 holds the component id for this gadget
R4-R9 potentially holding method-specific data

The following methods can be applied to all gadgets.

Gadget_GetFlags 64
On entry
R0 = 0
R1 = Window object id
R2 = 64
R3 = Gadget component id
On exit
R0 = flags settings for this gadget
Use

This method returns the flags word for the given gadget.

C veneer

extern _kernel_oserror *gadget_get_flags ( unsigned int flags,
                                           ObjectId window,
                                           ComponentId gadget,
                                           unsigned int *flags_settings
                                         );

Gadget_SetFlags 65
On entry
R1 = Window object id
R2 = 65
R3 = Gadget component id
R4 = new flags settings
On exit
R1-R9 preserved
Use

This method sets the flags word for the given gadget. The only flags that can usefully be changed are the faded bits. Modifying other bits is undefined.

C veneer

extern _kernel_oserror *gadget_set_flags ( unsigned int flags,
                                           ObjectId window,
                                           ComponentId gadget,
                                           unsigned int new_flags_settings
                                         );

Gadget_SetHelpMessage 66
On entry
R0 = flags
R1 = Window object id
R2 = 66
R3 = Gadget component id
R4 = pointer to help message text
On exit
R1-R9 preserved
Use

This method sets the help message which will be returned, when a help request is received for this gadget.

C veneer

extern _kernel_oserror *gadget_set_help_message ( unsigned int flags,
                                                  ObjectId window,
                                                  ComponentId gadget,
                                                  char *message_text
                                                );

Gadget_GetHelpMessage 67
On entry
R0 = flags
R1 = Window object id
R2 = 67
R3 = Gadget component id
R4 = pointer to buffer
R5 = size of buffer
On exit
R5 = size of buffer required to hold help text (if R4 was 0)
else buffer pointed at by R4 holds help text
R5 gives number of bytes written to buffer
Use

This method returns the help message which will be returned, when a help request is received for this gadget.

C veneer

extern _kernel_oserror *gadget_get_help_message ( unsigned int flags,
                                                  ObjectId window,
                                                  ComponentId gadget,
                                                  char *buffer,
                                                  int buff_size,
                                                  int *nbytes
                                                );

Gadget_GetIconList 68
On entry
R0 = flags
R1 = Window object id
R2 = 68
R3 = Gadget component id
R4 = pointer to buffer
R5 = size of buffer
On exit
R5 = size of buffer required to hold icon list (if R4 was 0)
else buffer pointed at by R4 holds list of Wimp icon numbers for this gadget
R5 holds number of bytes written to buffer
Use

This method returns a list of Wimp icon numbers (integers) for the icons used to implement this gadget. For a composite gadget the size returned will be zero.

C veneer

extern _kernel_oserror *gadget_get_icon_list ( unsigned int flags,
                                               ObjectId window,
                                               ComponentId gadget,
                                               int *buffer,
                                               int buff_size,
                                               int *nbytes
                                             );

The client should not cache the results of this call, since these values may change at a later date.

Gadget_SetFocus 69
On entry
R0 = flags
On exit
R1-R9 preserved
Use

This method sets the input focus to the given component of a window. Note that such a component must be a writable field, or a composite gadget which includes a writable field such as a number range.

C veneer

extern _kernel_oserror *gadget_set_focus ( unsigned int flags,
                                           ObjectId window,
                                           ComponentId component
                                         );

Gadget_GetType 70
On entry
R0 = 0
R1 = Window object id
R2 = 70
R3 = Gadget component id
On exit
R0 = type of this Gadget
Use

Usage:

This method returns the type of the given gadget.

C veneer

extern _kernel_oserror *gadget_get_type ( unsigned int flags,
                                          ObjectId window,
                                          ComponentId gadget,
                                          int *type
                                        );

Gadget_MoveGadget 71
On entry
R0 = flags
R1 = Window object id
R2 = 71
R3 = Gadget component id
R4 = pointer to new bounding box
On exit
R1-R9 preserved
Use

This method moves an already created gadget within a window. Note that as a new bounding box is given, it allows the gadget to be resized as well, though the exact behaviour of this feature will depend on the gadget type.

C veneer

extern _kernel_oserror *gadget_move_gadget ( unsigned int flags,
                                             ObjectId window,
                                             ComponentId gadget,
                                             BBox *new_bbox
                                           );

Gadget_GetBBox 72
On entry
R0 = flags
R1 = Window object id
R2 = 72
R3 = Gadget component id
R4 = pointer to 4 word buffer
On exit
R1-R9 preserved
Use

This method copies the bounding box of a gadget into the supplied buffer.

C veneer

extern _kernel_oserror *gadget_get_bbox ( unsigned int flags,
                                           ObjectId window,
                                           ComponentId gadget,
                                           BBox *box
                                         );

Gadget Wimp event handling

Wimp event Action
Mouse Click if Select or Adjust on an action button, option button or radio button member, then if a Toolbox event is associated with this event, it is raised. Otherwise the appropriate default Toolbox event is raised.

if on a pop-up menu button, then the associated Menu is shown.

if on a draggable then a Draggable_Click/Draggable_DoubleClick is reported.

Key Pressed This depends on the type of gadget.

For a writable field, if the keystroke is a down or up arrow, then the caret is placed in the next or previous writable field (using the field's 'before' and 'after' values).

If return is pressed, then the Default action button is activated (if present).

User Message Message_HelpRequest

if a help message is attached to the gadget, then a reply is sent on the application's behalf.

Action buttons

An action button is normally used to invoke an operation which is available from a dialogue box (e.g. a Cancel button or an OK button):

WINDOWS-4.GIF

Such a gadget contains a text string, which is specified when the gadget is created.

The above attributes can be set and read using the methods

ActionButton_SetText / ActionButton_GetText

Whenever the user clicks the Select or Adjust buttons on an action button an ActionButton_Selected event is raised with the flags word indicating which mouse button was used. The client can supply an alternative Toolbox event code in the template description for the action button, and can set and read this event code at run-time using the ActionButton_SetEvent and ActionButton_GetEvent methods.

The client can also specify an object which is to be shown when the action button is clicked on using the Select or Adjust buttons. The name of this object can be given in the action button template or manipulated at run-time using the ActionButton_SetClickShow and ActionButton_GetClickShow methods.

In a dialogue box, one action button can be chosen as the Default action button. This button is displayed with a distinctive border, and is activated when Return is pressed. An action button is marked as Default by setting a bit in the flags word for the gadget.

One action button can also be marked as the Cancel action button, by setting a bit in its flags word. This action button is also activated when its parent dialogue box has the input focus, and the user presses Escape.

By default, when an action button is clicked using Select, its parent dialogue box is closed. This behaviour can be over-ridden by setting a bit in the action button's flags word, to indicate that it is a 'local' button, whose effect is only to raise its associated Toolbox event. This facility is generally used for buttons which only have a local effect on the state of the dialogue box itself (e.g. a Try button in a font selector).

Clicking Adjust on an action button, raises its Toolbox event and keeps its parent dialogue box open (if it is marked as a Cancel action button, then the contents of any Gadgets are returned to how they were when the parent window was last shown). The Toolbox does not do this for you.

Bits in the flags word for an action button have the following meaning:

Bit Meaning
0 this is the Default action button
1 this is the Cancel action button
2 this is a local action button
3 if set, then the 'click show' object will be shown transiently (i.e. with Wimp_CreateMenu semantics - default is to show persistently)

Action button methods

ActionButton_SetText 128
On entry
R0 = flags
R1 = Window object id
R2 = 128
R3 = Gadget component id
R4 = pointer to text to appear in button
On exit
R1-R9 preserved
Use

This method sets the text which will be displayed in this action button.

C veneer

extern _kernel_oserror *actionbutton_set_text ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId action_button,
                                                char *text
                                              );

ActionButton_GetText 129
On entry
R0 = flags
R1 = Window object id
R2 = 129
R3 = Gadget component id
R4 = pointer to buffer
R5 = size of buffer
On exit
R5 = size of buffer required to hold text (if R4 was 0)
else buffer pointed at by R4 holds text
R5 holds number of bytes written to buffer
Use

This method returns the text which is currently displayed in this action button.

C veneer

extern _kernel_oserror *actionbutton_get_text ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId action_button,
                                                char *buffer,
                                                int buff_size,
                                                int *nbytes
                                              );

ActionButton_SetEvent 130
On entry
R0 = flags
R1 = Window object id
R2 = 130
R3 = Gadget component id
R4 = Toolbox event code
On exit
R1-R9 preserved
Use

This method sets the Toolbox event code which will be raised when this action button is clicked. The rest of the Toolbox event block remains the same as in ActionButton_Selected.

C veneer

extern _kernel_oserror *actionbutton_set_event ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId action_button,
                                                 int event
                                               );

ActionButton_GetEvent 131
On entry
R0 = flags
R1 = Window object id
R2 = 131
R3 = Gadget component id
On exit

R0 holds Toolbox event code

Use

This method returns the Toolbox event code which will be raised when this action button is clicked.

C veneer

extern _kernel_oserror *actionbutton_get_event ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId action_button,
                                                 int *event
                                               );

ActionButton_SetClickShow 132
On entry
R0 = flags
R1 = Window object id
R2 = 132
R3 = Gadget component id
R4 = object id of the object to show (or 0)
R5 = show flags:  
bit 0  
if clear show persistently
if set show transiently
On exit
R1-R9 preserved
Use

This method allows the client to specify the object to show when the user clicks Select or Adjust on the action button. 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.

C veneer

extern _kernel_oserror *actionbutton_set_click_show ( unsigned int flags,
                                                      ObjectId window,
                                                      ComponentId action_button,
                                                      ObjectId object,
                                                      int show_flags
                                                    );

ActionButton_GetClickShow 133
On entry
R0 = flags
R1 = Window object id
R2 = 133
R3 = Gadget component id
On exit
R0 = id of object to be shown
R1 = show flags
Use

This method returns the object id of the object which will be shown when the user clicks Select or Adjust on the action button. If bit 0 of R1 is set on exit, it means that the object will be shown transiently.

C veneer

extern _kernel_oserror *actionbutton_get_click_show ( unsigned int flags,
                                                      ObjectId window,
                                                      ComponentId action_button,
                                                      ObjectId *object,
                                                      int * show_flags
                                                    );

Action button Toolbox events

ActionButton_Selected (0x82881)
Block
+ 8 0x82881
+ 12 flags
bits 0, 1 and 2 show how the activation was done:
bit 0 set means Adjust was held down
bit 1 reserved
bit 2 set means Select was held down
If bits 0-2 are all 0, then Return was pressed on a default action button, or Escape was pressed activating the cancel action button.
bits 3, 4 and 5 indicate what type of button it is:
bit 3 set means that this is a Default action button
bit 4 set means that this is a Cancel action button
bit 5 set means that this is a local action button (i.e its parent window has not been closed)
Use

This Toolbox event is raised when the user clicks on an action button (or in the case of a default action button presses Return), and the client has not specified their own event to be associated with this button (by setting the event in the template to non-zero).

The returned flags word indicates whether the action button is a default and/or a cancel button, and also which mouse button was used to select the button.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
} ActionButtonSelectedEvent;

Action button templates

Field Size in bytes Type
text 4 MsgReference
max_text_len 4 word
click_show 4 StringReference
event 4 word

Adjuster arrows

An adjuster arrow gadget will be displayed as an up, down, left or right arrow icon, and clicking on the arrow will raise an Adjuster_Clicked Toolbox event, with an indication of whether the change is up or down:

WINDOWS-5.GIF

The adjuster arrow's flags word indicates whether the adjuster is an incrementor or decrementor. There is also a bit to indicate whether this is part of an 'up/down' or 'left/right' pair.

Bits in the flags word for an adjuster arrow have the following meaning:

Bit Meaning
0 set => 'increment'
clear => 'decrement'
1 set => one of an 'up/down' pair
clear => one of a 'left/right' pair

Adjuster arrows Toolbox events

Adjuster_Clicked (0x8288c)
Block
+ 8 0x8288c
+ 16 (0 => DOWN_ 1 => up)
Use

This Toolbox event is raised when the user clicks the mouse on an adjuster arrow (Adjust clicks on a down arrow are reported as 'up', on an up arrow as 'down').

C data type

typedef struct
{
  ToolboxEventHeader  hdr;
  int                 direction;
} AdjusterClickedEvent;

Adjuster arrow templates

There are no extra fields than those in the gadget header.

Button gadget

The Button gadget is similar to a Wimp icon. The main differences are that a Button will always have indirected data and that not all icon flags are settable:

  • A Button created as sprite only cannot be made into any sort of text Button.
  • A Button created as text only cannot be made into a sprite only Button.
  • A sprite only Button can only refer to sprites by name and these must be in the Wimp sprite pool or the task's sprite area.

Bits in the flags word for a Button gadget have the following meanings:

Bit Meaning
0 Use the task's sprite area (requires the window to have client sprite area) for sprite only buttons else use the Wimp sprite pool
1 return menu clicks

Button methods

Button_GetFlags 960
On entry
R0 = flags
R1 = Window object id
R2 = 960
R3 = Gadget component id
On exit
R0 = icon flags
R1-R9 preserved
Use

This method returns the flags of the given button gadget. The bits have the same meaning as those of a Wimp Icon.

C veneer

extern _kernel_oserror *button_get_flags ( unsigned int flags,
                                           ObjectId window,
                                           ComponentId button,
                                           int *icon_flags
                                         );

Button_SetFlags 961
On entry
R0 = flags
R1 = Window object id
R2 = 961
R3 = Gadget component id
R4 = clear word
R5 = EOR word
On exit
R1-R9 preserved
Use

This method sets the flags of a button. The effect of the clear word and the EOR word are analogous to those of Wimp_SetIconState, except that, as described above, not all combinations are settable.

C veneer

extern _kernel_oserror *button_set_flags ( unsigned int flags,
                                           ObjectId window,
                                           ComponentId button,
                                           int clear_word,
                                           int EOR_word
                                         );

Button_SetValue 962
On entry
R0 = flags
R1 = Window object id
R2 = 962
R3 = Gadget component id
R4 = new value
On exit
R1-R9 preserved
Use

This method sets the value (i.e. text or sprite name) of a Button.

C veneer

extern _kernel_oserror *button_set_value ( unsigned int flags,
                                           ObjectId window,
                                           ComponentId button,
                                           char *value
                                         );

Button_GetValue 963
On entry
R0 = flags
R1 = Window object id
R2 = 963
R3 = Gadget component id
R4 = pointer to buffer to hold string
R5 = size of buffer
On exit
R5 = size of buffer required (if R4 was 0)
else buffer pointed at by R4 holds string
R5 holds number of bytes written to buffer
Use

This method returns the value of a Button.

C veneer

extern _kernel_oserror *button_get_value ( unsigned int flags,
                                           ObjectId window,
                                           ComponentId button,
                                           char *buffer,
                                           int buff_size,
                                           int *nbytes
                                         );

Button_SetValidation 964
On entry
R0 = flags
R1 = Window object id
R2 = 964
R3 = Gadget component id
R4 = new value
On exit
R1-R9 preserved
Use

This method sets the validation string (e.g. sprite name) of a Button.

C veneer

extern _kernel_oserror *button_set_validation ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId button,
                                                char *value
                                              );

Button_GetValidation 965
On entry
R0 = flags
R1 = Window object id
R2 = 965
R3 = Gadget component id
R4 = pointer to buffer to hold string
R5 = size of buffer
On exit
R5 = size of buffer required (if R4 was 0)
else buffer pointed at by R4 holds string
R5 holds number of bytes written to buffer
Use

This method returns the validation string of a Button.

C veneer

extern _kernel_oserror *button_get_validation ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId button,
                                                char *buffer,
                                                int buff_size,
                                                int *nbytes
                                              );

Button_SetFont 966
On entry
R0 = flags
R1 = Window object id
R2 = 966
R3 = Gadget component id
R4 = pointer to font name to use
R5 = width in 16ths of a point
R6 = height in 16ths of a point
On exit
R1-R9 preserved
Use

This method makes the Button use an anti-aliased font. If the font name is NULL, then the field will use system font.

C veneer

extern _kernel_oserror *button_set_font ( unsigned int flags,
                                          ObjectId window,
                                          ComponentId button,
                                          char *font_name,
                                          int width,
                                          int height
                                        );

Button toolbox events

The button gadget does not have any toolbox events. All click or key presses are returned as Wimp events but with the component and window id of the tasks id block updated.

Button templates

Field Size in bytes Type
button_flags 4 Word
value 4 MsgReference
max_value 4 word
validation 4 StringReference
max_validation 4 word

Display fields

A display field gadget is used to display information in a 'read-only' manner:

WINDOWS-6.PNG

The display field has a 'slabbed in' boxed display area in which a text string is displayed. The contents of the display area can be set and read using the DisplayField_SetValue and DisplayField_GetValue methods.

Bits in the flags word for a Label have the following meaning:

Bit Meaning
1-2 justification:  
0 => left-justified
1 => right-justified
2 => centred

Display field methods

DisplayField_SetValue 448
On entry
R0 = flags
R1 = Window object id
R2 = 448
R3 = Gadget component id
R4 = pointer to text string to use
On exit
R1-R9 preserved
Use

This method sets the text string shown in a display field. The change is immediately visible if the parent dialogue box is currently on the screen.

C veneer

extern _kernel_oserror *displayfield_set_value ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId display_field,
                                                 char *text
                                               );

DisplayField_GetValue 449
On entry
R0 = flags
R1 = Window object id
R2 = 449
R3 = Gadget component id
R4 = pointer to buffer
R5 = size of buffer
On exit
R5 = size of buffer required else (if R4 was 0)
buffer pointed at by R4 contains text
R5 holds number of bytes written to buffer
Use

This method returns the text string shown in a display field.

C veneer

extern _kernel_oserror *displayfield_get_value ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId display_field,
                                                 char *buffer,
                                                 int buff_size,
                                                 int *nbytes
                                               );

DisplayField_SetFont 450
On entry
R0 = flags
R1 = Window object id
R2 = 450
R3 = Gadget component id
R4 = pointer to font name to use
R5 = width in 16ths of a point
R6 = height in 16ths of a point
On exit
R1-R9 preserved
Use

This method makes the display field use an anti-aliased font. If the font name is NULL, then the field will use system font.

C veneer

extern _kernel_oserror *displayfield_set_font ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId display_field,
                                                char *font_name,
                                                int width,
                                                int height
                                              );

Display field templates

Field Size in bytes Type
text 4 MsgReference
max_text_len 4 word

Draggable gadgets

A draggable gadget consists of a sprite, text or text&sprite which appears in a dialogue box, and can be dragged using the mouse. When the drag occurs, if this is a sprite or text&sprite draggable, then the Toolbox will use the standard CMOS bit to decide whether to do a 'solid' drag or a 'dotted line' drag.

Solid dragging makes use of the DragAnObject module allowing both text and sprite to be dragged (unlike DragASprite).

If it is a sprite draggable gadget, then the sprite used can be set and read dynamically using the Draggable_SetSprite/Draggable_GetSprite methods.

If it is a text draggable gadget, then the text used can be set and read dynamically using the Draggable_SetText/Draggable_GetText methods.

With a draggable of type click or doubleclick, a clicks or double click on the gadget will be returned as a Wimp mouse click event, but the toolbox id block will be updated to reflect the component and window (i.e. no special toolbox event is returned).

When the user begins to drag a draggable, the client can choose to receive a Draggable_DragStarted Toolbox event. When the drag ends, the client will always receive a Draggable_DragEnded Toolbox event.

Bits in the flags word for a draggable have the following meaning:

Bit Meaning
0 warn of drag start using Draggable_DragStarted
1 draggable contains a sprite
2 draggable contains text
3-5 Draggable type:  
0 => drag only
1 => click, drag, doubleclick
2 => click selects, doubleclick, drag
6 deliver drag ended events as Toolbox id's rather than Wimp windows (if possible)
7 dragged object has a drop shadow (if solid)
8 dragged object is not dithered (if solid)

Draggable methods

Draggable_SetSprite 640
On entry
R0 = flags
R1 = Window object id
R2 = 640
R3 = Gadget component id
R4 = pointer to sprite name to use
On exit
R1-R9 preserved
Use

This method sets the name of the sprite which will be used for this draggable.

C veneer

extern _kernel_oserror *draggable_set_sprite ( unsigned int flags,
                                               ObjectId window,
                                               ComponentId draggable,
                                               char *sprite_name
                                             );

Draggable_GetSprite 641
On entry
R0 = flags
R1 = Window object id
R2 = 641
R3 = Gadget component id
R4 = pointer to buffer (or 0)
R5 = size of buffer to hold sprite name
On exit
R5 = size of buffer required for message text (if R4 was 0)
else buffer pointed at by R4 holds sprite name
R5 holds number of bytes written to buffer
Use

This method returns the name of the sprite which is currently being used for this draggable.

C veneer

extern _kernel_oserror *draggable_get_sprite ( unsigned int flags,
                                               ObjectId window,
                                               ComponentId draggable,
                                               char *buffer,
                                               int buff_size,
                                               int *nbytes
                                             );

Draggable_SetText 642
On entry
R0 = flags
R1 = Window object id
R2 = 642
R3 = Gadget component id
R4 = pointer to text to use
On exit
R1-R9 preserved
Use

This method sets the text which will be displayed in this draggable.

C veneer

extern _kernel_oserror *draggable_set_text ( unsigned int flags,
                                             ObjectId window,
                                             ComponentId draggable,
                                             char *text
                                           );

Draggable_GetText 643
On entry
R0 = flags
R1 = Window object id
R2 = 643
R3 = Gadget component id
R4 = pointer to buffer
R5 = size of buffer
On exit
R5 = size of buffer required (if R4 was 0)
else buffer pointed at by R4 holds text
R5 holds number of bytes written to buffer
Use

This method returns the text which is currently being used for this draggable.

C veneer

extern _kernel_oserror *draggable_get_text ( unsigned int flags,
                                             ObjectId window,
                                             ComponentId draggable,
                                             char *buffer,
                                             int buff_size,
                                             int *nbytes
                                           );

Draggable_SetState 644
On entry
R0 = flags
R1 = Window object id
R2 = 644
R3 = Gadget component id
R4 = state (0 => DESELECTED_ 1 => selected).
On exit
R1-R9 preserved
Use

This method sets the Draggable's state to either selected or deselected.

C veneer

extern _kernel_oserror *draggable_set_state ( unsigned int flags,
                                              ObjectId window,
                                              ComponentId draggable,
                                              int state
                                            );

Draggable_GetState 645
On entry
R0 = flags
R1 = Window object id
R2 = 645
R3 = Gadget component id
On exit
R0 = state
Use

This method returns the Draggables' state (0 => DESELECTED_ 1 => selected).

C veneer

extern _kernel_oserror *draggable_get_state ( unsigned int flags,
                                              ObjectId window,
                                              ComponentId draggable,
                                              int *state
                                            );

Draggable Toolbox events

Draggable_DragStarted (0x82887)
Block
+ 8 0x82887
+ 12 flags  
bit 0 means Adjust is held down
bit 1 will be 0
bit 2 means Select is held down
bit 3 means Shift is held down
bit 4 means Ctrl is held down
Use

This Toolbox event is raised when the user starts a drag of a draggable gadget.

C data type

typedef struct
{
  ToolboxEventHeader    hdr;
} DraggableDragStartedEvent;

Draggable_DragEnded (0x82888)
Block
+ 8 0x82888
+ 12 flags:  
bit 0 clear then:  
+ 16 Wimp window handle of end of drag
+ 20 Wimp icon handle of end of drag
or bit 0 set:  
+ 16 Window id of end of drag
+ 20 component id of end of drag
+ 24 destination x coordinate of mouse pointer
+ 28 destination y coordinate of mouse pointer
Use

This Toolbox event is raised when the user ends a drag of a draggable gadget. By setting bit 6 when the draggable is created it is possible to receive events in terms of window object ids and gadget component ids. If the drag ended over a non-toolbox window (or bit 6 was zero) then Wimp handles are returned.

C data type

typedef struct
{
  ToolboxEventHeader  hdr;
  int                 window_handle;
  int                 icon_handle;
  int                 x;
  int                 y;
} DraggableDragEndedEvent;

Draggable templates

Field Size in bytes Type
text 4 MsgReference
max_text_len 4 word
sprite 4 StringReference
max_sprite_len 4 word

Labels

A label consists of some explanatory text which appears in a dialogue box. The client application can choose whether the bounding box of the label is shown by a visible box or not.

  • a label contains text, which is unchangeable at run-time
  • a label can be right-justified, left-justified, or centred, as indicated by its flags word.

Bits in the flags word for a label have the following meaning:

Bit Meaning
0 omit bounding box
1-2 justification:  
0 => left-justified
1 => right-justified
2 => centred

Label templates

Field Size in bytes Type
label 4 MsgReference

Labelled boxes

A labelled box gadget is used for collecting together a set of related items:

WINDOWS-7.PNG

The box has a label which can be either text or a sprite, and this label will appear at the top left hand corner of the box (a bit in the flags word for the gadget indicates whether text or a sprite is to be used). ResEd creates labelled boxes with bit 30 set so that they are created behind other gadgets.

There are no Toolbox events or methods associated with a labelled box.

Bits in the flags word for a labelled box have the following meaning:

Bit Meaning
0 labelled box has a sprite label (default is text)
1 in the case of a sprite label, the icon is filled if this bit is set, otherwise it is unfilled. This is because certain sprites will sufficiently obscure the border, and may be masked so should allow the tile sprite to show through.

Labelled box templates

Field Size in bytes Type
label 4 MsgReference or StringReference

Number ranges

A number range is a gadget used to display one of a range of possible integer or fixed point values. The value is shown in a display area, which can either be writable (in which case a writable field is used) or not writable (in which case a display field is used). It is also possible to create a Number Range where there is no display area.

The value which the client gives to a Number Range Gadget (and which it receives back) is a signed integer, to which a 'precision' will be applied. The precision is essentially the power of 10 by which the value should be divided, and the number of places which will be shown after the decimal point. For example to get the value 3.42 displayed in a Number Range the client would pass the value 342 with a precision of 2. Normally the precision of a Number Range is specified when the Gadget is created, but it can be set and read at run-time using the NumberRange_SetBounds and NumberRange_GetBounds methods. A Number Range can be made to display merely integer values by specifying a precision of 0. The maximum precision is 10, i.e. there can be up to ten digits after the decimal point.

The value displayed in a number range gadget is set using the NumberRange_SetValue method. The value passed is an integer which will be divided by 10^precision and will have precision digits after the decimal point. The value of a number range is read using the NumberRange_GetValue method; this value is an integer which should be divided by 10^precision to get its real equivalent. A number range has a lower and upper bound which constrains the values to which it can be set; these bounds are in 'integer' terms (i.e. before the precision has been applied). For example if a number range gadget has a precision of 3, and the client wishes to have a lower bound of 1.000 and an upper bound of 4.999, then the lower and upper bounds of the gadget should be set to 1000 and 4999 respectively.

A number range can also be given a step size. The step size is expressed in integer terms (i.e. before the precision is applied). For example if a number range gadget has a precision of 2, then setting a step size of 5 will result in a 'real' step size of 0.05. The bounds and step size can be set and read using the NumberRange_SetBounds and NumberRange_GetBounds methods.

A number range can also have a pair of adjuster arrows placed 8 OS Units to the right of its display area (either the writable or display field). When the user clicks on these arrows, the value of the number range is either decremented or incremented by its step size, subject to its lower and upper bounds (and displayed using its precision).

A number range can also have an associated slider. The slider is like a slider gadget, except that it can only be positioned relative to the Number Range's display area. The possible positionings are:

  • a horizontal slider 8 OS Units to the right of the display area
  • a horizontal slider 8 OS Units to the left of the display area.

When both a slider and adjusters are requested, then the adjusters appear at either end of the slider, rather than the positioning outlined above.

If the Number Range is writable, then the underlying Writable Field is given a validation string which will only permit input of numeric digits (0-9), the decimal point character for the current territory (unless the precision field is 0) and where applicable the minus sign. It also has 'before' and 'after' values which are used to move the caret in the same way as described for Writable Fields. Another Writable may reference the component id of a Number Range in its before and after fields.

Whenever the value changes in a number range gadget, the client is informed of the change via an NumberRange_ValueChanged Toolbox event, if it has set the appropriate bit in the gadget's flags word.

Included in the definition of the number range is the length of the display field in OS Units (display_length as shown in Number range templates). This is ignored if there is no slider.

Bits in the flags word for a number range gadget have the following meanings:

Bit Meaning when set
0 inform client of value changes using NumberRange_ValueChanged
2 writable (default is read-only display)
3 no display area
4 has adjuster arrows
5-7 slider type:  
0 => no slider
1 => slider to the right of the display area
2 => slider to the left of the display area
8-9 justification:  
0 => left-justified
1 => right-justified
2 => centred
12-15 desktop colour of slider bar
16-19 desktop colour of slider background

Note: slider colours are in the same flag position as a Slider Gadget.

Number range methods

NumberRange_SetValue 832
On entry
R0 = flags
R1 = Window object id
R2 = 832
R3 = Gadget component id
R4 = new value
On exit
R1-R9 preserved
Use

This method sets the value displayed in the number range's display area, subject to its bound constraints. The value will be displayed taking into account its precision.

C veneer

extern _kernel_oserror *numberrange_set_value ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId number_range,
                                                int value
                                              );

NumberRange_GetValue 833
On entry
R0 = flags
R1 = Window object id
R2 = 833
R3 = Gadget component id
On exit

R0 holds current value

Use

This method returns the value of the number range. Note that this is the integer form of what is actually displayed in the display area (i.e. not taking 'precision' into account).

C veneer

extern _kernel_oserror *numberrange_get_value ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId number_range,
                                                int *value
                                              );

NumberRange_SetBounds 834
On entry
R0 = flags  
bit 0 set means change the lower bound
bit 1 set means change the upper bound
bit 2 set means change the step size
bit 3 set means change the precision
R1 = Window object id
R2 = 834
R3 = Gadget component id
R4 = new lower bound
R5 = new upper bound
R6 = new step size
R7 = precision
On exit
R1-R9 preserved
Use

This method is used to set the lower and upper bounds, the step size and the precision of the number range. Note that the bounds and step size are expressed in terms of an integer before they are transformed using the precision value.

C veneer

extern _kernel_oserror *numberrange_set_bounds ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId number_range,
                                                 int lower_bound,
                                                 int upper_bound,
                                                 int step_size,
                                                 int precision
                                               );

NumberRange_GetBounds 835
On entry
R0 = flags  
bit 0 set means return the lower bound
bit 1 set means return the upper bound
bit 2 set means return the step size
bit 3 set means return the precision
R1 = Window object id
R2 = 835
R3 = Gadget component id
On exit
R0 = lower bound
R1 = upper bound
R2 = step size
R3 = precision
Use

This method returns the lower and upper bounds, the step size and the precision of the number range, depending on the setting of the appropriate flags bits. Note that the bounds and step size are expressed in terms of an integer before they are transformed using the precision value.

C veneer

extern _kernel_oserror *numberrange_get_bounds ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId number_range,
                                                 int *lower_bound,
                                                 int *upper_bound,
                                                 int *step_size,
                                                 int *precision
                                               );

NumberRange_GetComponents 836
On entry
R0 = flags  
bit 0 set means return the numerical field
bit 1 set means return the left adjuster
bit 2 set means return the right adjuster
bit 3 set means return the slider
R1 = Window object id
R2 = 836
R3 = Gadget component id
On exit
R0 = numeric id
R1 = left adjuster id
R2 = right adjuster id
R3 = slider id
Use

This method returns the component ids of the gadgets that make up the number range depending on which flag bits are set. Note that the numeric id will be the component id of the Display Field or Writable, dependent on how the Gadget was created.

C veneer

extern _kernel_oserror *numberrange_get_components ( unsigned int flags,
                                                     ObjectId window,
                                                     ComponentId number_range,
                                                     ComponentId *numeric_field,
                                                     ComponentId *left_adjuster,
                                                     ComponentId *right_adjuster,
                                                     ComponentId *slider
                                                   );

Number range Toolbox events

NumberRange_ValueChanged (0x8288d)
Block
+ 8 0x8288d
+ 16 new value shown in display area
Use

This Toolbox event is raised when the value of the Number Range has changed.

C data type

typedef struct
{
  ToolboxEventHeader  hdr;
  int                 new_value;
} NumberRangeValueChangedEvent;

Number range templates

Field Size in bytes Type
lower_bound 4 word
upper_bound 4 word
step_size 4 word
initial_value 4 word
precision 4 word
before 4 word
after 4 word
display_length 4 word

Option buttons

An option button is used to indicate whether a particular option has been chosen or not (e.g. case-sensitive in a Find dialogue box). It has two states - on and off:

WINDOWS-8.PNG

Such a gadget is displayed with a standard option icon, together with a textual label; the textual label can be read and set at run-time using the OptionButton_SetLabel and OptionButton_GetLabel methods.

The on/off state of the option button can be set and read using the OptionButton_SetState/OptionButton_GetState methods.

If bit zero of the flags is set, then whenever the state of the Option Button changes, an OptionButton_StateChanged event is raised, with the flags word indicating which mouse button was used. The client can supply an alternative Toolbox Event code in the template description for the Option Button, and can set and read this event code at run-time using the OptionButton_SetEvent and OptionButton_GetEvent methods.

Bits in the flags word for Option Button have the following meaning:

Bit Meaning
0 generate a OptionButton_StateChanged when user clicks.
2 when set, this means that the Option Button is 'On' when first created.

Option button methods

OptionButton_SetLabel 192
On entry
R0 = flags
R1 = Window object id
R2 = 192
R3 = Gadget component id
R4 = pointer to string giving label to use
On exit
R1-R9 preserved
Use

This method sets the label which will be used for this option button.

C veneer

extern _kernel_oserror *optionbutton_set_label ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId option_button,
                                                 char *label
                                               );

OptionButton_GetLabel 193
On entry
R0 = flags
R1 = Window object id
R2 = 193
R3 = Gadget component id
R4 = pointer to buffer
R5 = size of buffer
On exit
R5 = size of buffer required to hold label (if R4 was 0)
else buffer pointed at by R4 holds label
R5 holds number of bytes written to buffer
Use

This method returns the label which is currently displayed for this option button.

C veneer

extern _kernel_oserror *optionbutton_get_label ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId option_button,
                                                 char *buffer,
                                                 int buff_size,
                                                 int *nbytes
                                               );

OptionButton_SetEvent 194
On entry
R0 = flags
R1 = Window object id
R2 = 194
R3 = Gadget component id
R4 = Toolbox event code
On exit
R1-R9 preserved
Use

This method sets the Toolbox event which will be raised when the state of this option button changes. The rest of the Toolbox event block remains the same as in OptionButton_StateChanged.

C veneer

extern _kernel_oserror *optionbutton_set_event ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId option_button,
                                                 int event
                                               );

OptionButton_GetEvent 195
On entry
R0 = flags
R1 = Window object id
R2 = 195
R3 = Gadget component id
On exit

R0 holds Toolbox event code.

Use

This method returns the Toolbox event which will be raised when this option button's state changes.

C veneer

extern _kernel_oserror *optionbutton_get_event ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId option_button,
                                                 int *event
                                               );

OptionButton_SetState 196
On entry
R0 = flags
R1 = Window object id
R2 = 196
R3 = Gadget component id
R4 = state (0 => OFF_ 1 => on)
On exit
R1-R9 preserved
Use

This method sets the option button's state to on or off.

C veneer

extern _kernel_oserror *optionbutton_set_state ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId option_button,
                                                 int state
                                               );

OptionButton_GetState 197
On entry
R0 = flags
R1 = Window object id
R2 = 197
R3 = Gadget component id
On exit
R0 = state
Use

This method returns the option button's state (0 => OFF_ 1 => on).

C veneer

extern _kernel_oserror *optionbutton_get_state ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId option_button,
                                                 int *state
                                               );

Option button Toolbox events

OptionButton_StateChanged (0x82882)
Block
+ 8 0x82882
+ 12 flags
bits 0, 1 and 2 show how the activation was done:
bit 0 set means Adjust was held down
bit 1 reserved
bit 2 set means Select was held down
+ 16 new state (0 => OFF_ 1 => on)
Use

This Toolbox event is raised when the state of an option button changes, and the client has not specified an event to be associated with this change.

The returned flags word indicates which mouse button was used to select the button.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  int                new_state;
} OptionButtonStateChangedEvent;

Option button templates

Field Size in bytes Type
flags 4 word
label 4 MsgReference
max_label_len 4 word
event 4 word

Pop-up menus

A pop-up menu gadget will be displayed as a 'menu-arrow' icon, and its associated Menu object will be displayed when a mouse button is clicked over this icon:

WINDOWS-9.GIF

The Menu to be displayed can be set and read dynamically at run-time using the PopUp_SetMenu and PopUp_GetMenu methods. It can also be done with ResEd.

If the appropriate bit is set in the flags word, then a PopUp_AboutToBeShown Toolbox event is delivered before the associated pop-up Menu is shown. This allows the client to build a new Menu object and associate it with the pop-up using PopUp_SetMenu.

Note that Menu 'hits' will be reported for the Menu object, and not for the pop-up gadget. The Menu will have as its parent, the dialogue box in which the pop-up exists, and the pop-up itself as the parent component. Note also that the associated pop-up Menu may also have its flags word bit set which requests a warning before it is shown; this event will be delivered after the PopUp_AboutToBeShown event.

Bits in the flags word for a pop-up Menu have the following meaning:

Bit Meaning
0 warn using PopUp_AboutToBeShown before the associated menu is shown.

Pop-up menu methods

PopUp_SetMenu 704
On entry
R0 = flags
R1 = Window object id
R2 = 704
R3 = Gadget component id
R4 = object id of Menu to use
On exit
R1-R9 preserved
Use

This method sets the Menu object which will be shown when the pop-up button is clicked on.

C veneer

extern _kernel_oserror *popup_set_menu ( unsigned int flags,
                                         ObjectId window,
                                         ComponentId popup,
                                         ObjectId menu
                                       );

PopUp_GetMenu 705
On entry
R0 = flags
R1 = Window object id
R2 = 705
R3 = Gadget component id
On exit
R0 = Menu object id
Use

This method returns the object id of the Menu which will be shown when the pop-up button is clicked on.

C veneer

extern _kernel_oserror *popup_get_menu ( unsigned int flags,
                                         ObjectId window,
                                         ComponentId popup,
                                         ObjectId *menu
                                       );

Pop-up menu Toolbox events

PopUp_AboutToBeShown (0x8288b)
Block
+ 8 0x8288b
+ 16 object id of Menu object which will be shown
(note that the 'self' id and component fields will refer to the
parent Window's object id and the PopUp's component id respectively)
Use

This Toolbox event is raised when the user has clicked on a pop-up button. The Menu is actually shown on the next call to Wimp_Poll.

C data type

typedef struct
{
  ToolboxEventHeader  hdr;
  ObjectId            menu_id;
}PopUpAboutToBeShownEvent;

Pop-up menu templates

Field Size in bytes Type
menu 4 StringReference

Radio buttons

A radio button is used for making a single choice from a set of options, and a number of radio buttons are normally used in a 'group'. The group to which a radio button belongs is determined by the radio button's 'group number'.

A radio button is displayed as a standard radio icon, together with a text label. The label for a radio button can be set and read using the RadioButton_SetLabel and RadioButton_GetLabel methods.

A radio button has two states: 'On' and 'Off'. Only one radio button in a group is in the on state at any one time. When the user clicks on a radio button its state is set to on.

WINDOWS-10.PNG

Whenever the state of a radio button changes, a RadioButton_StateChanged event is raised, with the flags word indicating which mouse button was used, if the appropriate bit was set in the flags word for the radio button, requesting that a RadioButton_StateChanged event is generated. The client can supply an alternative Toolbox event code in the template description for the radio button, and can set and read this event code at run-time using the RadioButton_SetEvent and RadioButton_GetEvent methods.

Bits in the flags word for a radio button have the following meaning:

Bit Meaning
0 generate a RadioButton_StateChanged when user clicks
2 when set, means that the radio button is On when first created

Radio button methods

RadioButton_SetLabel 384
On entry
R0 = flags
R1 = Window object id
R2 = 384
R3 = Gadget component id
R4 = pointer to string giving label to use
On exit
R1-R9 preserved
Use

This method sets the label which will be used for this radio button.

C veneer

extern _kernel_oserror *radiobutton_set_label ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId radio_button,
                                                char *label
                                              );

RadioButton_GetLabel 385
On entry
R0 = flags
R1 = Window object id
R2 = 385
R3 = Gadget component id
R4 = pointer to buffer
R5 = size of buffer
On exit
R5 = size of buffer required to hold label (if R4 was 0)
else buffer pointed at by R4 holds label
R5 holds number of bytes written to buffer
Use

This method returns the label which is currently displayed for this radio button.

C veneer

extern _kernel_oserror *radiobutton_get_label ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId radio_button,
                                                char *buffer,
                                                int buff_size,
                                                int *nbytes
                                              );

RadioButton_SetEvent 386
On entry
R0 = flags
R1 = Window object id
R2 = 386
R3 = Gadget component id
R4 = Toolbox event code
On exit
R1-R9 preserved
Use

This method sets the Toolbox event which will be raised when the state of the radio button changes. The rest of the Toolbox event block will be the same as for the RadioButton_StateChanged Toolbox event.

C veneer

extern _kernel_oserror *radiobutton_set_event ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId radio_button,
                                                int event
                                              );

RadioButton_GetEvent 387
On entry
R0 = flags
R1 = Window object id
R2 = 387
R3 = Gadget component id
On exit

R0 holds Toolbox event code

Use

This method returns the Toolbox event which will be raised when this radio button's state changes.

C veneer

extern _kernel_oserror *radiobutton_get_event ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId radio_button,
                                                int *event
                                              );

RadioButton_SetState 388
On entry
R0 = flags
R1 = Window object id
R2 = 388
R3 = Gadget component id
R4 = state (0 => OFF_ 1 => On)
On exit
R1-R9 preserved
Use

This method sets the state of the radio button to On or Off. When a button which is Off is set to On, the button which was previously On is set to Off. If by setting the radio button to Off, this would result in no button being On in the group, then an error is returned.

C veneer

extern _kernel_oserror *radiobutton_set_state ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId radio_button,
                                                int state
                                              );

RadioButton_GetState 389
On entry
R0 = flags
R1 = Window object id
R2 = 389
R3 = Gadget component id
On exit
R0 = state (0 => OFF_ 1 => On)
R1 = component id of radio button which is On in the group
Use

This method returns the state of the given radio button.

The client can determine which radio button is On in a group by calling this method for any one button in the group, since the component id of the On button is also returned (in R1).

C veneer

extern _kernel_oserror *radiobutton_get_state ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId radio_button,
                                                int *state,
                                                Component Id *selected
                                              );

Radio button Toolbox events

RadioButton_StateChanged (0x82883)
Block
+ 8 0x82883
+ 12 flags  
bits 0, 1 and 2 show how the activation was done:
bit 0 set means Adjust was held down
bit 1 is reserved
bit 2 set means Select was held down
+ 16 state (0 => OFF_ 1 => On)
+ 20 component id of the radio button within the group which was On before this state change
Use

This Toolbox event is raised when the state of a radio button changes, and the client has not specified an event to be associated with this change.

The returned flags word indicates which mouse button was used to select the radio button.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  int                state;
  ComponentId        old_on_button;
} RadioButtonStateChangedEvent;

Radio button templates

Field Size in bytes Type
group_number 4 word
label 4 MsgReference
max_label_len 4 word
event 4 word

Sliders

A slider gadget is used to display a 'bar', which may be draggable by the user, displayed in a 'well'. Whether the slider is draggable or not is indicated by its flags word:

WINDOWS-11.PNG

By setting a bit in the slider's flags word the client can request that all changes in the slider's value are returned as the bar is dragged. Alternatively it may request to receive value changes only when the bar dragging stops (i.e. when the user releases the mouse button). Such changes are reported via the Slider_ValueChanged Toolbox event.

A slider is specified as either being 'vertical' or 'horizontal'.

A slider has associated with it an initial value, a minimum value, a maximum value, and a step size. If the slider is draggable (indicated by a flags bit), then when the user drags the bar with the mouse, the bar moves a number of pixels commensurate with the step size, and the bounding box of the slider.

The maximum and minimum values and the step size can be set and read dynamically using the Slider_SetBound/Slider_GetBound methods.

A Slider also has associated with it, the colour used for its 'bar' - this is a Desktop colour. This is normally specified in the resource file, but can be set and read dynamically using the Slider_SetColour/Slider_GetColour methods.

The current value of the slider can be set and read using the Slider_SetValue/Slider_GetValue methods.

Bits in the flags word for a slider have the following meaning:

Bit Meaning
0 if set then deliver value changes when user clicks/drags
1 if set then deliver value changes constantly whilst dragging else just at start/end
3 if set means slider is vertical (default is horizontal)
4 if set then bar is draggable/clickable
12-15 the desktop colour of the bar
16-19 the desktop colour of the background

Slider methods

Slider_SetValue 576
On entry
R0 = flags
R1 = Window object id
R2 = 576
R3 = Gadget component id
R4 = integer value
On exit
R1-R9 preserved
Use

This method sets the value of a slider. The slider's bar is changed accordingly.

C veneer

extern _kernel_oserror *slider_set_value ( unsigned int flags,
                                           ObjectId window,
                                           ComponentId slider,
                                           int value
                                         );

Slider_GetValue 577
On entry
R0 = flags
R1 = Window object id
R2 = 577
R3 = Gadget component id
On exit
R0 = slider's value
Use

This method returns the value of a slider.

C veneer

extern _kernel_oserror *slider_get_value ( unsigned int flags,
                                           ObjectId window,
                                           ComponentId slider,
                                           int *value
                                         );

Slider_SetBound 58
On entry
R0 = flags  
bit 0 set means set upper bound
bit 1 set means set lower bound
bit 2 set means set step size
R1 = Window object id
R2 = 578
R3 = Gadget component id
R4 = upper bound
R5 = lower bound
R6 = step size
On exit
R1-R9 preserved
Use

This method sets the lower bound, upper bound and step size of a slider gadget.

C veneer

extern _kernel_oserror *slider_set_bound ( unsigned int flags,
                                           ObjectId window,
                                           ComponentId slider,
                                           int upper_bound,
                                           int lower_bound,
                                           int step_size
                                         );

Slider_GetBound 579
On entry
R0 = flags  
bit 0 set means return upper bound
bit 1 set means return lower bound
bit 2 set means return step size
R1 = Window object id
R2 = 579
R3 = Gadget component id
On exit
R0 = upper bound
R1 = lower bound
R2 = step size
Use

This method returns the lower bound, upper bound and step size of a slider gadget.

C veneer

extern _kernel_oserror *slider_get_bound ( unsigned int flags,
                                           ObjectId window,
                                           ComponentId slider,
                                           int *upper_bound,
                                           int *lower_bound,
                                           int *step_size
                                         );

Slider_SetColour 580
On entry
R0 = flags
R1 = Window object id
R2 = 580
R3 = Gadget component id
R4 = Desktop colour value for bar
R5 = Desktop colour value for background
On exit
R1-R9 preserved
Use

This method sets the Desktop colour used in a slider.

C veneer

extern _kernel_oserror *slider_set_colour ( unsigned int flags,
                                            ObjectId window,
                                            ComponentId slider,
                                            int bar_colour,
                                            int back_colour
                                          );

Slider_GetColour 581
On entry
R0 = flags
R1 = Window object id
R2 = 581
R3 = Gadget component id
On exit
R0 = Desktop colour value for bar
R1 = Desktop colour value for background
Use

This method returns the Desktop colour used in a slider.

C veneer

extern _kernel_oserror *slider_get_colour ( unsigned int flags,
                                            ObjectId window,
                                            ComponentId slider,
                                            int *bar_colour,
                                            int *back_colour
                                          );

Slider Toolbox events

Slider_ValueChanged (0x82886)
Block
+ 8 0x82886
+ 12 flags:  
bits 0-2:  
0 means 'start of drag or just click'
1 means 'drag still in progress'
2 means 'drag has ended'
+ 16 new value of slider.
Use

This Toolbox event is raised when the value of the slider has changed. This may be due to an update caused by a user action (e.g. dragging the bar).

C data type

typedef struct
{
  ToolboxEventHeader  hdr;
  int                 new_value;
} SliderValueChangedEvent;

Slider templates

Field Size in bytes Type
lower_bound 4 word
upper_bound 4 word
step_size 4 word
initial_value 4 word

String sets

A string set is a gadget used to display one of an ordered set of text strings.

The string which is shown in the display area is known as the 'selected string'. The display area can be either writable (in which case a writable field is used) or not writable (in which case a display field is used).

A string set has a pop-up Menu placed 8 OS Units to the right of the display area. The client supplies a set of available strings, and the Toolbox will display the selected string in the string set's display area. The Toolbox will build a Menu on the client's behalf, and display it when the pop-up menu button is clicked. The selected string will be shown as ticked in the Menu, and hits on the Menu will result in the string corresponding to the Menu entry text becoming the selected string.

If the string set is writable, then if the user enters a string which is not in the string set, no entry would be shown as ticked in an associated pop-up Menu.

The set of available strings can be set at run-time using the StringSet_SetAvailable method. The selected string is set and read using the StringSet_SetSelected and StringSet_GetSelected methods.

Whenever the selected string changes in a string set gadget, the client is informed of the change via a StringSet_ValueChanged Toolbox event, if it has set the appropriate bit in the gadget's flags word.

If a string set is writable, it can also have a set of allowable characters which the user can type into the display area. This is identical to the 'a' directive used in a Wimp icon's validation string.

The set of allowable characters can be set at run-time using the StringSet_SetAllowable method.

In the template description for a writable string set, the client specifies the component ids of any writable fields which come before and after it. These are used to move the caret between writable fields when the user presses the arrow and tab keys. A special value of -1 indicates that there is no writable field before or after this one.

Bits in the flags word for a string set gadget have the following meanings:

Bit Meaning
0 inform client of changes to the selected string using StringSet_ValueChanged
1 writable (default is read-only display)
3 inform client just before showing the menu
4 does not have any display field or writable
5-6 justification:
0 => left-justified
1 => right-justified
2 => centred

String set methods

StringSet_SetAvailable 896
On entry
R0 = flags
R1 = Window object id
R2 = 896
R3 = Gadget component id
R4 = pointer to block of contiguous strings which are to be used as the
available set of strings
On exit
R1-R9 preserved
Use

This method is used to set the available set of strings in a string set, and a pop-up menu will be built from them. Strings are separated using a comma (','); a comma must be escaped using the \ character, if the client wishes it to appear in the display area. To get the '\' character itself, '\\' should be used.

Note that there is no StringSet_GetAvailable.

C veneer

extern _kernel_oserror *stringset_set_available ( unsigned int flags,
                                                  ObjectId window,
                                                  ComponentId string_set,
                                                  char *strings
                                                );

StringSet_SetSelected 898
On entry
R0 = flags  
bit 0 set means index of string is supplied in R4
clear means the string itself is supplied
R1 = Window object id
R2 = 898
R3 = Gadget component id
R4 = pointer to string to be selected or R4 = index of string to be selected
On exit
R1-R9 preserved
Use

This method sets which string in the string set is selected. The string can either be specified as a text string or as an index into the array of available strings (depending on the setting of bit 0 in the flags word). The selected string is shown in the string set's display area, and will be ticked in the associated pop-up Menu.

C veneer

extern _kernel_oserror *stringset_set_selected ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId string_set,
                                                 char *string_to_select
                                               );

StringSet_GetSelected 899
On entry
R0 = flags  
bit 0 set means return index of selected string
clear means the string itself is returned
R1 = Window object id
R2 = 899
R3 = Gadget component id
R4 = index of selected string or R4 = pointer to buffer to hold selected string
R5 = size of buffer
On exit
R0 = index of selected string (if bit 0 of flags word was set)
else
if R4 was 0 then R5 holds size of buffer required
else
buffer pointed at by R4 holds selected string
R5 holds number of bytes written to buffer
Use

This method returns the currently selected string for this string set (i.e. the one shown in the display area). This may be either an index into the set of available strings or a buffer containing the string itself. If the selected string is not in the available set (e.g. it has been typed into a writable string set), then the value -1 is returned if an index is requested (by setting bit 0 of the flags word for this call).

C veneer

extern _kernel_oserror *stringset_get_selected ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId string_set,
                                                 ...
                                               );

StringSet_SetAllowable 900
On entry
R0 = flags
R1 = Window object id
R2 = 900
R3 = Gadget component id
R4 = pointer to string giving new set of allowable characters
On exit
R1-R9 preserved
Use

This method defines the set of allowable characters which can be typed into a writable string set. The set is specified in the same way as a Wimp 'a' validation string directive (without including the letter 'a').

C veneer

extern _kernel_oserror *stringset_set_allowable ( unsigned int flags,
                                                  ObjectId window,
                                                  ComponentId string_set,
                                                  char *allowable
                                                );

StringSet_GetComponents 902
On entry
R0 = flags  
bit 0 set means return the alphanumerical field
bit 1 set means return the popup menu
R1 = Window object id
R2 = 902
R3 = Gadget component id
On exit
R0 = alphanumeric id
R1 = popup id
Use

This method returns the component ids of the gadgets that make up the string set depending on which flag bits are set. Note that the alphanumeric id will be the component id of the Display Field or Writable, dependent on how the Gadget was created.

C veneer

extern _kernel_oserror *stringset_get_components ( unsigned int flags,
                                              ObjectId window,
                                              ComponentId string_set,
                                              ComponentId *alphanumeric_field,
                                              ComponentId *popup_menu
                                                 );

String set Toolbox events

StringSet_ValueChanged (0x8288e)
Block
+ 8 0x8288e
+ 12 flags
if bit 0 is set, then the text string was too long to fit into the event block
+ 16... text string shown in string set's display area (or null string if too long to fit)
Use

This Toolbox event is raised when the value of the string set has changed. If the text string was too long to fit into the event block, then bit 0 of the flags word is set.

C data type

typedef struct
{
  ToolboxEventHeader  hdr;
  char                string[sizeof(ToolboxEvent)-sizeof(ToolboxEventHeader)];
} StringSetValueChangedEvent;

StringSet_AboutToBeShown (0x8288f)
Block
+ 8 0x8288f
Use

This Toolbox event is raised just before the string set's menu is to be shown. This allows the client to make changes to the string set just when it is used, rather than continually.

C data type

typedef struct
{
  ToolboxEventHeader  hdr;
} StringSetAboutToBeShownEvent;

String set templates

Field Size in bytes Type
string_set 4 MsgReference
initial_selected_string 4 MsgReference
max_selected_string_len 4 word
allowable 4 MsgReference
max_allowable 4 word
before 4 word
after 4 word

Writable fields

The writable field has a boxed display area in which a text string is displayed and can be edited by the user. The contents of the display area can be set and read using the WritableField_SetValue and WritableField_GetValue methods. The user can click the mouse in a writable field and enter its value from the keyboard:

WINDOWS-12.PNG

Whenever the value in a writable field is changed, the client receives a WritableField_ValueChanged Toolbox event, if it has set the appropriate bit in the flags word. This will happen when the user presses a key whilst the caret is in it.

Note that it is possible to get different values from Writable_GetValue on subsequent calls, without receiving a ValueChanged Event in between. This is because the value represents what is actually visible in the gadget.

A writable field can also have a set of allowable characters which the user can type into the display area. This is identical to the 'a' directive used in a Wimp icon's validation string.

The set of allowable characters can be set at run-time using the WritableField_SetAllowable method. To allow all characters, this attribute should be NULL.

In the template description for a writable field, the client specifies the component ids of writable fields which come 'before' and 'after' it. These are used to move the caret between writable fields when the user presses the arrow and tab keys. A special value of -1 indicates that there is no writable field before or 'after this one. The exact semantics for the keys are as follows:

up-arrow or shift-TAB move the caret to the writable field before the one which currently has the caret
down-arrow or TAB move the caret to the writable field after the one which currently has the caret

Bits in the flags word for a writable field have the following meaning:

Bit Meaning
0 inform of value changes using WritableField_ValueChanged
2-3 justification:
0 => left-justified
1 => right-justified
2 => centred
4 do not display text, use '-' for each character (password support)

Writable field methods

WritableField_SetValue 512
On entry
R0 = flags
R1 = Window object id
R2 = 512
R3 = Gadget component id
R4 = pointer to text string to use
On exit
R1-R9 preserved
Use

This method sets the text string shown in a writable field. The change is immediately visible if the parent dialogue box is currently on the screen.

C veneer

extern _kernel_oserror *writablefield_set_value ( unsigned int flags,
                                                  ObjectId window,
                                                  ComponentId writable,
                                                  char *text
                                                );

WritableField_GetValue 513
On entry
R0 = flags
R1 = Window object id
R2 = 513
R3 = Gadget component id
R4 = pointer to buffer
R5 = size of buffer
On exit
R5 = size of buffer required (if R4 was 0)
else buffer pointed at by R4 contains text
R5 holds number of bytes written to buffer
Use

This method returns the text string shown in a writable field.

C veneer

extern _kernel_oserror *writablefield_get_value ( unsigned int flags,
                                                  ObjectId window,
                                                  ComponentId writable,
                                                  char *buffer,
                                                  int buff_size,
                                                  int *nbytes
                                                );

WritableField_SetAllowable 514
On entry
R0 = flags
R1 = Window object id
R2 = 514
R3 = Gadget component id
R4 = pointer to string giving new set of allowable characters
On exit
R1-R9 preserved
Use

This method defines the set of allowable characters which can be typed into a writable field. The set is specified in the same way as a Wimp 'a' validation string directive (without including the letter 'a'). If the string is NULL, then all characters are allowable.

C veneer

extern _kernel_oserror *writablefield_set_allowable ( unsigned int flags,
                                                      ObjectId window,
                                                      ComponentId writable,
                                                      char *allowed
                                                    );

WritableField_SetFont 516
On entry
R0 = flags
R1 = Window object id
R2 = 516
R3 = Gadget component id
R4 = pointer to font name to use
R5 = width in 16ths of a point
R6 = height in 16ths of a point
On exit
R1-R9 preserved
Use

This method makes the writable field use an anti-aliased font. If the font name is NULL, then the field will use system font.

C veneer

extern _kernel_oserror *writablefield_set_font ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId writable_field,
                                                 char *font_name,
                                                 int width,
                                                 int height
                                               );

Writable field Toolbox events

WritableField_ValueChanged (0x82885)
Block
+ 8 0x82885
+ 12 flags
if bit 0 is set, then the text string was too long to fit into the event block
+ 16... text string shown in writable field
Use

This Toolbox event is raised when the value of the writable field has changed. The text string is copied into the event block, and is nul-terminated. If the text string was too long to fit into the event block, then bit 0 of the flags word is set and a null string is supplied.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  char               string[sizeof(ToolboxEvent)-sizeof(ToolboxEventHeader)];
} WritableFieldValueChangedEvent;

Writable field templates

Field Size in bytes Type
text 4 MsgReference
max_text_len 4 word
allowable 4 MsgReference
max_allowable_len 4 word
before 4 word
after 4 word

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