Introduction and Overview
Gadgets are registered using the SWI SWI Window_RegisterExternal and removed using the SWI SWI Window_DeregisterExternal. These SWIs have been extended in order to allow for greater flexibility in the future.
Technical Details
Type details
The type details can take one of two forms, depending on whether R0 bit 0 is set or clear. The basic form has bit 0 clear and, in C, has the following structure :
typedef struct {
int type;
unsigned long validflags;
FeatureMask features;
} GadgetExtensionRecord;
The extended form adds an extra FeatureMask word, making the record 4 words long, rather than 3 :
typedef struct {
int type;
unsigned long validflags;
FeatureMask features;
FeatureMask2 features2;
} GadgetExtensionRecord2;
The FeatureMask (and FeatureMask2) flags word takes the following form in C :
typedef struct {
int add:2,
remove:2,
postadd:2,
method:2,
reserved:2,
mclick:2,
reserved2:4,
plot:2,
setfocus:2,
move:2,
fade:2,
windowshow:2,
mscroll:2,
lostfocus:2,
redraw:2;
} FeatureMask;
typedef struct {
int timer:2,
unused2:2,
unused4:2,
unused6:2,
unused8:2,
unused10:2,
unused12:2,
unused14:2,
unused16:2,
unused18:2,
unused20:2,
unused22:2,
unused24:2,
unused26:2,
unused28:2,
unused30:2;
} FeatureMask2;
Each of these bits can take a value to indicate what type of handler is present in the gadget :
| Value | Meaning |
|---|---|
| 0 | 'No handler present'. The operation will be ignored |
| 1 | 'Default handler present'. The Window module will perform whatever default processing the operation expects, for example a 'move' operation will apply simple position changes to the registered icons for the gadget. |
| 2 | 'Private handler present'. The Window module will call the gadget entry point to request the operation be performed. |
| 3 | Reserved, must not be used |
See the Gadget handlers document for details of the handlers and their API.
A number of functions exist to be used to register and deregister gadgets :
extern _kernel_oserror *register_gadget_types(unsigned int flags,
GadgetExtensionRecord *rec,
int SWIno);
extern _kernel_oserror *deregister_gadget_type(unsigned int flags,
int type,
int SWIno);
extern _kernel_oserror *register_gadget_type(unsigned int flags,
int type,
unsigned int valid,
unsigned int mask,
int SWIno);
extern _kernel_oserror *register_gadget_type2(unsigned int flags,
int type,
unsigned int valid,
unsigned int mask,
unsigned int mask2,
int SWIno);
SWI Calls
| R0 | = | Flags:
| |||||||||
| R1 | = | Pointer to list of type details (see above) | |||||||||
| R2 | = | Gadget SWI number | |||||||||
| R0 - R2 | = | Preserved |
This SWI registers the new Gadget type(s) with the Window module. The given SWI number will be called whenever the Window module encounters the given Gadget type and the features mask indicates that there is a handler available.
| R0 | = | Flags, must be 0 |
| R1 | = | Type of Gadget to deregister |
| R2 | = | SWI that handled it |
| R0 - R2 | = | Preserved |
This SWI deregisters a Gadget type. Note that if a module dies without deregistering the Window module will automatically deregister it on the next SWI call. However, this behaviour should not be relied upon - it is there to prevent unexpected behaviour with the rest of the system.