TracerManager.CreateTracer
Implementation : Function
Description : Creates a new tracing object
Signature : CreateTracer ()
Parameters : None
Returns : A tracing object
Notes : The TracerManager is a singleton factory-object, which is
instantiated automatically when a script is loaded, and which
manages the creation of Tracer objects, as well as the closure
of their windows on page exit (if this is required - see
TracerManager.CloseAll). All tracer objects must be created
through this function. I.e. never create a tracer object by
calling TracerManager.Tracer directly.
Multiple tracing-objects can be created.
Multiple TracerManagers are not possible (and would not be
useful).
TracerManager.CloseAll
Implementation : Function
Description : Closes all windows associated with any tracing objects
Signature : CloseAll ()
Parameters : None
Returns : Nothing
Notes : It is not necessary to call this function if the page does not
have an onunload event-handler defined in the body tag of the
page. This because the TracerManager object is able to tie into
the onunload event automatically.
A call to this function is necessary, however, if the page does
have an onunload event-handler, and should be made from within
that handler. This is because the presence of the handler's
definition in the body tag of the page overrides any event
handling tie-ins created in the page's JavaScript, thus leaving
the TracerManager powerless to close the windows automatically.
Failure to call this function, where a body tag event-handler
exists, will cause any existing tracer-windows to remain open
after the browser has left the page. This is inconvenient,
albeit harmless, as it requires the user to close any tracing
windows explicitly.
Tracer.OpenWin
Implementation : Function.
Description : Opens a window for a given tracer object.
Signature : OpenWin (Left, Top, Width, Height)
Parameters : Left - Integer denoting the X position of the window,
in pixels, relative to the global screen-coordinates
Top - Integer denoting the Y position of the window,
in pixels, relative to the global screen-coordinates
Width - Integer denoting the width in pixels of the
window
Height - Integer denoting the height in pixels of the
window
Returns : A reference to the tracer object that owns the window
Notes : Pop-up windows must be enabled on the host browser for this
function to work.
Any messages that have been buffered by the tracing object prior
to a call to this function are displayed in the resulting window.
Calling this function on a tracer object that already has a
window will have no effect.
This function will still work if a call to Tracer.Off has been
made previously.
The alwaysRaised property of the window is set to 'yes'. This may
have no effect in the host browser.
Tracer.CloseWin
Implementation : Function
Description : Closes the window associated with a given tracer object
Signature : CloseWin ()
Parameters : None
Returns : Nothing
Notes : Any messages that are sent to the tracer object following a call
to this function are buffered, unless Tracer.Off has been called
previously. Should Tracer.OpenWin be called subsequently to a
call to Tracer.CloseWin then any buffered messages are displayed
in the resulting window.
Closing a window and then opening it again does not cause
messages that were displayed previously to be re-displayed.
Calling this function on a tracer object that does not have a
window has no effect.
This function will still work if a call to Tracer.Off has been
made previously.
Call TracerManager.CloseAll to close all tracing windows.
A tracing window can be closed explicitly by the user (e.g. with
a mouse-click), but this event is not communicated to the tracing
object (for technical reasons). This is, however, harmless as the
associated tracer-object detects the missing window on the next
call to Tracer.MsgOut and buffers any messages sent through calls
to Tracer.MsgOut.
Tracer.MsgOut
Implementation : Function
Description : Displays a message in the tracing window
Signature : MsgOut (Message)
Parameters : Message - String containing the message to be displayed
Returns : 'true' if the tracing window is open
'false' if the tracing window is closed
Notes : If no window exists for the tracing object in question then the
message is buffered, unless Tracer.Off has been called
previously. A subsequent call to Tracer.OpenWin causes the buffer
contents to be displayed in the resulting window. A call to this
function, following a call to Tracer.CloseWin, causes the message
to be buffered, unless Tracer.Off has been called.
Buffering is provided because there may be times when global code
is executed during the initialisation of the page, and it may not
be possible/desirable to open a tracing window prior to the
execution of such code.
Calls to this function, where the user has closed the window
explicitly using the mouse or keyboard, causes the message to be
buffered, unless Tracer.Off has been called previously, in which
case the call is ignored.
Tracer.MsgOut_Numbered
Implementation : Function
Description : Displays the value of the message counter, and and optional
message
Signature : MsgOut_Numbered ([Message])
Parameters : Message - Optional, string containing a message to be
displayed
Returns : Nothing
Notes : Each tracer object maintains an integer counter that is set to
zero upon tracer instantiation. When this function is called the
value of the counter is displayed in the tracing window (or sent
to the message buffer, if appropriate), and then incremented. This
allows one to keep track of the number of numbered messages
displayed so far, thus obviating the need to maintain a separate
counter in the code that is being debugged.
See Tracer.ResetMsgNumber for details on resetting the counter to
zero.
Calls to Tracer.MsgOut do not make use of, or affect, the counter.
Tracer.ResetMsgNumber
Implementation : Function
Description : Resets the numbered-message counter to zero
Signature : ResetMsgNumber ()
Parameters : None
Returns : Nothing
Notes : Each tracer object maintains an integer counter that is set to
zero upon tracer instantiation. When MsgOut_Numbered is called this
number is displayed, along with an optional user-defined message,
and then incremented. This function resets the counter to zero.
Tracer.On
Implementation : Function
Description : Turns tracing on for a given tracer object
Signature : On ()
Parameters : None
Returns : Nothing
Notes : Tracing is on by default for new Tracer objects.
Any calls to Tracer.MsgOut that follow a call to Tracer.Off and
precede a call to this function are ignored (messages are neither
buffered nor displayed, should a window exist for the tracer
object in question).
Calling this function where tracing is already active has no
effect.
Tracer.Off
Implementation : Function
Description : Turns tracing off for a given tracer object
Signature : Off ()
Parameters : None
Returns : Nothing
Notes : Calling this function causes calls to Tracer.MsgOut to have no
effect.
Calling this function where tracing has already been turned off
has no effect.
Messages that have been buffered prior to calling this function
are displayed should a tracing window be opened subsequently.
It would be advantageous to be able to place a button in the
tracer window, such that one could toggle tracing with a click of
the mouse. This, however, requires injecting JavaScript code into
the execution context of the tracing window, which must then
communicate with the execution context of the host page. Getting
this to work across all browsers is tricky, although this feature
may be added to the library at some point in the future.