BirdWatcher log messages from code running in any Songbird area (including preference panes, dialogs and the main SB window) in any Songbird pane.

Setup - Transmitters

1) Install BirdWatcher add on.

2) Load BirdWatcher code into the sb area you want to log from with a script element in your XUL:

     src="chrome://birdwatcher/content/birdwatcher.js"

(or import birdwatcher.js using mozIJSSubScriptLoader)

3) In the code you want to log from create your transmitter object(s), e.g.:

       var log = new Transmitter()

You can provide optional parameters for:
  a channel name,
  some optional text, and
  an iconSpec.

if you do not want to use the defaults of extension name and js file name.

If you do not want to have to remove references to Transmitter and your transmitter object(s) before releasing your code, you could use something like:

     if (typeof Transmitter != 'undefined') {
         var log = new Transmitter()
     }
    if (!log) {
         var log={};
         log.cross=log.debug=log.info=log.tick=log.warn=function(){}
         log.error = function(text){Components.utils.reportError('your addon Name: '+text)}
      }

Set all the transmitter methods you use to the empty function when Transmitter is undefined!

The channel name and any 'optional text' can be used to close the transmitter from any receiver's 'close transmitters' button.

The optional image parameter: if the 4th character from the end is '.', the whole string is used as a file name for the image file, otherwise BirdWatcher assumes the string is a chrome name and uses that chrome skin's pane-icon :

    chrome://extName/skin/pane-icon.png .

4) Use the methods available on your transmitter objects to send messages to receiver(s) from anywhere in your code.

Transmitter objects' logging methods are:

    .info(text) - shows a blue dot
    .debug(text) - green
    .warn(text) - orange
    .error(text) - red
    .tick(text)
    .cross(text)

Transmitters' other methods are:
    .note('text','optional png fileName from BirdWatcher skin')
    .timer('an id','optional text') ; 1st call starts a timer, 2nd call stops it & logs the elapsed time
    .pause('optional text') stops this object transmitting
    .resume('optional text') restarts this object transmitting
    .quit('optional text') clears this transmitter object, leaving empty functions for the main methods, and removes added transmitter elements.

      
Setup - Receivers

You can have any number of receivers; each can display messages from any transmitter in any location.

1) Open the BirdWatcher pane. The service-pane opens 2 receivers the first time it is opened but thereafter opens just one. The content pane has 1 receiver.

Or 2) Set up Receiver(s) in your own pane XUL.

You do not have to copy BirdWatcher.xul into your xul. When a new Receiver object is instantiated in the JS for a pane, the BirdWatcher xul is inserted under the element (or element id) specified. The xul is appended to the pane, if no element is specified/found. A splitter is always inserted above each inserted receiver.

Alternatively, you can load BirdWatcher.xul from your JS or copy and paste it into your xul exactly where you want it.

To create a new receiver in js:

      var rec = new Receiver('a channel name','optional text',optional element(name))

You can access the receiver methods in you code to start and stop receiving, clear the receiver etc.

Display

Use the drop-down menu at the top to choose which channel to log at any particular time. If there is no receiver logging the transmitter objects with a particular channel you won't see those messages anywhere!

Each line in the log (latest at the top) shows:
    the sb area the message was sent from,
    any image from when the transmitter was instantiated,
    message type (blue/green/red/tick/cross etc., as above)
    '+', if the message has detail,
and the
    message text.

Hovering over the line shows the extension and js file from which the message was logged.

Receiver Buttons

    close Transmitters

receiver channel - drop-down menu of all transmitter channels which are active. 'BirdWatcher' shows all messages!

    clear receiver
    pause/resume receiver
    start/stop - a local timer
    show/hide receiver panel details
 
Long Messages and Objects

If you want to log a lot of text, log it as 2nd parameter:

       log.debug('short text','long text').

That line in the log will show a '+' before the short text; clicking it will pop-up the long text. This works for all transmitter logging methods.

If you log an object as the detail item, the detail pop-up shows the structure of the object with its properties, their types and values.

Arrays logged as detail show as hash objects with indices and values; when logged as short text they show as a string of comma-separated values!

Status monitoring.

If you define a log entry with
log.updatable(IdForLine,text,column list)

(Column list is comma-separated string of names for the columns you want.)

you can then issue:

log.update(icon,IdForLine,column name,detail,text)

the initial item will be updated with the appropriate icon in the named column. Handy for a quick status monitor! Any .png in birdWatcher/skin can be used as a icon. (BirdWatcher skin (now) includes pngs for 'debug','warn','error', 'tick', 'cross', 0-9, ?, etc.) Any detail is shown when that icon is clicked (each icon has its own detail). Any text will overwrite original line description

Closing Transmitters

The icon on the rhs of the receiver channel name allows you to close transmitters. Transmitters with any of the words entered into the prompt will log a final (closing) message and shut down. All of their properties are deleted and their methods set to the empty function. This creates an 'opening with no BirdWatcher' situation. Entering 'BirdWatcher' will close all transmitters.

BirdWatcher introduces only 2 constructors: 'Transmitter' and 'Receiver'.