|
Window_SupportExternal
Overview
The Window_SupportExternal SWI is used to provide additional functions to extension gadgets. These operations are listed below. Unless otherwise stated, the operations are present in all distributed versions of the Window module.
Window_SupportExternal (SWI &82887)
On entry:
R0 = flags (Should be zero unless otherwise stated)
R1 = Reason code :
0 = Create icon
1 = Reserved
2 = Create object
3 = Create gadget
4 = Allocate memory
5 = Free memory
6 = Extend allocated memory
7 = Simple move gadget
8 = Remove icons
9 = Add icons
10 = Call after
11 = Call every
Others = Reserved
R2 = Code specific
On exit:
Depends on reason code
This SWI provides various functions that are of use to extension gadget modules.
Create icon (0)
On entry:
R1 = 0 (Create icon)
R2 = pointer to wimp icon definition
On exit:
R0 = Icon handle or -1 if failed to create
This call creates a wimp icon from the given definition except when the Window module is in 'plotting' mode. A C equivalent is available:
int glib_create_icon(WimpCreateIconBlock *i);
Create object (2)
On entry:
R0 = flags
R1 = 2 (Create object)
R2 = pointer to depends on flag bit 0:
clear R2 = pointer to template name
set R2 = pointer to in memory object definition
On exit:
R0 = Object id or zero if failed to create
This call creates a toolbox object and returns its Object id. The reason for using this as opposed to toolbox_create_object (SWI Toolbox_CreateObject) is that the Window module first checks for plotting rather than creation mode. If the Gadget provides a plot handler, then it may safely use Toolbox_CreateObject SWI in its add handler.
Create gadget (3)
On entry:
R1 = 3 (Create gadget)
R2 = Object id (must be current Object id)
R3 = pointer to gadget definition
R4 = tag (0x800 to 0xfff)
On exit:
R0 = Component id or 0 if failed to create
This call, used for implementing composite gadgets, creates a gadget from the given template definition. The Window module generates a unique Component id for the gadget derived from the tag - It will be of the form 0x?????ttt. The use of a tag allows improved reaction to events on composite gadgets in that if a Composite Gadget creates all its Gadgets with tag 999, then its event routines can return immediately if the Component id's lower bits do not equal 999. Tags do not require registration, but it is worth advising 3QD Developments Ltd so that, where possible, clashes can be avoided. In order to receive Toolbox events a module must register an interest in them - this is described in application note 280. Note that the failure condition returns 0 rather than -1 as with other gadget calls.
A C equivalent is available:
int create_gadget(int o,int *i,int f);
Allocate memory (4)
On entry:
R1 = 4 (Allocate memory)
R2 = amount of memory to allocate in bytes
On exit:
R0 = pointer to memory or NULL
This call allocates memory from the Window module's allocator using either the RMA or the Toolbox dynamic area.
A C equivalent is available:
void *mem_allocate(int amount);
Free memory (5)
On entry:
R1 = 5 (Free free)
R2 = pointer to memory to free
On exit:
All registers preserved
This call frees memory that was previously allocated by the Window modules allocator, such as with the Window_SupportExternal 4.
A C equivalent is available:
void mem_free(void *tag);
Extend memory (6)
On entry:
R1 = 6 (Extend memory)
R2 = pointer to memory to extend
R3 = change in size
On exit:
R0 = pointer to memory of NULL if extend failed
This call reallocates memory that was previously allocated by the Window modules allocator, such as with the Window_SupportExternal 4. The change may be positive or negative to grow or shrink the block accordingly. The pointer to the block may have to change and this is returned in R0. A failure will preserve the original data. Note that this is not an equivalent call to C's 'realloc' function.
A C equivalent is available:
void mem_extend(void *tag, int change);
Simple move gadget (7)
On entry:
R1 = 7 (Simple move gadget)
R2 = Object id of parent object
R3 = Component id of gadget to move
R4 = pointer to new bounding box
On exit:
All registers preserved
This call moves all the icons associated with a gadget to the position specified by the new bounding box in the same manner as the internal gadgets. This call is only present in Window 1.98 and later. Versions of GLib before 0.05 do not use this operation and instead use a method of registering a temporary gadget, performing the move and then deregistering the gadget. The earlier form is strongly discouraged due to its adverse effects on certain versions of the Window module. If you use glib 0.05 or later you should ensure Window 1.98.
A C equivalent is available:
void glib_move_gadget(int type,Object id obj,Component id id,BBox *box);
The 'type' parameter is ignored in GLib 0.05 and later.
Remove icons (8)
On entry:
R1 = 8 (Remove icons)
R2 = Object id of parent object
R3 = Component id of gadget to remove
R4 = pointer to a list of icon handles, terminated by -1
On exit:
All registers preserved
This call allows a gadget to inform the Window module that the it no longer uses the icon handles given within the list. This allows gadgets to change the number of icons which they use dynamically during their life. This operation is present in Window 1.99 and later. A C equivalent is available:
void glib_remove_icons(Object id obj, Component id id, int *icons);
Add icons (9)
On entry:
R1 = 9 (Add icons)
R2 = Object id of parent object
R3 = Component id of gadget to add
R4 = pointer to a list of icon handles, terminated by -1
On exit:
All registers preserved
This call allows gadgets to inform the Window module that the gadget has created the icon handles given within the list. This allows gadgets to change the number of icons which they use dynamically during their life. This operation is present in Window 1.99 and later.
A C equivalent is available:
void glib_add_icons(Object id obj, Component id id, int *icons);
Call after (10)
On entry:
R1 = 10 (Call after)
R2 = Object id of parent object
R3 = Component id of gadget to register a timer event on
R4 = delay in centiseconds, or 0 to remove the call after
On exit:
All registers preserved
This call is used to cause the Window module to call the gadget at its entry point after a number of centiseconds have passed (on a Wimp poll return, so the system is known to be unthreaded). Only a single CallAfter (or CallEvery) may be associated with a gadget. The timer will only begin its operation when the parent window object is shown. It will be removed when the window is hidden. This call is present in versions of Window after 2.03.
A C equivalent is available:
void glib_gadget_timer_after(Object id object, Component id component,
int delay);
A similar function can be used to explicitly remove such a timer :
void glib_gadget_timer_remove(Object id object, Component id component);
Call every (11)
On entry:
R1 = 11 (Call every)
R2 = Object id of parent object
R3 = Component id of gadget to register a timer event on
R4 = delay in centiseconds, or 0 to remove the call every
On exit:
All registers preserved
This call is identical to the CallAfter call except that the callback will recur after each trigger.
A C equivalent is available:
void glib_gadget_timer_every(Object id object, Component id component,
int delay);
|
![[Select]](../imgs/seldoc.png)
