]>
User functions or accessories can perform such tasks as popping up a calculator, managing a hotlist, editing HTML files, adding remote control, and generally enhancing the user interface. They are started explicitly by the user, or automatically by the browser immediately on start-up. There is at most one instance of each user function.
User functions are, in principle, based on a subroutine model. They perform a function and then return. In the user interface this may correspond to a modal dialog. However, they may also open permanent windows and register event handlers for them, but some care is needed here.
User functions have a signature that includes:
Zero or more labels (for use in a menu, or on buttons).
Zero or more corresponding icons (which some browsers may display in preference to a button or menu entry).
A list of object files.
A suffix.
All user functions must define the following functions:
Bool initXXX(long id, char ***labels, char
*****icons_data, int *nrlabels)
Initializes private variables and returns labels and icons
for the functions that the applet performs. The labels can be
used by a browser to put into a menu, the icons can be used for
a tool bar. For each label, there are actually three icons, one
for normal display, one when the icon is clicked on, and one
when the icon is insensitive. The second and third one may be
NULL
.
The id
is the unique ID assigned by the browser
to this applet (there is only one instance). The applet must use
this ID if it ever calls W3Aevent
.
Here is an example of an actual function, for a Hotlist applet with two sub-functions, viz., `add current' and `view hotlist'. Note that the icons are passed as character data, not as Pixmaps:
EXPORT Bool initHotlist(long id, const char ***labels, const char *****icons_data, int *nrlabels) { #include "add.xpm" /* Include the XPM files */ #include "add1.xpm" #include "delete.xpm" #include "delete1.xpm" #include "hotlist.xpm" #include "open.xpm" #include "open1.xpm" static char *labs[] = { "Add current to hotlist", "Hotlist"}; static char **data[][3] = { {add, add1, NULL}, {hotlist, NULL, NULL}}; int *dummy; *labels = labs; *icons_data = data; *nrlabels = XtNumber(labs); new(dummy); return (long) dummy; }
A return of FALSE
indicates an error, in which case errno holds the error code.
All user accessories are initialized by the browser
immediately after the browser starts. Accessories may use this,
e.g., to install a callback (see W3Aregister
)
Bool doXXX(int code, int mid_x, int
mid_y)
The doXXX
function, but it will
never be called.
The return code is TRUE
for success, and
FALSE
for error.
void eventXXX(long sourceid, long
eventtype, void *params)
This function is called when an abstract event occurred in
the browser or another applet. source_id is the ID of
the applet in which the event originated, eventtype
is the type of event, params depends on the event
type. (See the explanation of W3Aevent
.)
How user functions can handle events is explained in the next section, together with the other functions that make up the W3A API.