Gadget handlers

On receiving this reason code an extension module should create the new gadget from the given data and return its icon list and private handle. The template will already have been checked for valid flags. Any attached objects (like the Click show objects attached to action buttons) should be created using the GLib calls.

On receiving this reason code an extension module should remove the gadget. If the recurse bit is set then any attached objects such as Windows or Menus should not be removed. This is in common with the flag bit in the SWI Toolbox_DeleteObject.

On receiving this reason code an extension module should fade or unfade the gadget, according to the value in R4. A Gadget will have been faded by the client making a call to the Gadget_SetFlags method.

The window module raises this reason code when a task uses the Toolbox_ObjectMiscOp SWI on a Gadget which is provided by an extension module. R4 points to a register bank (in C terms this is the _kernel_swi_regs type) which contains the values that the client passed to the SWI. If any information is to be returned to the client then this bank should be updated. i.e. to return a value in R0 do not set R0 to the value but update the contents of the location pointed to by R4+0. Note that the generic Gadget methods such as Gadget_SetFlags do not result in a call to GADGET_METHOD.

The window module raises this reason code when an icon belonging to the Gadget is clicked on. The event block in R4 is just like the one returned by Wimp_Poll when an icon is clicked on. An extension module would typically use this to update the state of the Gadget or return a 'high-level' Toolbox Event. By setting R1 to be non-zero the Window module will update the task's ID block so that when the wimp mouse click event is delivered it is marked as belonging to this Gadget. Although it is unlikely that the task will be interested in the underlying event it should still be claimed. Possible exceptions to this rule are when the menu mouse button is used - in this case, not claiming the click (R1 = 0) passes the mouse click on which would allow the Window's menu to be viewed. This is not true for a popup menu type Gadget though.

It is also possible to claim the event entirely so that the task will not see the mouse click. This is achieved by setting R1 to -1 on exit, but this should be avoided as this does not fit the Toolbox model and so should only be done in specialist cases.

The window module raises this reason code when !ResEd is plotting Gadgets. The extension module should use Wimp_PlotIcon or Window_PlotGadget (for composite Gadgets) to display the Gadget which is defined by the template.

This call will be made when the Window module wishes to set the focus to a Gadget. The direction signals whether to set the focus to the before or after Gadget in the event of this Gadget being faded. Care should be taken when 'passing on' the focus as an infinite loop will be entered if all members of the list are faded. Gadgets which are composite and consist of a writable Gadget do not need to worry about this and should just set focus to their writable without checking their faded status, assuming that the before and after fields of the underlying writable have been set.

This call is made when the Gadget_Move method is applied to a Gadget. A composite gadget must supply a handler if it is going to be moved after creation as the default handler can only move the icons which belong directly to a Gadget. It is also of use if the Gadget supports resizing - the default mover will only move by an offset as it generally does not know how to handle any change in the size of the bounding box.

FIXME: The entry and exit conditions of this reason code are not documented.

This call is made to inform the gadget that its parent Window has been shown or has been hidden. Gadgets may wish to take action the first time they are shown or to stop an action once the window is hidden. A typical example of such a gadget might be a timer.

This call is made when the Window module receives a scroll event for an icon belonging to the gadget. In order for the WindowScroll module to generate such events the icons must have the correct validation string set. See the WindowScroll module document for more details.

This call is made when the Window module detects that a gadget has lost the focus, either due to a cursor movement or the focus being moved to another icon (even temporarily by a Menu). Gadgets may wish to take action based on having lost the focus, such as validating input.

This call is made when the Window module needs to redraw a region of the window covered by a gadget. Gadgets which have the 'redraw' Feature set to include a 'Private Handler' will be automatically registered with the RedrawManager module and this entry point will be called to redraw their content. The 'Gadget_AtBack' flag is used to control whether the redraw occurs before or after icon rendering. Because the redraw operation uses the RedrawManager, the order of such gadgets within the window will be arbitrary, but always before or after all other (non-Redraw) gadgets. The Redraw region will be bounded by the graphics window. See the Rendering into Windows document for more details.

This call is made when a Gadget's timer is triggered. The accuracy of gadget timers cannot be guaranteed. Gadget timers are started either on creation or when the window is shown. They are stopped when the window is hidden.