// The authoritative version of this file is with the burstproject repository. 
/**
* @file fix_ecma.js
*
* This attempts to bring builtin objects such as Array and Function
* into compliance with ECMAScript edition 3 (JavaScript 1.5).
*
* The main target is support for IE5.0 Windows (JScript 5.0). Even there,
* we do not attempt to compensate for all its missing features (such as lacking
* non-greedy regexps, etc.).
*
* This file has no dependencies on any other file.
*
* This file only affects the builtin ECMAScript objects, except that it
* does keep track of the names has defined in the global Array <var>bu_fixed</var>.
*
* @author Copyright 2003 Mark D. Anderson (mda@discerning.com)
* @author Licensed under the Academic Free License 1.2 http://www.opensource.org/licenses/academic.php
*/

/** Array of names of symbols we've defined */
//:GLVAR Array bu_FIXED = [];
var bu_fixed = [];

// function to register a fixed name
function bu_fixing(name) {
	// don't use Array.push, as we may not have defined it yet....
	bu_fixed[bu_fixed.length] = name;
}

// Modified from Usenet posts by David Crockford and Yep (y-e.perio@em-lyon.com)
if (!Function.prototype.apply) {
	bu_fixing('Function.apply');
	Function.prototype.apply = function bu_fix_apply(o,a) {
		var r;
		if(!o){ o = {}; } // in case func.apply(null, arguments).
		o.___apply=this;
		switch((a && a.length) || 0) {
			case 0: r = o.___apply(); break;
			case 1: r = o.___apply(a[0]); break;
			case 2: r = o.___apply(a[0],a[1]); break;
			case 3: r = o.___apply(a[0],a[1],a[2]); break;
			case 4: r = o.___apply(a[0],a[1],a[2],a[3]); break;
			case 5: r = o.___apply(a[0],a[1],a[2],a[3],a[4]); break;
			case 6: r = o.___apply(a[0],a[1],a[2],a[3],a[4],a[5]); break;
			default: 
				for(var i=0, s=""; i<a.length;i++){
					if(i!=0){ s += ","; }
					s += "a[" + i +"]";
				}
				r = eval("o.___apply(" + s + ")");
		}
		// note that delete is not in JS1.1 and thus won't work in IE5.0 PC.
		// since this is a workaround anyway, we just let it stay.
		//delete o.___apply;
		o.__apply = null;
		return r;
	}
}

if (!Function.prototype.call) {
	bu_fixing('Function.call');
	Function.prototype.call = function bu_fix_call(o) {
		// copy arguments and use apply
		var args = new Array(arguments.length - 1);
		for(var i=1;i<arguments.length;i++){
			args[i - 1] = arguments[i];
		}
		return this.apply(o, args);
	}
}

/*
* There are many re-implementations of these Array functions available, for example:
* - http://www.crockford.com/javascript/remedial.html
* - http://www.webreference.com/dhtml/column33/
* - http://www.technicalpursuit.com/Dev_viewsource.html
* - http://www.informit.com/isapi/product_id~{E40D98B6-703F-4ED9-9B6C-9DD2E731FAD5}/element_id~{26FC4DC0-4520-47D2-B188-EFF1FF8F2E10}/st~{68F792C2-D59B-43BA-A07E-F0B1569A0392}/session_id~{2FF7DAF3-4594-49C3-9928-042852C1BF38}/content/articlex.asp
* - http://cvs.berlios.de/cgi-bin/viewcvs.cgi/jsunit/jsunit/lib/JsUtil.js?rev=1.14&content-type=text/vnd.viewcvs-markup
*
* I have no particular reason to prefer the implementations given here, except that I wrote them.
*/

if (!Array.prototype.push) {
	bu_fixing('Array.push');
	Array.prototype.push = function bu_fix_push() {
		for (var i = 0; i < arguments.length; i++){
			this[this.length] = arguments[i];
		}
		return this.length;
	};
}

if (!Array.prototype.pop) {
	bu_fixing('Array.pop');
	Array.prototype.pop = function bu_fix_pop() {
		if(this.length == 0){ 
			try{
				return undefined; 
			}catch(e){
				return null;
			}
		}
		return this[this.length--];
	}
}

if (!Array.prototype.shift) {
	bu_fixing('Array.shift');
	Array.prototype.shift = function bu_fix_shift() {
		this.reverse();
		var lastv = this.pop();
		this.reverse();
		return lastv;
	}
}

if (!Array.prototype.splice) {
  bu_fixing('Array.splice');
  Array.prototype.splice = function bu_fix_splice(start, deleteCount) {
    var len = parseInt(this.length);

    start = start ? parseInt(start) : 0;
    start = (start < 0) ? Math.max(start+len,0) : Math.min(len,start);

    deleteCount = deleteCount ? parseInt(deleteCount) : 0;
    deleteCount = Math.min(Math.max(parseInt(deleteCount),0), len);

    var deleted = this.slice(start, start+deleteCount);

    var insertCount = Math.max(arguments.length - 2,0);
    // new len, 1 more than last destination index
    var new_len = this.length + insertCount - deleteCount;
    var start_slide = start + insertCount;
    var nslide = len - start_slide; // (this.length - deleteCount) - start
    // slide up
    for(var i=new_len - 1;i>=start_slide;--i){
		this[i] = this[i - nslide];
	}
    // copy inserted elements
    for(i=start;i<start+insertCount;++i){
		this[i] = arguments[i-start+2];
	}
    return deleted;
  }
}

if (!Array.prototype.unshift) {
  bu_fixing('Array.unshift');
  Array.prototype.unshift = function bu_fix_unshift() {
     // prepare for a call to splice
     var a = [0,0];
     for(var i=0;i<arguments.length;i++){
		 a.push(arguments[i]);
	 }
     var ret = this.splice.apply(a);
     return this.length;
  }
}

// determine version of JScript, or null
// ScriptEngineMajorVersion is in JScript 5.
var bu_jscript_version = null;
if (typeof ScriptEngineMajorVersion == 'function') {
  bu_jscript_version = parseFloat(ScriptEngineMajorVersion() + '.' + ScriptEngineMinorVersion());
}

