Logging and Event Hooks
Logging System
A logging system is implemented in CWASA allowing independent logging of events for different components at a number of levels:
- error: Error reporting using console.error. Always available.
- warn: Warning messages using console.warn. Always available.
- log: Sparing logging using console.log. Aways available.
- info: Additional logging using console.info.
- debug: Sign-level debugging information using console.info.
- trace: Low-level debugging information using console.info.
Messages identify the time, component, and message. For debug and trace the level of reporting is also given.
Main releases of the software do not display logging at a more detailed level than log. Development releases also display info. Only unstable development versions use debug and trace. It may be possible to test these using versions ending in t, u, or v. Unusually, the public method CWASA.getLogger() overrides this convention, allowing a logger to be configured to display messages at any level.
Using Loggers
- CWASA.getLogger(logger, loggerlevel): Configure and receive a CWASA logger.
This method takes a string for a class of logging and the lowest level to log (one of info to trace generally). The result is a logger which is an object whose fields have the names of the levels and hold logging functions. The fields will be null if no logger for the level exists so code must check that the level is supported first.
myLogger = CWASA.getLogger("myLog", "debug");
...
if (typeof (myLogger.trace) === "function") { myLogger.trace("My Message"); }
Further getLogger calls can be used to change the logging level dynamically.
Event Hook System
The CWASA software uses a system of hook functions that are called when significant events occur. This system is used internally but can also be used via a public interface. As a result, external software can receive and generate events.
Hook functions can be added to process events of a particular type. Many events relate to avatar panels and if multiple panels are used on a page, events can be directed to one or all panels. Equally, a hook function can be designated to respond to messages for one or all panels.
Using Hooks
- CWASA.addHook(typ, fun, av): Install a hook function to be called on specific events for specific avatar instances.
The method takes a string for the type of event, a hook function, and an optional avatar panel index. If no index is given, * is used, indicating that the hook should receive events for all panels.
This example from OneAvClientTest.html links to existing status events to create a log of messages in a text field.
function addStatus(evt) {
var elt = document.getElementById("myStatusLog");
var msg = evt.msg;
if (evt.av != "*") { msg = "[av" + evt.av + "] " + msg; }
elt.value = elt.value + msg + "\n";
}
CWASA.addHook("status", addStatus);
To post an event use the function
- CWASA.callHookL(typ, msg, av): Post and event to be passed to appropriate hook functions.
As before, the avatar panel index is optional. When omitted, the event will be passed to all hook functions of the given type. The data will be presented in an event object with fields type, for the type, and av, for avatar index. The msg field has a structure depending on the type of event. See an example above and more examples on the OneAv*Test.html pages.
Supported Events
- status: msg is a string. Used for reporting status changes to the console and to fields in the CWASA GUI.
- avatarloading: msg is a string naming the avatar being loaded. Used for updating avatar menus in the CWASA GUI.
- avatarloaded: msg is a string naming the avatar that has been loaded. Used for updating avatar menus in the CWASA GUI. If loading an avatar fails, the following avatarloaded event will indicate that the original avatar is reinstated.
- avatarready: msg is null. Indicates that the avatar has been loaded and rendered.
- sigmlloading: msg is null. Indicates that SiGML data is being processed. Used to update the CWASA GUI.
- sigmlsign: msg is a JSON object containing the frames of a sign. Available for user scripts.
- sigmlloaded: msg is an object with fields s for the number of signs and f for the number of frames. Used by the CWASA GUI.
- animactive: msg is null. Indicates that animation is in progress. Used to update the CWASA GUI. Will normally be issued before sigmlloaded has been signalled.
- animidle: msg is null. Indicates that animation has ceased. Used to update the CWASA GUI.
- avatarfps: msg is a floating point number giving the frames per second at which the designated avatar is rendering. Used to update the CWASA GUI.
- avatarframe: msg is an object with fields s for the sign index and f for frame index. Used to update the CWASA GUI. Called per frame. The indices are based at 0 so adding 1 will give a more natural presentation.
- avatarsign: msg is an object with fields g for the sign gloss, s for the sign index and f for frame index. Used to update the CWASA GUI. Called per sign and at the end of animation. The indices are based at 0 so adding 1 will give a more natural presentation. The frame index will be in the range associated with the sign.
It is perfectly possible to define your own events, install hooks for them, and generate events for them. If the type of event is unknown to CWASA there will be no effect on the rest of the software.
Public CWASA Interface
- CWASA.getLogger(logger, loggerlevel): Configure and receive a CWASA logger.
- CWASA.addHook(typ, fun, av): Install a hook function to be called on specific events for specific avatars.
- CWASA.callHook(typ, msg, av): Post an event to be passed to appropriate hook functions.