W3A-U: User functions

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:

1. Zero or more labels (for use in a menu, or on buttons).

2. Zero or more corresponding icons (which some browsers may display in preference to a button or menu entry).

3. A list of object files.

4. 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 code is the number of the label that the user selected, counting from 1. A user function without labels still needs to define 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.