|
www.riscos.com Technical Support: |
A Window is essentially an extension of a Wimp window (in fact part of the Window object definition is a Wimp window definition):
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).
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.
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.
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.
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):
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):
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.
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 | ||
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.
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.
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.
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.
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.
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.
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.
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 |
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 0 |
| R0 | = | Wimp window handle for this window |
This method returns the handle of the underlying Wimp window used to implement this Window object.
extern _kernel_oserror *window_get_wimp_handle ( unsigned int flags,
ObjectId window,
int *window_handle
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 1 |
| R3 | = | pointer to description block for gadget |
| R0 | = | component id |
| R1-R9 | preserved | |
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.
extern _kernel_oserror *window_add_gadget ( unsigned int flags,
ObjectId window,
Gadget *gadget,
ComponentId *gadget_component
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 2 |
| R3 | = | component id |
| R1-R9 | preserved |
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.
extern _kernel_oserror *window_remove_gadget ( unsigned int flags,
ObjectId window,
ComponentId gadget
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 3 |
| R3 | = | menu object id |
| R1-R9 | preserved |
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.
extern _kernel_oserror *window_set_menu ( unsigned int flags,
ObjectId window,
ObjectId menu_id
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 4 |
| R0 | = | Menu id |
This method is used to get the id of the Menu which will be displayed when the Menu button is pressed over this Window object.
extern _kernel_oserror *window_get_menu ( unsigned int flags,
ObjectId window,
ObjectId *menu_id
);
| 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 |
| R1-R9 | preserved |
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.
extern _kernel_oserror *window_set_pointer ( unsigned int flags,
ObjectId window,
char *sprite_name,
int x_hot_spot,
int y_hot_spot
);
| 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 |
| 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 |
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.
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
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 7 |
| R3 | = | pointer to message text |
| R1-R9 | preserved |
This method is used to set the help message which will be returned when a Help Request message is received for this Window object. The Toolbox handles the reply message for you.
If R3 is 0, then the Help Message for this Window is removed.
extern _kernel_oserror *window_set_help_message ( unsigned int flags,
ObjectId window,
char *message_text
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 8 |
| R3 | = | pointer to buffer |
| R4 | = | size of buffer to hold message text |
| R4 | = | size of buffer required for message text (if R3 was 0)
else Buffer pointed at by R3 holds message text R4 holds number of bytes written to buffer |
This method is used to read the help message which will be returned when a Help Request message is received for this Window object.
extern _kernel_oserror *window_get_help_message ( unsigned int flags,
ObjectId window,
char *buffer,
int buff_len,
int *nbytes
);
| 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 |
| R1-R9 | preserved |
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.
extern _kernel_oserror *window_add_keyboard_shortcuts ( unsigned int flags,
ObjectId window,
int no_shortcuts,
KeyboardShortcut *shortcuts
);
| 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) |
| R1-R9 | preserved |
This method removes a number of keyboard short-cuts which have been associated with this Window using the Window_AddKeyboardShortcuts method.
extern _kernel_oserror *window_remove_keyboard_shortcuts ( unsigned int flags,
ObjectId window,
int no_remove,
KeyboardShortcut *shortcuts
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 11 |
| R3 | = | pointer to new text for title bar |
| R1-R9 | preserved |
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.
extern _kernel_oserror *window_set_title ( unsigned int flags,
ObjectId window,
char *title
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 12 |
| R3 | = | pointer to buffer to hold title text (or 0) |
| R4 | = | size of buffer |
| 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 |
This method returns the string currently used in a Window's title bar.
extern _kernel_oserror *window_get_title ( unsigned int flags,
ObjectId window,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 13 |
| R3 | = | component id |
| R1-R9 | preserved |
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.
extern _kernel_oserror *window_set_default_focus ( unsigned int flags,
ObjectId window,
ComponentId focus
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 14 |
| R0 | = | component id |
| R1-R9 | preserved |
This method returns the default focus component of a window.
extern _kernel_oserror *window_get_default_focus ( unsigned int flags,
ObjectId window,
ComponentId *focus
);
| 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 | ||
| R1-R9 | preserved |
This method changes the extent of the underlying Wimp window.
extern _kernel_oserror *window_set_extent ( unsigned int flags,
ObjectId window,
BBox *extent
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 16 |
| R3 | = | pointer to four word block to hold extent |
| 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 | |
This method returns the extent of the underlying Wimp window.
extern _kernel_oserror *window_get_extent ( unsigned int flags,
ObjectId window,
BBox *extent
);
| 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 | ||
| R1-R9 | preserved |
This method forces a redraw on the area of the window given by the work area coordinates pointed to by R3.
extern _kernel_oserror *window_force_redraw ( unsigned int flags,
ObjectId window,
BBox *redraw_box
);
| 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 | |
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.
extern _kernel_oserror *window_set_tool_bars ( unsigned int flags,
ObjectId window,
ObjectId ibl,
ObjectId itl,
ObjectId ebl,
ObjectId etl
);
| 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 | ||
| 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 |
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.
extern _kernel_oserror *window_get_tool_bars ( unsigned int flags,
ObjectId window,
ObjectId *ibl,
ObjectId *itl,
ObjectId *ebl,
ObjectId *etl
);
| R0 | = | flags |
| 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 | |
This SWI is analogous to Wimp_GetPointerInfo, but returns Object ids and Component ids if the pointer is over a toolbox window.
extern _kernel_oserror *window_get_pointer_info ( unsigned int flags,
int *x_pos,
int *y_pos,
int *buttons,
ObjectId *window,
ComponentId *component
);
| R0 | = | flags |
| R1 | = | Wimp window handle |
| R2 | = | icon handle |
| R0 | = | toolbox object handle for window |
| R1 | = | component id |
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.
extern _kernel_oserror *window_wimp_to_toolbox ( unsigned int flags,
int window_handle,
int icon_handle,
ObjectId *object,
ComponentId *component
);
| R0 | = | flags |
| R1 | = | pointer window template |
| R2 | = | component id to match |
| R0 | = | pointer to Gadget |
| R1 | = | size of gadget |
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.
extern _kernel_oserror *window_extract_gadget_info ( unsigned int flags,
ObjectTemplateHeader *templ,
ComponentId gadget,
void **desc,
int *size
);
| + 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 |
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.
typedef struct
{
ToolboxEventHeader hdr;
int show_type;
union
{
TopLeft top_left;
WindowShowObjectBlock full_spec;
} info;
} WindowAboutToBeShownEvent;
| + 8 | 0x82890 |
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.
typedef struct
{
ToolboxEventHeader hdr;
} WindowHasBeenHiddenEvent;
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) |
| Field | Size in bytes | Type |
|---|---|---|
| flags | 4 | word |
| wimp_key_code | 4 | word |
| key_event | 4 | word |
| key_show | 4 | StringReference |
| 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 |
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:
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.
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.
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:
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.
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.
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.
Toolbar object attributes are described in the window attributes section on Attributes.
Note that a toolbar should not have toolbars itself.
Toolbar objects are created and deleted using the standard Toolbox_CreateObject and Toolbox_DeleteObject methods.
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.
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 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:
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 |
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.
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.
| R0 | = | 0 |
| R1 | = | Window object id |
| R2 | = | 64 |
| R3 | = | Gadget component id |
| R0 | = | flags settings for this gadget |
This method returns the flags word for the given gadget.
extern _kernel_oserror *gadget_get_flags ( unsigned int flags,
ObjectId window,
ComponentId gadget,
unsigned int *flags_settings
);
| R1 | = | Window object id |
| R2 | = | 65 |
| R3 | = | Gadget component id |
| R4 | = | new flags settings |
| R1-R9 | preserved |
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.
extern _kernel_oserror *gadget_set_flags ( unsigned int flags,
ObjectId window,
ComponentId gadget,
unsigned int new_flags_settings
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 66 |
| R3 | = | Gadget component id |
| R4 | = | pointer to help message text |
| R1-R9 | preserved |
This method sets the help message which will be returned, when a help request is received for this gadget.
extern _kernel_oserror *gadget_set_help_message ( unsigned int flags,
ObjectId window,
ComponentId gadget,
char *message_text
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 67 |
| R3 | = | Gadget component id |
| R4 | = | pointer to buffer |
| R5 | = | size of buffer |
| 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 |
This method returns the help message which will be returned, when a help request is received for this gadget.
extern _kernel_oserror *gadget_get_help_message ( unsigned int flags,
ObjectId window,
ComponentId gadget,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 68 |
| R3 | = | Gadget component id |
| R4 | = | pointer to buffer |
| R5 | = | size of buffer |
| 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 |
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.
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.
| R0 | = | flags |
| R1-R9 | preserved |
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.
extern _kernel_oserror *gadget_set_focus ( unsigned int flags,
ObjectId window,
ComponentId component
);
| R0 | = | 0 |
| R1 | = | Window object id |
| R2 | = | 70 |
| R3 | = | Gadget component id |
| R0 | = | type of this Gadget |
Usage:
This method returns the type of the given gadget.
extern _kernel_oserror *gadget_get_type ( unsigned int flags,
ObjectId window,
ComponentId gadget,
int *type
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 71 |
| R3 | = | Gadget component id |
| R4 | = | pointer to new bounding box |
| R1-R9 | preserved |
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.
extern _kernel_oserror *gadget_move_gadget ( unsigned int flags,
ObjectId window,
ComponentId gadget,
BBox *new_bbox
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 72 |
| R3 | = | Gadget component id |
| R4 | = | pointer to 4 word buffer |
| R1-R9 | preserved |
This method copies the bounding box of a gadget into the supplied buffer.
extern _kernel_oserror *gadget_get_bbox ( unsigned int flags,
ObjectId window,
ComponentId gadget,
BBox *box
);
| 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. |
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):
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) |
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 128 |
| R3 | = | Gadget component id |
| R4 | = | pointer to text to appear in button |
| R1-R9 | preserved |
This method sets the text which will be displayed in this action button.
extern _kernel_oserror *actionbutton_set_text ( unsigned int flags,
ObjectId window,
ComponentId action_button,
char *text
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 129 |
| R3 | = | Gadget component id |
| R4 | = | pointer to buffer |
| R5 | = | size of buffer |
| 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 |
This method returns the text which is currently displayed in this action button.
extern _kernel_oserror *actionbutton_get_text ( unsigned int flags,
ObjectId window,
ComponentId action_button,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 130 |
| R3 | = | Gadget component id |
| R4 | = | Toolbox event code |
| R1-R9 | preserved |
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.
extern _kernel_oserror *actionbutton_set_event ( unsigned int flags,
ObjectId window,
ComponentId action_button,
int event
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 131 |
| R3 | = | Gadget component id |
R0 holds Toolbox event code
This method returns the Toolbox event code which will be raised when this action button is clicked.
extern _kernel_oserror *actionbutton_get_event ( unsigned int flags,
ObjectId window,
ComponentId action_button,
int *event
);
| 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 | ||||
| R1-R9 | preserved |
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.
extern _kernel_oserror *actionbutton_set_click_show ( unsigned int flags,
ObjectId window,
ComponentId action_button,
ObjectId object,
int show_flags
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 133 |
| R3 | = | Gadget component id |
| R0 | = | id of object to be shown |
| R1 | = | show flags |
This method returns the object id of the object which will be shown when the user 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.
extern _kernel_oserror *actionbutton_get_click_show ( unsigned int flags,
ObjectId window,
ComponentId action_button,
ObjectId *object,
int * show_flags
);
| + 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) | ||
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.
typedef struct
{
ToolboxEventHeader hdr;
} ActionButtonSelectedEvent;
| Field | Size in bytes | Type |
|---|---|---|
| text | 4 | MsgReference |
| max_text_len | 4 | word |
| click_show | 4 | StringReference |
| event | 4 | word |
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:
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
|
| + 8 | 0x8288c |
| + 16 | (0 DOWN_ 1 up)
|
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').
typedef struct
{
ToolboxEventHeader hdr;
int direction;
} AdjusterClickedEvent;
There are no extra fields than those in the gadget header.
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:
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 |
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 960 |
| R3 | = | Gadget component id |
| R0 | = | icon flags |
| R1-R9 | preserved | |
This method returns the flags of the given button gadget. The bits have the same meaning as those of a Wimp Icon.
extern _kernel_oserror *button_get_flags ( unsigned int flags,
ObjectId window,
ComponentId button,
int *icon_flags
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 961 |
| R3 | = | Gadget component id |
| R4 | = | clear word |
| R5 | = | EOR word |
| R1-R9 | preserved |
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.
extern _kernel_oserror *button_set_flags ( unsigned int flags,
ObjectId window,
ComponentId button,
int clear_word,
int EOR_word
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 962 |
| R3 | = | Gadget component id |
| R4 | = | new value |
| R1-R9 | preserved |
This method sets the value (i.e. text or sprite name) of a Button.
extern _kernel_oserror *button_set_value ( unsigned int flags,
ObjectId window,
ComponentId button,
char *value
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 963 |
| R3 | = | Gadget component id |
| R4 | = | pointer to buffer to hold string |
| R5 | = | size of buffer |
| 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 |
This method returns the value of a Button.
extern _kernel_oserror *button_get_value ( unsigned int flags,
ObjectId window,
ComponentId button,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 964 |
| R3 | = | Gadget component id |
| R4 | = | new value |
| R1-R9 | preserved |
This method sets the validation string (e.g. sprite name) of a Button.
extern _kernel_oserror *button_set_validation ( unsigned int flags,
ObjectId window,
ComponentId button,
char *value
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 965 |
| R3 | = | Gadget component id |
| R4 | = | pointer to buffer to hold string |
| R5 | = | size of buffer |
| 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 |
This method returns the validation string of a Button.
extern _kernel_oserror *button_get_validation ( unsigned int flags,
ObjectId window,
ComponentId button,
char *buffer,
int buff_size,
int *nbytes
);
| 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 |
| R1-R9 | preserved |
This method makes the Button use an anti-aliased font. If the font name is NULL, then the field will use system font.
extern _kernel_oserror *button_set_font ( unsigned int flags,
ObjectId window,
ComponentId button,
char *font_name,
int width,
int height
);
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.
A display field gadget is used to display information in a 'read-only' manner:
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
| ||
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 448 |
| R3 | = | Gadget component id |
| R4 | = | pointer to text string to use |
| R1-R9 | preserved |
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.
extern _kernel_oserror *displayfield_set_value ( unsigned int flags,
ObjectId window,
ComponentId display_field,
char *text
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 449 |
| R3 | = | Gadget component id |
| R4 | = | pointer to buffer |
| R5 | = | size of buffer |
| 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 |
This method returns the text string shown in a display field.
extern _kernel_oserror *displayfield_get_value ( unsigned int flags,
ObjectId window,
ComponentId display_field,
char *buffer,
int buff_size,
int *nbytes
);
| 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 |
| R1-R9 | preserved |
This method makes the display field use an anti-aliased font. If the font name is NULL, then the field will use system font.
extern _kernel_oserror *displayfield_set_font ( unsigned int flags,
ObjectId window,
ComponentId display_field,
char *font_name,
int width,
int height
);
| Field | Size in bytes | Type |
|---|---|---|
| text | 4 | MsgReference |
| max_text_len | 4 | word |
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) | |
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 640 |
| R3 | = | Gadget component id |
| R4 | = | pointer to sprite name to use |
| R1-R9 | preserved |
This method sets the name of the sprite which will be used for this draggable.
extern _kernel_oserror *draggable_set_sprite ( unsigned int flags,
ObjectId window,
ComponentId draggable,
char *sprite_name
);
| 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 |
| 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 |
This method returns the name of the sprite which is currently being used for this draggable.
extern _kernel_oserror *draggable_get_sprite ( unsigned int flags,
ObjectId window,
ComponentId draggable,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 642 |
| R3 | = | Gadget component id |
| R4 | = | pointer to text to use |
| R1-R9 | preserved |
This method sets the text which will be displayed in this draggable.
extern _kernel_oserror *draggable_set_text ( unsigned int flags,
ObjectId window,
ComponentId draggable,
char *text
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 643 |
| R3 | = | Gadget component id |
| R4 | = | pointer to buffer |
| R5 | = | size of buffer |
| 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 |
This method returns the text which is currently being used for this draggable.
extern _kernel_oserror *draggable_get_text ( unsigned int flags,
ObjectId window,
ComponentId draggable,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 644 |
| R3 | = | Gadget component id |
| R4 | = | state (0 DESELECTED_ 1 selected).
|
| R1-R9 | preserved |
This method sets the Draggable's state to either selected or deselected.
extern _kernel_oserror *draggable_set_state ( unsigned int flags,
ObjectId window,
ComponentId draggable,
int state
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 645 |
| R3 | = | Gadget component id |
| R0 | = | state |
This method returns the Draggables' state (0 DESELECTED_ 1 selected).
extern _kernel_oserror *draggable_get_state ( unsigned int flags,
ObjectId window,
ComponentId draggable,
int *state
);
| + 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 | ||
This Toolbox event is raised when the user starts a drag of a draggable gadget.
typedef struct
{
ToolboxEventHeader hdr;
} DraggableDragStartedEvent;
| + 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 | |||
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.
typedef struct
{
ToolboxEventHeader hdr;
int window_handle;
int icon_handle;
int x;
int y;
} DraggableDragEndedEvent;
| Field | Size in bytes | Type |
|---|---|---|
| text | 4 | MsgReference |
| max_text_len | 4 | word |
| sprite | 4 | StringReference |
| max_sprite_len | 4 | word |
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.
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
| ||
| Field | Size in bytes | Type |
|---|---|---|
| label | 4 | MsgReference |
A labelled box gadget is used for collecting together a set of related items:
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. |
| Field | Size in bytes | Type |
|---|---|---|
| label | 4 | MsgReference or StringReference |
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:
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.
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 832 |
| R3 | = | Gadget component id |
| R4 | = | new value |
| R1-R9 | preserved |
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.
extern _kernel_oserror *numberrange_set_value ( unsigned int flags,
ObjectId window,
ComponentId number_range,
int value
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 833 |
| R3 | = | Gadget component id |
R0 holds current value
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).
extern _kernel_oserror *numberrange_get_value ( unsigned int flags,
ObjectId window,
ComponentId number_range,
int *value
);
| 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 | ||
| R1-R9 | preserved |
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.
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
);
| 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 | ||
| R0 | = | lower bound |
| R1 | = | upper bound |
| R2 | = | step size |
| R3 | = | precision |
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.
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
);
| 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 | ||
| R0 | = | numeric id |
| R1 | = | left adjuster id |
| R2 | = | right adjuster id |
| R3 | = | slider id |
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.
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
);
| + 8 | 0x8288d |
| + 16 | new value shown in display area |
This Toolbox event is raised when the value of the Number Range has changed.
typedef struct
{
ToolboxEventHeader hdr;
int new_value;
} NumberRangeValueChangedEvent;
| 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 |
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:
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. |
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 192 |
| R3 | = | Gadget component id |
| R4 | = | pointer to string giving label to use |
| R1-R9 | preserved |
This method sets the label which will be used for this option button.
extern _kernel_oserror *optionbutton_set_label ( unsigned int flags,
ObjectId window,
ComponentId option_button,
char *label
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 193 |
| R3 | = | Gadget component id |
| R4 | = | pointer to buffer |
| R5 | = | size of buffer |
| 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 |
This method returns the label which is currently displayed for this option button.
extern _kernel_oserror *optionbutton_get_label ( unsigned int flags,
ObjectId window,
ComponentId option_button,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 194 |
| R3 | = | Gadget component id |
| R4 | = | Toolbox event code |
| R1-R9 | preserved |
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.
extern _kernel_oserror *optionbutton_set_event ( unsigned int flags,
ObjectId window,
ComponentId option_button,
int event
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 195 |
| R3 | = | Gadget component id |
R0 holds Toolbox event code.
This method returns the Toolbox event which will be raised when this option button's state changes.
extern _kernel_oserror *optionbutton_get_event ( unsigned int flags,
ObjectId window,
ComponentId option_button,
int *event
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 196 |
| R3 | = | Gadget component id |
| R4 | = | state (0 OFF_ 1 on)
|
| R1-R9 | preserved |
This method sets the option button's state to on or off.
extern _kernel_oserror *optionbutton_set_state ( unsigned int flags,
ObjectId window,
ComponentId option_button,
int state
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 197 |
| R3 | = | Gadget component id |
| R0 | = | state |
This method returns the option button's state (0 OFF_ 1 on).
extern _kernel_oserror *optionbutton_get_state ( unsigned int flags,
ObjectId window,
ComponentId option_button,
int *state
);
| + 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)
| ||
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.
typedef struct
{
ToolboxEventHeader hdr;
int new_state;
} OptionButtonStateChangedEvent;
| Field | Size in bytes | Type |
|---|---|---|
| flags | 4 | word |
| label | 4 | MsgReference |
| max_label_len | 4 | word |
| event | 4 | word |
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:
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. |
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 704 |
| R3 | = | Gadget component id |
| R4 | = | object id of Menu to use |
| R1-R9 | preserved |
This method sets the Menu object which will be shown when the pop-up button is clicked on.
extern _kernel_oserror *popup_set_menu ( unsigned int flags,
ObjectId window,
ComponentId popup,
ObjectId menu
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 705 |
| R3 | = | Gadget component id |
| R0 | = | Menu object id |
This method returns the object id of the Menu which will be shown when the pop-up button is clicked on.
extern _kernel_oserror *popup_get_menu ( unsigned int flags,
ObjectId window,
ComponentId popup,
ObjectId *menu
);
| + 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) |
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.
typedef struct
{
ToolboxEventHeader hdr;
ObjectId menu_id;
}PopUpAboutToBeShownEvent;
| Field | Size in bytes | Type |
|---|---|---|
| menu | 4 | StringReference |
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.
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 |
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 384 |
| R3 | = | Gadget component id |
| R4 | = | pointer to string giving label to use |
| R1-R9 | preserved |
This method sets the label which will be used for this radio button.
extern _kernel_oserror *radiobutton_set_label ( unsigned int flags,
ObjectId window,
ComponentId radio_button,
char *label
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 385 |
| R3 | = | Gadget component id |
| R4 | = | pointer to buffer |
| R5 | = | size of buffer |
| 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 |
This method returns the label which is currently displayed for this radio button.
extern _kernel_oserror *radiobutton_get_label ( unsigned int flags,
ObjectId window,
ComponentId radio_button,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 386 |
| R3 | = | Gadget component id |
| R4 | = | Toolbox event code |
| R1-R9 | preserved |
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.
extern _kernel_oserror *radiobutton_set_event ( unsigned int flags,
ObjectId window,
ComponentId radio_button,
int event
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 387 |
| R3 | = | Gadget component id |
R0 holds Toolbox event code
This method returns the Toolbox event which will be raised when this radio button's state changes.
extern _kernel_oserror *radiobutton_get_event ( unsigned int flags,
ObjectId window,
ComponentId radio_button,
int *event
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 388 |
| R3 | = | Gadget component id |
| R4 | = | state (0 OFF_ 1 On)
|
| R1-R9 | preserved |
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.
extern _kernel_oserror *radiobutton_set_state ( unsigned int flags,
ObjectId window,
ComponentId radio_button,
int state
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 389 |
| R3 | = | Gadget component id |
| R0 | = | state (0 OFF_ 1 On)
|
| R1 | = | component id of radio button which is On in the group |
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).
extern _kernel_oserror *radiobutton_get_state ( unsigned int flags,
ObjectId window,
ComponentId radio_button,
int *state,
Component Id *selected
);
| + 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 | |||
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.
typedef struct
{
ToolboxEventHeader hdr;
int state;
ComponentId old_on_button;
} RadioButtonStateChangedEvent;
| Field | Size in bytes | Type |
|---|---|---|
| group_number | 4 | word |
| label | 4 | MsgReference |
| max_label_len | 4 | word |
| event | 4 | word |
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:
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 |
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 576 |
| R3 | = | Gadget component id |
| R4 | = | integer value |
| R1-R9 | preserved |
This method sets the value of a slider. The slider's bar is changed accordingly.
extern _kernel_oserror *slider_set_value ( unsigned int flags,
ObjectId window,
ComponentId slider,
int value
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 577 |
| R3 | = | Gadget component id |
| R0 | = | slider's value |
This method returns the value of a slider.
extern _kernel_oserror *slider_get_value ( unsigned int flags,
ObjectId window,
ComponentId slider,
int *value
);
| 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 | ||
| R1-R9 | preserved |
This method sets the lower bound, upper bound and step size of a slider gadget.
extern _kernel_oserror *slider_set_bound ( unsigned int flags,
ObjectId window,
ComponentId slider,
int upper_bound,
int lower_bound,
int step_size
);
| 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 | ||
| R0 | = | upper bound |
| R1 | = | lower bound |
| R2 | = | step size |
This method returns the lower bound, upper bound and step size of a slider gadget.
extern _kernel_oserror *slider_get_bound ( unsigned int flags,
ObjectId window,
ComponentId slider,
int *upper_bound,
int *lower_bound,
int *step_size
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 580 |
| R3 | = | Gadget component id |
| R4 | = | Desktop colour value for bar |
| R5 | = | Desktop colour value for background |
| R1-R9 | preserved |
This method sets the Desktop colour used in a slider.
extern _kernel_oserror *slider_set_colour ( unsigned int flags,
ObjectId window,
ComponentId slider,
int bar_colour,
int back_colour
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 581 |
| R3 | = | Gadget component id |
| R0 | = | Desktop colour value for bar |
| R1 | = | Desktop colour value for background |
This method returns the Desktop colour used in a slider.
extern _kernel_oserror *slider_get_colour ( unsigned int flags,
ObjectId window,
ComponentId slider,
int *bar_colour,
int *back_colour
);
| + 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. | ||
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).
typedef struct
{
ToolboxEventHeader hdr;
int new_value;
} SliderValueChangedEvent;
| Field | Size in bytes | Type |
|---|---|---|
| lower_bound | 4 | word |
| upper_bound | 4 | word |
| step_size | 4 | word |
| initial_value | 4 | word |
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
|
| 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 |
| R1-R9 | preserved |
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.
extern _kernel_oserror *stringset_set_available ( unsigned int flags,
ObjectId window,
ComponentId string_set,
char *strings
);
| 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 | |||
| R1-R9 | preserved |
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.
extern _kernel_oserror *stringset_set_selected ( unsigned int flags,
ObjectId window,
ComponentId string_set,
char *string_to_select
);
| 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 | |||
| 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 |
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).
extern _kernel_oserror *stringset_get_selected ( unsigned int flags,
ObjectId window,
ComponentId string_set,
...
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 900 |
| R3 | = | Gadget component id |
| R4 | = | pointer to string giving new set of allowable characters |
| R1-R9 | preserved |
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').
extern _kernel_oserror *stringset_set_allowable ( unsigned int flags,
ObjectId window,
ComponentId string_set,
char *allowable
);
| 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 | ||
| R0 | = | alphanumeric id |
| R1 | = | popup id |
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.
extern _kernel_oserror *stringset_get_components ( unsigned int flags,
ObjectId window,
ComponentId string_set,
ComponentId *alphanumeric_field,
ComponentId *popup_menu
);
| + 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) |
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.
typedef struct
{
ToolboxEventHeader hdr;
char string[sizeof(ToolboxEvent)-sizeof(ToolboxEventHeader)];
} StringSetValueChangedEvent;
| + 8 | 0x8288f |
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.
typedef struct
{
ToolboxEventHeader hdr;
} StringSetAboutToBeShownEvent;
| 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 |
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:
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) |
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 512 |
| R3 | = | Gadget component id |
| R4 | = | pointer to text string to use |
| R1-R9 | preserved |
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.
extern _kernel_oserror *writablefield_set_value ( unsigned int flags,
ObjectId window,
ComponentId writable,
char *text
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 513 |
| R3 | = | Gadget component id |
| R4 | = | pointer to buffer |
| R5 | = | size of buffer |
| 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 |
This method returns the text string shown in a writable field.
extern _kernel_oserror *writablefield_get_value ( unsigned int flags,
ObjectId window,
ComponentId writable,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Window object id |
| R2 | = | 514 |
| R3 | = | Gadget component id |
| R4 | = | pointer to string giving new set of allowable characters |
| R1-R9 | preserved |
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.
extern _kernel_oserror *writablefield_set_allowable ( unsigned int flags,
ObjectId window,
ComponentId writable,
char *allowed
);
| 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 |
| R1-R9 | preserved |
This method makes the writable field use an anti-aliased font. If the font name is NULL, then the field will use system font.
extern _kernel_oserror *writablefield_set_font ( unsigned int flags,
ObjectId window,
ComponentId writable_field,
char *font_name,
int width,
int height
);
| + 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 |
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.
typedef struct
{
ToolboxEventHeader hdr;
char string[sizeof(ToolboxEvent)-sizeof(ToolboxEventHeader)];
} WritableFieldValueChangedEvent;
| 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 |