/*
ECMAScript edition 3 says that the Error object has properties "name" and "message".

IE5 (JS.0) does not have "name" or "message", just "description" (same as "message") and "number".

The IE5 number is: errorObject.number & 0xffff, where facility code and error code are 16-bits each.

IE5.5 supports both "message" and "name".

Note that this doesn't help much regarding native Error objects thrown in IE5.0.
*/
if((typeof Error == 'undefined')||(bu_jscript_version&&(bu_jscript_version < 5.5))){
	bu_fixing('Error');
	Error = function(msg) { 
		if(!(this instanceof Error)){
			return new Error(msg); 
		}
		this.message = msg || '';
		return this; // just to silence warnings
	};
	Error.prototype = new Object();
	Error.prototype.name = 'Error';
	Error.prototype.toString = function(){
		return this.name + ': ' + this.message;
	};
}

if(typeof bu_loaded != 'undefined'){ bu_loaded('fix_ecma.js'); }
<!-- 
/*--> 
<!--*/
// $Id: sigslot_core2.js,v 1.35 2004/09/08 22:32:11 russcoon Exp $
// Copyright (C) 2003 Mark D. Anderson (mda@discerning.com)
// Licensed under the Academic Free License version 1.2
//
// This is a re-implementation of sigslot_core.js that is faster.
//
// It implements these interface functions:
//   connectByName
//   connectOnceByName
//   disconnectAllByName
//   addBareSignalByName
//   addBareSigByName
// It does not implement the other functions in the original.
// At this time, the above functions are the only ones used within the NW library.
//
// This file uses Function.apply, Array.push, and Array.splice.  If you want it
// to work on IE5.0 PC or other deficient EcmaScript implementations, you may
// want to include fix_ecma.js as well. 
// 
// I ran a Mozilla profiler on combo_box_test.html using Mozilla 1.4 on a Mac
// OS X 1Ghz.  Comparing addBareSignalName:
//    sigslot_core.js v1.46    125 Total Calls  Total Time: 1567.11 (min/max/avg 1.43/71.76/12.54).
//    sigslot_core2.js         140 Total Calls  Total Time: 44.95 (min/max/avg 0.03/12.25/0.32)
// (The unequal number of calls is due to differences in whether caller or
// callee determines whether the call is necessary.)

/*--> 
<sect1 id="sigslot_core.js">
	<title><filename>sigslot_core.js</filename></title>
	<para lang="en">
		The term "&sigslot;" referrs to a method of multi-dispatch
		function/method calling which can be used to provide anonymous event
		notification. In less dense terms, this means that &sigslot;
		allows programmers to worry less about how a method is going to be
		called in event-driven code. &sigslot; takes care of the
		details of "connecting" two functions togeather, and makes fewer
		up-front demands of programmers than traditional callback-style event
		handling.
	</para>
	<para lang="en">
		The word Signal refers to a method or function that is being listened
		for, and a Slot referrs to any function or method that should also be
		called with the Signal is called (or "emitted"). Since the methods do
		not need to be aware that they are going to function as either Signals
		or Slots, code can be written in a more natural fashion without having
		to worry about triggering callbacks from each Signal.
	</para>
	<para lang="en">
		The ideas behind the &sigslot; (sigslot) model of event
		handling are in no way new or novel. As Mark Anderson is keen to point
		out, the term "slot" to describe a method dates at least back to
		<ulink url="http://www.lisp.org/table/objects.htm">CLOS</ulink>.
	</para>
	<para lang="en">
		More recently, the concepts of specific &sigslot; in imperitive
		and object oriented languages have been taken up by successful GUI
		toolkits such as QT and GTK+. These toolkits use &sigslot; to provide
		information to programmers about the state of generic widgets that can
		be customized at runtime and whose definition is not necessarialy under
		the control of the programs which need to be informed of events. The
		&nw; toolkit uses Signald and Slots in a similar fashion, with this
		library forming the core of all of the mouse and keyboard event
		propagation code in the API.
	</para>
	<para lang="en">
		What follows is the API documentation for the &sigslot; implmentation
		from the &nw; framework. This library can be used in a stand-alone
		fashion, and does not require a browser, any ECMA262-3 environment will
		work.
	</para>
	<!-- spanish translation -->
	<para lang="es">
		El t&eacute;rmino "Se&ntilde;ales y Rastros" hace referencia a un
		m&eacute;todo de env&iacute;o m&uacute;ltiple de llamadas a
		funci&oacute;n/m&eacute;todo que puede ser empleado para proporcionar
		notificaci&oacute;n an&oacute;nima de eventos. Empleando
		t&eacute;rminos m&aacute;s sencillos, esto significa que Las
		Se&ntilde;ales y los Rastros permiten a los programadores
		despreocuparse de c&oacute;mo un m&eacute;todo va a ser llamado en el
		c&oacute;digo dirigido a eventos. Se&ntilde;ales y Rastros cuida de los
		detalles de la "conexi&oacute;n" entre dos funciones, y hace mucho
		menor la demanda para los programadores que el m&eacute;todo
		tradicional de manejo de eventos con el estilo de llamadas hacia
		atr&aacute;s.
	</para>
	<para lang="es">
		La palabra Se&ntilde;al se refiere a un m&eacute;todo o funci&oacute;n
		que est&aacute; siendo escuchado, y un Rastro se refiere a cualquier
		funci&oacute;n que deber&iacute;a ser llamada cuando es llamada la
		se&ntilde;al (o "emitida"). Partiendo de que los m&eacute;todos no
		necesitan preocuparse de si van a funcionar como Se&ntilde;ales o como
		Rastros, el c&oacute;digo puede ser escrito de modo m&aacute;s
		naturalsin tener que preocuparse de disparar llamads atr&aacute;s para
		cada Se&ntilde;al.
	</para>
	<para lang="es">
		Las ideas detr&aacute;s del modelo de manejo de eventos con
		Se&ntilde;ales y Rastros(sigslot) no son novedosas. Como Mark Anderson
		es tan amable de apuntarme, el t&eacute;rmino "slot" para describir un
		m&eacute;todo data al menos de <ulink
		url="http://www.lisp.org/table/objects.htm">CLOS</ulink>.
	</para>
	<para lang="es">
		M&aacute;s recientemente, los conceptos de Se&ntilde;ales y Rastros
		espec&iacute;ficos en lenguajes imperativos y orientados a objetos han
		sido adoptadas con &eacute;xito por herramientas GUI como QT y GTK+.
		Estas herramientas usan sigslot para proporcionar informaci&oacute;n a
		los programadores acerca de el estado de widgets gen&eacute;ricos que
		pueden personalizarse en tiempo de ejecuci&oacute;n y cuya
		definici&oacute;n no tiene porque estar necesariamente bajo el control
		de los programas que necesitan esa informaci&oacute;n sobre los
		eventos. La herramienta &nw; usa Se&ntilde;ales y Rastros de un modo
		similar, con esta librer&iacute;a formando parte del n&uacute;cleo de
		toda la propagaci&oacute;n de eventos del teclado y el mouse en la API.
	</para>
	<para lang="es">
		Lo que sigue es la documentaci&oacute;n de la API para la
		implementaci&oacute;n de Se&ntilde;ales y Rastros perteneciente al
		marco de trabajo de &nw;. Esta librer&iacute;a puede ser empleada en
		solitario y no requiere un navegador, simplemente un entorno ECMA262-3
		para funcionar correctamente.
	</para>
<!--*/


