]>
A viewer is used to add viewing capability for a new format. It is an interactive application that normally displays its output in a window provided by the browser. It is characterized by:
All viewers must export the following functions:
Bool initXXX(char ***mime_types, int
*nrtypes, float **qual)
(XXX
is replaced with the unique suffix.)
Initializes private variables and returns the list of formats
that the applet accepts. Each string in mime_types
must be a valid MIME type, possibly including wildcards
*
, ?
and []
(just like
Unix file name patterns). The qual
array must be
exactly as long as the mime_types
array and contain
numbers between 0.0 and 1.0. A return of FALSE
indicates an error, in which case errno holds the
error code (see...).
Bool openXXX(const W3ADocumentInfo
info, W3AWindow window, long id)
Directs the viewer to start a new window to display a
document of the indicated type. The passed window
is a drawing area in which the viewer can draw or place
sub-windows. In a browser that works with the X Toolkit, the
W3AWindow
type is just an alias for
Widget
, on other window systems it will be
something else. How to negotiate window positions and sizes is
platform dependent (see also W3Atoplevel
).
The return code is FALSE
in case of an error.
The ID is a unique number, generated by the browser. The routines below use the same ID to refer to the same viewer instance.
int writeXXX(long id, const char *buf, size_t
nchars)
Sends characters to the viewer. After the last call, a call
with nchars = 0
must be made, to indicate to the
viewer that the end of the data is reached. The viewer may
display the data immediately, or it may wait for the end of the
data. The return value is equal to
Bool closeXXX(long id)
Requests the viewer to destroy the window(s) corresponding to
void eventXXX(long id, long sourceid, long
eventtype, void *params)
This function is called when an abstract event occurred in
the browser or another applet. id is the accessory's
own ID, 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
.)
Bool infoXXX(long id, W3ADocumentInfo
*info)
This function may be called only after all data has been
written to the viewer (the last call to writeXXX
had nbytes = 0
). Calling infoXXX
gives
the viewer the opportunity to modify the title
field of info
. Other fields may also be modified,
but there is usually little sense in doing so. Most viewer will
return without modifying info
.
Like with all changes to fields of a
Warning: Note that the restriction that
W3ADocumentInfo
, the previous contents of the title
fields must be freed and the new contents must be allocated on
the heap.
infoXXX
may only be called after all the data has
been written to the viewer is different from the restriction
on infoXXX
in agents, where the function may be
called immediately after the openXXX
.