try{ // try block necessary for CLI usage
	if(window["__scripts__"]){
		__scripts__.provide(__config__.corePath+"sigslot_core.js");
		__scripts__.require(__config__.corePath+"fix_ecma.js");
	}
}catch(e){
	window = this;
}

/*--> 
	<sect2 id="__sig__">
		<title>__sig__</title>
		<para lang="en">
			The &__sig__; singleton provides a centralized, anonymous Signals
			and Slots event passing mechanism. &sigslot; is a method
			for abstracted event propigation used mainly in GUI toolkits like
			&nw;. Instead of defining callback handlers on every object or
			method we wish to provide outside access to, &sigslot; provides
			a way of "connecting" functions and methods without extra work on
			the part of the function/method author. Functions and methods never
			need be aware of the &sigslot; mechanism's existance to act as
			either emitters (signals) or listeners (slots) for an event. Even
			better, the &sigslot; style of event handling can be grafted into
			existing code with minimal rework, significantly reducing
			implementation overhead.
		</para>
		<para lang="es">
			El objeto &uacute;nico &__sig__; proporciona un mecanismo de pasar
			eventos centralizado y an&oacute;nimo, mediante Se&ntilde;ales y
			Rastros. Se&ntilde;ales y Rastros es un m&eacute;todo para la
			propagaci&oacute;n abstracta de eventos usado principalmente en
			herramientas GUI como &nw;. En lugar de definir manejadores de
			llamadas hacia atr&aacute;s en cada objeto o m&eacute;todo sobre el
			que deseamos proporcionar acceso externo, se&ntilde;ales/rastros
			proporciona un modo de "conectar" funciones y m&eacute;todos sin
			trabajo extra por parte del autor de las funciones/m&eacute;todos.
			Las funciones y los m&eacute;todos nunca necesitan cuidar de la
			existencia del mecanismo de se&ntilde;ales/rastros para actuar
			tanto como emisores (se&ntilde;ales) o escuchadores (rastros) de un
			evento. Todav&iacute;a mejor, el estilo de manejo de eventos de
			se&ntilde;ales/rastros puede ser insertado en cualquie
			c&oacute;digo existente con un m&iacute;nimo trabajo adicional,
			reduciendo significativamente el proceso de implementaci&oacute;n.
		</para>
		<sect3 id="__sig__.properties">
			<title lang="en">Properties</title>
			<title lang="es">Propiedades</title>
<!--*/

__sig__ = new function(){
	var sestr = "please pass the name of the function, not a pointer";

	/*--> 
	<fieldsynopsis id="__sig__.lock">
		&public; &bool;
		<varname>lock</varname>
		<initializer>&false;</initializer>
	</fieldsynopsis>
	<para role="fieldinfo" lang="en">
		<varname>lock</varname> determines whether or not slots listening on
		signals will be called when a signal is emitted. When set to &false;,
		slots will be called when signals are emitted. When
		<varname>lock</varname> is &true;, no slots will be called, although
		the signal function will be called with the passed parameters, as
		normal.
	</para>
	<para role="fieldinfo" lang="es">
		<varname>lock</varname> determina cuando o no los rastros escuchando
		estas se&ntilde;ales van a ser llamados cuando una se&ntilde;al es
		emitida. Si se fija a &false;, los rastros van a ser llamados cuando
		las se&ntilde;ales son emitidas. Cuando <varname>lock</varname> es
		&true;, los rastros no van a ser llamados, aunque la funci&oacute;n
		se&ntilde;al va a ser llamada con los mismos par&aacute;metros, tal
		como se hace normalmente.
	</para>
	<!--*/
    this.lock = false;

	/*--> 
	<fieldsynopsis id="__sig__.squelchSlotExceptions">
		&public; &bool;
		<varname>squelchSlotExceptions</varname>
		<initializer>&true;</initializer>
	</fieldsynopsis>
	<para role="fieldinfo" lang="en">
		Determines how an exception thrown from a slot is handled. Signal
		exception handling is never intercepted. When this property is set to
		&false;, any exception thrown from a slot will prevent all remaining
		slots on a signal from being called and an exception will bubble up.
	</para>
	<!--*/
    this.squelchSlotExceptions = true;


	/*--> 
	<fieldsynopsis id="__sig__.timeCalls">
		&public; &bool;
		<varname>timeCalls</varname>
		<initializer>&false;</initializer>
	</fieldsynopsis>
	<para role="fieldinfo" lang="en">
		Should the &__sig__; object keep timing information about the methods
		called through it and its dependencies?
	</para>
	<!--*/
	this.timeCalls = ((window["__config__"])&&(__config__.profileSigslot)) ? __config__.profileSigslot : false;

	/*--> 
	<fieldsynopsis id="__sig__.timingData">
		&public; &assoc_arr; <varname>timingData</varname>
	</fieldsynopsis>
	<para role="fieldinfo" lang="en">
		Timing information about calls to functions and their listeners.
	</para>
	<!--*/
	this.timingData = [];

	var anonFuncId = 0;

	/*--> 
		</sect3>
		<sect3 id="__sig__.methods">
			<title>Methods</title>
	<!--*/

	/*--> 
	<methodsynopsis id="__sig__.setAnonFunc">
		&public; &str;
		<methodname>setAnonFunc</methodname>
		<methodparam>&func_ptr; <parameter>funcObj</parameter></methodparam>
	</methodsynopsis>
	<para role="methodinfo">
		<methodname>setAnonFunc</methodname> is useful in situations where
		developers want to quickly connnect an anonymous function to some
		signal. Since the <methodname>connect*</methodname> methods of
		&__sig__; all require a function name as an argument, this method will
		take a function object (or pointer) and return a unique name in the
		global namespace which it has bound the function to. To understand how
		this works (and why it's useful), consider a case where someone wants
		to connect an event handler on a &node; to a one-off behavior or
		potentially using references to variables which are only bound to the
		local scope. Using <methodname>setAnonFunc</methodname>, that task
		might be preformed in this way:
	</para>
<programlisting><![CDATA[var inputArea = document.createElement("input");
inputArea.type = "text";

var alertButton = document.createElement("input");
alertButton.type = "button";
alertButton.value = "click me!";

var funcName = __sig__.setAnonFunc(function(){
	alert("input vaue is: "+inputArea.value);
});

document.body.appendChild(alertButton);
document.body.appendChild(inputArea);

__sig__.connectByName(alertButton, "onclick", null, funcName);]]></programlisting>
	<para role="methodinfo">
		Note that all of this code could occur within a function
		<emphasis>without modification</emphasis>. Because JavaScript is
		closure-based, the <varname>inputArea</varname> and
		<varname>alertButton</varname> variables will not loose their value in
		the anonymous function that is created the next time a function
		containing this code is called. In this way
		<methodname>setAnonFunc</methodname> can also assist developers is
		reducing the number of synthetic IDs they need to create and the number
		of DOM operations required for many tasks.
	</para>
	<!-- FIXME: need new translation for this section -->
	<!--*/
	this.setAnonFunc = function(funcObj, funcCaller){
		if(!funcCaller){ funcCaller = window; }
		var fn = "NWanonFunc"+anonFuncId++;
		if(!funcCaller[fn]){
			funcCaller[fn] = funcObj;
			return fn;
		}else{
			// keep trying
			return this.setAnonFunc(funcObj, funcCaller);
		}
	}

	/*--> 
	<methodsynopsis id="__sig__.connectByName">
		&public; &bool;
		<methodname>connectByName</methodname>
		<methodparam>&obj; <parameter>sigObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>sigFuncName</parameter></methodparam>
		<methodparam>&obj; <parameter>slotObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>slotFuncName</parameter></methodparam>
		<methodparam>&bool; <parameter>once</parameter></methodparam>
		<methodparam>&arr; <parameter>defaultArgs</parameter></methodparam>
		<methodparam>&arr; <parameter>overRideArgs</parameter></methodparam>
		<methodparam>&arr; <parameter>mutators</parameter></methodparam>
		<methodparam>&obj; <parameter>singleMutator</parameter></methodparam>
	</methodsynopsis>
	<para role="methodinfo">
		<methodname>connectByName</methodname> handles the mechanics of
		attaching signal functions to slot functions.
		<methodname>connectByName</methodname> takes four arguments, or rather,
		two pairs of arguments. The first and third argument specify namespace
		objects which the named methods (the second and fourth arguments) are
		members of. These can be &null; to indicate membership in the global
		namespace. The second and fourth arguments <emphasis>must</emphasis> be
		strings which name the functions to be connected. Previous versions of
		the signals and slots library supported two connection models, one
		using function pointers and the other function name strings. The latter
		has been choosen for ongoing development and no form of the former is
		supported.
	</para>
	<para role="methodinfo">
		The returned &bool; indicates success or failure of the conection.
		Failure can occur when <parameter>once</parameter> is specified but a
		connection already exists. For documentation on the
		<parameter>defaultArgs</parameter>,
		<parameter>overRideArgs</parameter>, and
		<parameter>mutators</parameter> parameters, see the documentation for
		<link linkend="__sig__.connect">
			&__sig__;.<methodname>connect</methodname>
		</link>.
	</para>
	<!-- FIXME: need new translation for this section -->
	<!--*/
	/**
	* Add a post-trigger to obj[funcName].
	*
	* After this is done, whenever obj[funcName] is called in the future:
	* 1. The original obj[funcName] (if any) is invoked, and the return value
	*    retained.
	* 2. If __sig__.lock is not true, invoke all subscribers
	*    trigObj[trigFuncName] in subscription order.
	* 3. Return the return value from the original function.
	*
	* If there is no original obj[funcName], one that simply returns true is
	* used.
	*
	* Naturally, the original function and all subscribers should expect the
	* same argument signature.
	*
	* Either obj or trigObj may be null; they are defaulted to window.
	*
	* If onceOnly is true, it will ensure that trigObj[trigFuncName] is not
	* already subscribed.  Otherwise it will not spend the time to check.
	*
	* This functionality is implemented by giving obj some new "hidden"
	* members:
	*    obj[funcName + '__orig__']        = the original Function
	*    obj[funcName + '__subscribers__'] = an Array of [trigObj,trigFuncName] pairs, to call
	*    obj[funcName]                     = a wrapper Function to do the work at run time.
	*
	* If onceOnly and it was already subscribed, returns false. Otherwise
	* returns true.
	*/ 
	this.connectByName  = function(obj, funcName, trigObj, trigFuncName, onceOnly, defaultArgs, overRideArgs, mutators, finalMutator){
		if(!obj){ obj = window; }
		if(!trigObj){ trigObj = window; }

		// beats me why original connectByName wraps the slot function, not
		// just the signal function, but we do that here too for consistency.
		this.addBareSignalByName(trigObj, trigFuncName);

		var subs = this.addBareSignalByName(obj, funcName);
		if(onceOnly){
			for(var i=subs.length-1; i>=0; i=i-1){
				if((subs[i][0] === trigObj)&&(subs[i][1] == trigFuncName)){
					return false;
				}
			}
		}
		subs.push([trigObj, trigFuncName, defaultArgs, overRideArgs, mutators, finalMutator]);
		return true;
	}

	/*--> 
	<methodsynopsis id="__sig__.connectOnceByName">
		&public; &void;
		<methodname>connectOnceByName</methodname>
		<methodparam>&obj; <parameter>sigObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>sigFuncName</parameter></methodparam>
		<methodparam>&obj; <parameter>slotObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>slotFuncName</parameter></methodparam>
	</methodsynopsis>
	<para role="methodinfo" lang="en">
		<methodname>connectOnceByName</methodname> connects to functions iff
		(if and only if) no previous connection between the functions has been
		defined. This is useful in situations where you want to ensure
		that when a signal is emitted a particular listener is only called once.
	</para>
	<para role="methodinfo" lang="es">
		<methodname>connectOnceByName</methodname> conecta a funciones si (si y
		s&oacute;lamente si) ninguna conexi&oacute;n previa entre las funciones
		ha sido definida. Esto es &uacute;til en situaciones en las que quieres
		asegurarte de que cuando una se&ntilde;al es emitida un escuchador en
		particular s&oacute;lo es llamado una vez.
	</para>
	<!--*/
	// thin wrappers
    this.connectOnceByName = function(o,f,to,tf) {
		return this.connectByName(o,f,to,tf,true);
	}

	/*--> 
	<methodsynopsis id="__sig__.disconnectOnceByName">
		&public; &void;
		<methodname>disconnectOnceByName</methodname>
		<methodparam>&obj; <parameter>sigObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>sigFuncName</parameter></methodparam>
		<methodparam>&obj; <parameter>slotObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>slotFuncName</parameter></methodparam>
	</methodsynopsis>
	<para role="methodinfo" lang="en">
		Removes this first signal listener registered on the the specified slot
		corresponding to the function/method name passed by the first two
		parameters. For signals with duplicate listeners, this will only remove
		the first. To remove all identical slots from a signal, use
		<methodname>disconnectAllByName</methodname> instead.
	</para>
	<para role="methodinfo" lang="es">
		Elimina este primer escuchador de se&ntilde;al registrado en el rastro
		especificado correspondiente al nombre de la
		funci&oacute;n/m&eacute;todo pasado por los primeros dos
		par&aacute;metros. Para se&ntilde;ales con escuchadores duplicados,
		este m&eacute;todo s&oacute;lo eliminar&aacute; la primera. Para
		remover todos los rastros id&eacute;nticos para una se&ntilde;al, usa
		<methodname>disconnectAllByName</methodname> en su lugar.
	</para>
	<!--*/
    this.disconnectOnceByName = function(o,f,to,tf) {
		return this.disconnectAllByName(o,f,to,tf,true);
	}

	/*--> 
	<methodsynopsis id="__sig__.disconnectAllByName">
		&public; &int;
		<methodname>disconnectAllByName</methodname>
		<methodparam>&obj; <parameter>sigObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>sigFuncName</parameter></methodparam>
		<methodparam>&obj; <parameter>slotObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>slotFuncName</parameter></methodparam>
	</methodsynopsis>
	<para role="methodinfo" lang="en">
		Almost identical to <methodname>disconnectOnceByName</methodname>,
		except that it removes all duplicte slots from the specified signal,
		not just the first. The return of the function is an integer
		representing the number of listeners disconnected.
	</para>
	<!-- FIXME: need to get return value documented in spanish -->
	<para role="methodinfo" lang="es">
		Pr&aacute;cticamente id&eacute;ntico a
		<methodname>disconnectOnceByName</methodname>, excepto que elimina
		todos los rastros duplicados para la se&ntilde;al especificada, no
		s&oacute;lo el primero.
	</para>
	<!--*/
	/**
	* Removes all subscribers to obj[funcName] which match trigObj[trigFuncName].
	*
	* Returns the number of subscribers removed.
	* 	optional 5th argument indicates to only remove a single subscriber
	*/
    this.disconnectAllByName = function(obj, funcName, trigObj, trigFuncName, onceOnly) {
		if(!obj){ obj = window; } // null means the global object, which we assume to be window
		var subs = obj[funcName + '__subscribers__'];
		if(!subs){ return 0; } // indicates no connections
		if(!trigObj){ trigObj = window; } // null means the global object, which we assume to be window
		// loop from back so we can delete as we go
		var count = 0;
		for(var i=subs.length-1;i>=0;i=i-1) {
			if ((subs[i][0] === trigObj)&&(subs[i][1] == trigFuncName)) {
				subs.splice(i, 1);
				count++;
				if(onceOnly){ break; }
			}
		}
		return count;
	}

	/*--> 
	<methodsynopsis id="__sig__.addBareSignalByName">
		&public; &void;
		<methodname>addBareSignalByName</methodname>
		<methodparam>&obj; <parameter>sigObj</parameter> <initializer>window</initializer></methodparam>
		<methodparam>&str; <parameter>sigFuncName</parameter></methodparam>
	</methodsynopsis>
	<para role="methodinfo" lang="en">
		Courtesy function for internal use when connections are created.
		Exposed as a <literal>public</literal> member only because we cannot
		predict where it will be needed.
	</para>
	<!-- FIXME: need to update docs here -->
	<para role="methodinfo" lang="es">
		Funciones de cortes&iacute;a, la mayor&iacute;a para uso interno cuando
		los m&eacute;todos <methodname>*ByName</methodname> est&aacute;n siendo
		utilizados para proporcionar conexiones. Expuestas como un miembro
		<modifier>public</modifier> s&oacute;lo porque no podemos predecir
		donde van a ser necesarias.
	</para>
	<!--*/
	/**
	* You have no particular reason to call this function directly.
	* (I frankly don't know why the current NW library has so many direct calls to
	* addBareSignalName everywhere.)
	*
	* Performs the act of replacing obj[funcName] with a function that iterates over
	* subscribers instead. It does nothing if this has already been done.
	*
	* Returns the Array of subscriber data.
	*/
	this.addBareSignalByName = function(obj, funcName) {
		if(!obj){ obj = window; }
		var subname = funcName + '__subscribers__';
		// check in a way to silence warnings
		var subs = typeof obj[subname] == 'undefined' ? null : obj[subname];

		// already wrapped; just return.
		if(subs){ return subs; }

		var origname = funcName + '__orig__';
		obj[origname] = obj[funcName] || function(){ return true; };
		subs = obj[subname] = [];
		// note this function definition relies on lexical binding of obj and subs.
		obj[funcName] = function(){
			try{
				if(typeof(__sig__) != 'undefined' && __sig__ != 'undefined' && __sig__.timeCalls){
					if(!__sig__.timingData[funcName]){
						__sig__.timingData[funcName] = [];
					}
					var sl = __sig__.timingData[funcName].length;
					__sig__.timingData[funcName].push([new Date()]);
				}

				// call the original (if we can)
				if((!obj)||(!obj[origname])){ return; }
				var ret = obj[origname].apply(obj, arguments);
				if(__sig__.timeCalls){
					__sig__.timingData[funcName][sl].push(new Date());
				}
				// invoke all subscribers unless lock is set
				if(__sig__.lock){ return ret; }
				for(var i=0;i<subs.length;++i){
					var na = [];	// we've gotta copy over the arguments so we
									// don't pollute the args array on subsequent
									// passes
					var trigObj = subs[i][0];
					var das = subs[i][2]; // check to see if there are any default params...
					var oas = subs[i][3]; // ...or over-ride params...
					var mas = subs[i][4]; // ...or mutators....
					var fmas = subs[i][5];// ...or a final mutator
					if(das||oas||mas){ // merge defaults with conditional over-ride
						if(!das) das = new Array();
						if(!oas) oas = new Array();
						if(!mas) mas = new Array();
						if(!arguments) arguments = new Array();
						// FIXME: we assume ECMAv3 Math.max here, is that sane?
						var tl = Math.max(das.length, oas.length, mas.length, arguments.length);
						for(var j=0; j<tl; j++){
							if(((typeof na[j] == "undefined")&&(das[j]))||(oas[j])){
								na[j]=oas[j]||das[j];
							}else{
								na[j]=arguments[j];
							}
							if(mas[j]){
								na[j] = mas[j](na[j], na);
							}
						}
						// set size property if necessaray
						if(das.length>na.length){ 
							na.length = das.length;
						}
					}else if(fmas){
						for(var x=0; x<arguments.length; x++){
							na.push(arguments[x]);
						}
					}else{
						// make sure the common case isn't slowed down the
						// default/overRide/mutator handling
						// na = arguments;
						na = arguments;
					}
					// the final mutator MUST return an array
					if(fmas){
						na = fmas(na);
					}
					// FIXME: need to determine a better way to handle errors
					// without always hitting the overhead of try{}catch(e){}.
					try{	
						trigObj[subs[i][1]].apply(trigObj, na);
					}catch(e){
						if(!__sig__.squelchSlotExceptions){
							throw e;
						}
						// FIXME: need to ensure that error properties are
						// 		  correctly enumerated in the logging of the
						// 		  exception
	                    // FIXME: log level should be configurable
	                    // FIXME: should __log__.exception() be used instead?
						if(window["__log__"]){
							// FIXME: this logging statement needs to be handed off
							// 		  to an async logging wrapper for later pickup.
							// 		  Doing this synchronously is going to be way
							// 		  too slow.
	
							// NOTE: we explicitly ask for squelch here!
							__log__.exception(subs[i][1], e, true);
						}
					}
				}
				if(__sig__.timeCalls){
					__sig__.timingData[funcName][sl].push(new Date());
				}
				return ret;
			} catch(e) {
				
			}
				
		};
		// extend the dispatcher function object with a property indicating
		// that it's a sigslot dispatcher
		// obj[funcName].isDispatcher = true;

		// make sure that if we need cleanup, it gets done
		// if((window["__is__"])&&(window["__env__"])&&(__is__.ie)&&(funcName.toLowerCase().slice(0, 2)=="on")){
		if(funcName.toLowerCase)
			var lcfn = funcName.toLowerCase();
		if((window["__env__"])&&(lcfn.slice(0, 2)=="on")&&(lcfn.slice(0,8)!="onunload")){
			NW_attachEvent_list.push([obj, funcName, obj[funcName]]);
			NW_expando_list.push([obj, origname, obj[origname]]);
			NW_expando_props_obj.add(origname);
			NW_expando_props_obj.add(funcName);
		}

		return subs;
	}

    // aliases
	this.addBareSigByName = this.addBareSignalByName;

	/*--> 
	<methodsynopsis id="__sig__.disconnectByName">
		&public; &int;
		<methodname>disconnectByName</methodname>
		<methodparam>&obj; <parameter>sigObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>sigFuncName</parameter></methodparam>
		<methodparam>&obj; <parameter>slotObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>slotFuncName</parameter></methodparam>
	</methodsynopsis>
	<para role="methodinfo">
		Alias for <link linkend="__sig__.disconnectAllByName"><methodname>disconnectAllByName</methodname></link>.
	</para>
	<!-- FIXME: need new translation for this section -->
	<!--*/
	this.disconnectByName = this.disconnectAllByName;

	// thin wrappers

	/*--> 
	<methodsynopsis id="__sig__.disconnect">
		&public; &int;
		<methodname>disconnect</methodname>
		<methodparam>&obj; <parameter>sigObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>sigFuncName</parameter></methodparam>
		<methodparam>&obj; <parameter>slotObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>slotFuncName</parameter></methodparam>
	</methodsynopsis>
	<para role="methodinfo">
		Alias for <link linkend="__sig__.disconnectAllByName"><methodname>disconnectAllByName</methodname></link>.
	</para>
	<!-- FIXME: need new translation for this section -->
	<!--*/
    this.disconnect = function(obj, funcName, trigObj, trigFuncName) {
		if((typeof funcName != "string")||(typeof trigFuncName != "string")){ 
			throw new Error(sestr); 
		}
		return this.disconnectByName(obj, funcName, trigObj, trigFuncName, false);
	}

	/*--> 
	<methodsynopsis id="__sig__.disconnectAll">
		&public; &int;
		<methodname>disconnectAll</methodname>
		<methodparam>&obj; <parameter>sigObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>sigFuncName</parameter></methodparam>
		<methodparam>&obj; <parameter>slotObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>slotFuncName</parameter></methodparam>
	</methodsynopsis>
	<para role="methodinfo">
		Alias for <link linkend="__sig__.disconnectAllByName"><methodname>disconnectAllByName</methodname></link>.
	</para>
	<!-- FIXME: need new translation for this section -->
	<!--*/
	this.disconnectAll = this.disconnect;

	/*--> 
	<methodsynopsis id="__sig__.connect">
		&public; &void;
		<methodname>connect</methodname>
		<methodparam>&obj; <parameter>sigObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>sigFuncName</parameter></methodparam>
		<methodparam>&obj; <parameter>slotObj</parameter> <initializer>null</initializer></methodparam>
		<methodparam>&str; <parameter>slotFuncName</parameter></methodparam>
		<methodparam>&arr; <parameter>defaultArguments</parameter></methodparam>
		<methodparam>&arr; <parameter>overRideArguments</parameter></methodparam>
		<methodparam>&arr; <parameter>mutators</parameter></methodparam>
		<methodparam>&func_ptr; <parameter>finalMutator</parameter></methodparam>
	</methodsynopsis>
	<para role="methodinfo">
		Wrapper for <link
		linkend="__sig__.connectByName"><methodname>connectByName</methodname></link>
		which provides several other calling modes that
		<methodname>connectByName</methodname> does not. In addition to the
		four-argument calling convention, <methodname>connnect</methodname>
		supports a two-argument calling style in which the arguments must be
		either function pointers, function objects, or names of functions which
		currently do or should exist in the global namespace (in a browser,
		<literal>window</literal>). 
	</para>
	<note role="methodinfo">
		When the two-argument style is used with function references, &__sig__;
		is not capable of (efficiently) determining what the assigned name for
		the function is, and this may cause <emphasis>SERIOUS</emphasis> and
		<emphasis>NON OBVIOUS</emphasis> side effects. This is not an issue
		with anonymous functions, as they have no namespace attachment (other
		than, perhaps, their declaring namespace). In order to avoid this
		scenario, always pass (non anonymous) functions as strings which
		contain the function name.
	</note>
	<!-- FIXME: need new translation for this section -->
	<!--*/
    this.connect = function(obj, funcName, trigObj, trigFuncName, defaultArgs, overRideArgs, mutators, finalMutator){
		if(arguments.length<4){
			if(arguments.length == 2){
				// we can assume that we either got 2 functions or 2 function
				// names. In this case, try to offload some of the work from
				// the user.

				if(typeof funcName == "function"){
					trigObj = window;
					trigFuncName = this.setAnonFunc(funcName);
				}else if(typeof funcName == "string"){
					trigObj = window;
					trigFuncName = funcName;
				}else{
					throw new Error("invalid arguments");
				}

				if(typeof obj == "function"){
					funcName = this.setAnonFunc(obj);
					obj = window;
				}else if(typeof obj == "string"){
					funcName = obj;
					obj = window;
				}else{
					throw new Error("invalid arguments");
				}

			}else if(arguments.length == 3){
				// we got one fully qualified method. Figure out if it comes
				// first or second.
				if(typeof arguments[1] == "string"){
					// fully qualified item came first

					// FIXME: should we be trying to do for(... in ...)
					// iteration in order to determine assigned name and use
					// setAnonFunc only when that fails?

					if(typeof trigObj == "function"){
						trigFuncName = this.setAnonFunc(trigObj);
					}else{
						trigFuncName = String(trigObj);
					}
					trigObj = window;
				}else{
					// fully qualified item is second

					// shift everything over one
					trigFuncName = String(trigObj);
					trigObj = funcName;
					if(typeof obj == "function"){
						funcName = this.setAnonFunc(obj);
					}else{
						funcName = String(obj);
					}
					obj = window;
				}
			}else if(arguments.length == 1){
				return this.kwConnect(arguments[0]);
			}
		}else if((typeof funcName != "string")||(typeof trigFuncName != "string")){ 
			throw new Error(sestr); 
		}
		return this.connectByName(obj, funcName, trigObj, trigFuncName, false, defaultArgs, overRideArgs, mutators, finalMutator);
	}

	/*--> 
	<methodsynopsis id="__sig__.kwConnect">
		&public; &bool;
		<methodname>kwConnect</methodname>
		<methodparam>&obj; <parameter>keywordArguments</parameter></methodparam>
	</methodsynopsis>
	<para role="methodinfo">
	</para>
	<!-- FIXME: need new translation for this section -->
	<!--*/
	this.kwConnect = function(ka){
		return this.connectByName(	(ka["signalObj"]||ka["signalObject"]||window), ka.signalName, 
									(ka["slotObj"]||ka["slotObject"]||window), ka.slotName, 
									ka["once"], ka["defaults"], ka["overRides"], 
									ka["mutators"], (ka["finalMutator"]||ka["mutator"]));
	}
}

/*--> 
		</sect3>
		<!-- FIXME: need to sync up this section with updated english Examples below. -->
		<sect3 id="__sig__.examples" lang="es">
			<title>Ejemplos</title>
			<para>
			El mecanismo de eventos de se&ntilde;ales/rastros proporcionado por
			&nw; es una de las diferenciaciones nucleares entre &nw; y
			cualquier otra cosa. Esto no quiere decir que el mecanismo de
			eventos se&ntilde;ales/rastros pueda ser empleado s&oacute;lamente
			con &nw; o, incluso, s&oacute;lamente con DHTML. La clase &__sig__;
			definida en <filename>sigslot_core.js</filename> puede ser empleada
			independientemente de &nw; y deber&iacute;a ser portable a
			cualquier entorno moderno de JavaScript.
			</para>
			<para>
			La implementaci&oacute;n de se&ntilde;ales/rastros expuesta por el
			objeto &__sig__; intenta proporcionar una interfaz clara y simple
			para el manejo abstracto de eventos.
			</para>
			<sect4>
				<title>Uso com&uacute;n</title>
				<para>
					El escenario de uso m&aacute;s com&uacute;n para "Signals
					and Slots" se encuentra en la respuesta a las acciones del
					usuario. En un entorno DHTML, consideremos el caso en el
					que queremos ser informados de un click del mouse en un
					elemento en particular. Dado el actual estado de
					incompatibilidades navegadores relativas al manejo de
					eventos, fijar m&aacute;s de un escuchador en un nodo dado
					requiere al menos dar varios rodeos, o que todos los
					potenciales escuchadores se regsitren a s&iacute; mismos
					mediante un mecanismo personalizado de llamadas
					atr&aacute;s. Aqu&iacute; est&aacute; el aspecto que
					tendr&iacute;a empleando Se&ntilde;ales y Signals and
					Rastros en su lugar:
				</para>
<programlisting><comment>// asumimos un nodo en el documento con id "example"</comment>
var domNode = document.getElementById("example");

function firstListener(){
  alert("first");
}

function secondListener(){
  alert("second");
}

<comment>// agregar un escuchador no es dif&iacute;cil</comment>
__sig__.connectByName(domNode, "onclick", null, "firstListener");
<comment>// y no como en otros sistemas, tampoco lo es el segundo</comment>
__sig__.connectByName(domNode, "onclick", null, "secondListener");</programlisting>
				<para>
					Cuando se hace click sobre el nodo del documento con id
					"example", dos cajas de alerta van a ser creadas, en el
					orden en el que las funciones fueron a&ntilde;adidas. No se
					requiere ning&uacute;n trabajo expl&iacute;cito para
					solucionar inconsistencias espec&iacute;ficas de los
					navegadores debidas al manejo de eventos del DOM. Este
					empleo es muy com&uacute;n.
				</para>
				<note>
					La aridez de los m&eacute;todos conectados presenta
					actualmente una controversia com&uacute;n cuando se usa la
					librer&iacute;a sigslot de &nw;. Ten en cuenta que los
					Rastros deben tener estelas que requieran <emphasis>un
					n&uacute;mero igual o menor de argumentos</emphasis> que la
					Se&ntilde;al a al que son agregados. Todos los argumentos
					pasados al m&eacute;todo Se&ntilde;al vana ser pasados a
					cada uno de sus rastros "tal cual", por tanto, si un Rastro
					requiere m&aacute;s argumentos que la se&ntilde;al que
					est&aacute; escuchando, La llamada al Rastro
					<emphasis>fallar&aacute;</emphasis>.
				</note>
				<para>
					Tambi&eacute;n es posible llamar juntas a funciones de
					cadena empleando se&ntilde;ales and rastros. El siguiente
					fragmento define una cadena simple:
				</para>
<programlisting>function eventRoot(arg){
  return true;
}

function listener1(arg){
  alert("first: "+arg);
}

function listener2(arg){
  alert("second:"+arg);
}

__sig__.connectByName(null, "eventRoot", null, "listener1");
__sig__.connectByName(null, "listener1", null, "listener2");

eventRoot("hello world!");</programlisting>
				<para>
					El ejemplo anterior crear&aacute; dos ventanas de alerta, con
					<function>listener1</function> y
					<function>listener2</function> que ser&aacute;n llamados en orden.
				</para>
				<para>
					Desconectar m&eacute;todos es tan simple como conectarlos.
					Consideremos el siguiente ejemplo (basado en el
					anterior):
				</para>
<programlisting>function eventRoot(arg){
  return true;
}

function listener1(arg){
  alert("first: "+arg);
}

function listener2(arg){
  alert("second:"+arg);
}

__sig__.connectByName(null, "eventRoot", null, "listener1");
__sig__.connectByName(null, "listener1", null, "listener2");

<comment>// esto crear&aacute; dos cajas de alerta</comment>
eventRoot("hello world!");

__sig__.disconnectOnceByName(null, "eventRoot", null, "listener1");

<comment>// no se crean cajas de alerta!</comment>
eventRoot("hello world!");

<comment>// pero al conexi&oacute;n entre listener1 y listener2
// todav&iacute;a es v&aacute;lida, lo que significa que 2 alertas se van
// a crear aqu&iacute;:</comment>
listener1("hello world!");</programlisting>
				<note>
					El m&eacute;todo
					&__sig__;.<link
					linkend="__sig__.disconnectOnceByName"><methodname>disconnectOnceByName</methodname></link>
					s&oacute;lo elimina la primera conexi&oacute;n que
					encuentra. Para eliminar todas las conexiones entre
					funciones o m&eacute;todos, usa &__sig__;.<link
					linkend="__sig__.disconnectAllByName"><methodname>disconnectAllByName</methodname></link>
					en su lugar.
				</note>
			</sect4>
		</sect3>
		<sect3 id="__sig__.examples" lang="en">
			<title>Examples</title>
			<para>
			The &sigslot; event mechanism provided by &nw; is one of its core
			differentiators between &nw; and everything else. This is not to
			say that the &sigslot; event mechanism can only be used with &nw;
			or, indeed, only with DHTML. The &__sig__; class defined in
			<filename>sigslot_core.js</filename> can be used independently of
			&nw; and should be portable to any modern JavaScript environment.
			</para>
			<para>
			The &sigslot; implementation exposed by the &__sig__; object
			attempts to provide a simple and clean interface for abstracted
			event handling. 
			</para>
			<sect4>
				<title>Common Usage</title>
				<para>
				The most common usage scenario for &sigslot; is in response to
				user input or events. In a DHTML environment, consider the case
				where we want to be informed of a mouse click on an particular
				element. Given the current state of browser incompatability
				regarding event handling, setting more than one listener on any
				given node either requires jumping through large hoops, or
				requiring that all potential listeners register themselves
				through a custom callback system. Here's how it would look
				using &sigslot; instead:
				</para>
<programlisting><comment>// assume a node in the document with the id "example"</comment>
var domNode = document.getElementById("example");

function firstListener(){
  alert("first");
}

function secondListener(){
  alert("second");
}

<comment>// attaching one listener isn't difficult</comment>
__sig__.connectByName(domNode, "onclick", null, "firstListener");
<comment>// and unlike most other systems, neither is the second</comment>
__sig__.connectByName(domNode, "onclick", null, "secondListener");</programlisting>
				<para>
				When the node in the document with the id "example" is then
				clicked on, two alert boxes will be created, in the order the
				functions were attached. No explicit work was required to hack
				around browser-specific inconsistencies regarding DOM node
				event handling. This use is quite common.
				</para>
				<note>
				Arity of the connected methods currently presents a common
				"gotcha" when using the &nw; &sigslot; library. Please note
				that Slots must have signatures requiring <emphasis>an equal or
				lesser number of arguments</emphasis> than the Signal to which
				they are attached. All arguments passed to the Signal method
				will be passed to each of it's Slots "as is", so should a Slot
				require more arguments than the Signal it is listening to, the
				call to the Slot <emphasis>will fail</emphasis>.
				</note>
				<para>
				It is also possible to chain function calls togeather using
				&sigslot;. The following snippet defines a simple chain:
				</para>
<programlisting>function eventRoot(arg){
  return true;
}

function listener1(arg){
  alert("first: "+arg);
}

function listener2(arg){
  alert("second:"+arg);
}

__sig__.connectByName(null, "eventRoot", null, "listener1");
__sig__.connectByName(null, "listener1", null, "listener2");

eventRoot("hello world!");</programlisting>
				<para>
					The above example will create two alert boxes, with
					<function>listener1</function> and
					<function>listener2</function> being called in order.
				</para>
				<para>
					Disconnectiong methods is as simple as connecting them.
					Consider the following example (based on the previous
					example):
				</para>
<programlisting>function eventRoot(arg){
  return true;
}

function listener1(arg){
  alert("first: "+arg);
}

function listener2(arg){
  alert("second:"+arg);
}

__sig__.connectByName(null, "eventRoot", null, "listener1");
__sig__.connectByName(null, "listener1", null, "listener2");

<comment>// this will create two alert boxes</comment>
eventRoot("hello world!");

__sig__.disconnectOnceByName(null, "eventRoot", null, "listener1");

<comment>// no alertboxes created!</comment>
eventRoot("hello world!");

<comment>// but the connection between listener1 and listener2 
// is still valid, meaning that 2 alerts will 
// be created here:</comment>
listener1("hello world!");</programlisting>
				<note>
				The method &__sig__;.<methodname>disconnectByName</methodname>
				only removes the first connection found. To remove all
				connections between functions or methods, use
				&__sig__;.<methodname>disconnectAllByName</methodname> instead.
				</note>
			</sect4>
		</sect3>
<!--*/
try{ // try block necessary for CLI usage
	// if not a standalone file, register that we are providing this functionality
	if(window["__scripts__"]){
		__scripts__.finalize(__config__.corePath+"sigslot_core.js");
	}
}catch(e){ }

/*-->
	</sect2>
</sect1>
<!-- */ // -->