Subversion Repositories Applications.papyrus

if(!dojo._hasResource["dijit._Widget"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code.

dojo._hasResource["dijit._Widget"] = true;

dojo.provide("dijit._Widget");

dojo.require("dijit._base");

dojo.declare("dijit._Widget", null, {

	// summary:

	//		The foundation of dijit widgets.

	//

	// id: String

	//		a unique, opaque ID string that can be assigned by users or by the

	//		system. If the developer passes an ID which is known not to be

	//		unique, the specified ID is ignored and the system-generated ID is

	//		used instead.

	id: "",

	// lang: String

	//	Language to display this widget in (like en-us).

	//	Defaults to brower's specified preferred language (typically the language of the OS)

	lang: "",

	// dir: String

	//  Bi-directional support, as defined by the HTML DIR attribute. Either left-to-right "ltr" or right-to-left "rtl".

	dir: "",

	// class: String

	// HTML class attribute

	"class": "",

	// style: String

	// HTML style attribute

	style: "",

	// title: String

	// HTML title attribute

	title: "",

	// srcNodeRef: DomNode

	//		pointer to original dom node

	srcNodeRef: null,

	// domNode: DomNode

	//		this is our visible representation of the widget! Other DOM

	//		Nodes may by assigned to other properties, usually through the

	//		template system's dojoAttachPonit syntax, but the domNode

	//		property is the canonical "top level" node in widget UI.

	domNode: null,

	// attributeMap: Object

	//		A map of attributes and attachpoints -- typically standard HTML attributes -- to set

	//		on the widget's dom, at the "domNode" attach point, by default.

	//		Other node references can be specified as properties of 'this'

	attributeMap: {id:"", dir:"", lang:"", "class":"", style:"", title:""},  // TODO: add on* handlers?

	//////////// INITIALIZATION METHODS ///////////////////////////////////////

	postscript: function(params, srcNodeRef){

		this.create(params, srcNodeRef);

	},

	create: function(params, srcNodeRef){

		// summary:

		//		To understand the process by which widgets are instantiated, it

		//		is critical to understand what other methods create calls and

		//		which of them you'll want to override. Of course, adventurous

		//		developers could override create entirely, but this should

		//		only be done as a last resort.

		//

		//		Below is a list of the methods that are called, in the order

		//		they are fired, along with notes about what they do and if/when

		//		you should over-ride them in your widget:

		//

		//			postMixInProperties:

		//				a stub function that you can over-ride to modify

		//				variables that may have been naively assigned by

		//				mixInProperties

		//			# widget is added to manager object here

		//			buildRendering

		//				Subclasses use this method to handle all UI initialization

		//				Sets this.domNode.  Templated widgets do this automatically

		//				and otherwise it just uses the source dom node.

		//			postCreate

		//				a stub function that you can over-ride to modify take

		//				actions once the widget has been placed in the UI

		// store pointer to original dom tree

		this.srcNodeRef = dojo.byId(srcNodeRef);

		// For garbage collection.  An array of handles returned by Widget.connect()

		// Each handle returned from Widget.connect() is an array of handles from dojo.connect()

		this._connects=[];

		// _attaches: String[]

		// 		names of all our dojoAttachPoint variables

		this._attaches=[];

		//mixin our passed parameters

		if(this.srcNodeRef && (typeof this.srcNodeRef.id == "string")){ this.id = this.srcNodeRef.id; }

		if(params){

			dojo.mixin(this,params);

		}

		this.postMixInProperties();

		// generate an id for the widget if one wasn't specified

		// (be sure to do this before buildRendering() because that function might

		// expect the id to be there.

		if(!this.id){

			this.id=dijit.getUniqueId(this.declaredClass.replace(/\./g,"_"));

		}

		dijit.registry.add(this);

		this.buildRendering();

		// Copy attributes listed in attributeMap into the [newly created] DOM for the widget.

		// The placement of these attributes is according to the property mapping in attributeMap.

		// Note special handling for 'style' and 'class' attributes which are lists and can

		// have elements from both old and new structures, and some attributes like "type"

		// cannot be processed this way as they are not mutable.

		if(this.domNode){

			for(var attr in this.attributeMap){

				var mapNode = this[this.attributeMap[attr] || "domNode"];

				var value = this[attr];

				if(typeof value != "object" && (value !== "" || (params && params[attr]))){

					switch(attr){

					case "class":

						dojo.addClass(mapNode, value);

						break;

					case "style":

						if(mapNode.style.cssText){

							mapNode.style.cssText += "; " + value;// FIXME: Opera

						}else{

							mapNode.style.cssText = value;

						}

						break;

					default:

						mapNode.setAttribute(attr, value);

					}

				}

			}

		}

		if(this.domNode){

			this.domNode.setAttribute("widgetId", this.id);

		}

		this.postCreate();

		// If srcNodeRef has been processed and removed from the DOM (e.g. TemplatedWidget) then delete it to allow GC.

		if(this.srcNodeRef && !this.srcNodeRef.parentNode){

			delete this.srcNodeRef;

		}

	},

	postMixInProperties: function(){

		// summary

		//	Called after the parameters to the widget have been read-in,

		//	but before the widget template is instantiated.

		//	Especially useful to set properties that are referenced in the widget template.

	},

	buildRendering: function(){

		// summary:

		//		Construct the UI for this widget, setting this.domNode.

		//		Most widgets will mixin TemplatedWidget, which overrides this method.

		this.domNode = this.srcNodeRef || dojo.doc.createElement('div');

	},

	postCreate: function(){

		// summary:

		//		Called after a widget's dom has been setup

	},

	startup: function(){

		// summary:

		//		Called after a widget's children, and other widgets on the page, have been created.

		//		Provides an opportunity to manipulate any children before they are displayed

		//		This is useful for composite widgets that need to control or layout sub-widgets

		//		Many layout widgets can use this as a wiring phase

	},

	//////////// DESTROY FUNCTIONS ////////////////////////////////

	destroyRecursive: function(/*Boolean*/ finalize){

		// summary:

		// 		Destroy this widget and it's descendants. This is the generic

		// 		"destructor" function that all widget users should call to

		// 		cleanly discard with a widget. Once a widget is destroyed, it's

		// 		removed from the manager object.

		// finalize: Boolean

		//		is this function being called part of global environment

		//		tear-down?

		this.destroyDescendants();

		this.destroy();

	},

	destroy: function(/*Boolean*/ finalize){

		// summary:

		// 		Destroy this widget, but not its descendants

		// finalize: Boolean

		//		is this function being called part of global environment

		//		tear-down?

		this.uninitialize();

		dojo.forEach(this._connects, function(array){

			dojo.forEach(array, dojo.disconnect);

		});

		this.destroyRendering(finalize);

		dijit.registry.remove(this.id);

	},

	destroyRendering: function(/*Boolean*/ finalize){

		// summary:

		//		Destroys the DOM nodes associated with this widget

		// finalize: Boolean

		//		is this function being called part of global environment

		//		tear-down?

		if(this.bgIframe){

			this.bgIframe.destroy();

			delete this.bgIframe;

		}

		if(this.domNode){

			dojo._destroyElement(this.domNode);

			delete this.domNode;

		}

		if(this.srcNodeRef){

			dojo._destroyElement(this.srcNodeRef);

			delete this.srcNodeRef;

		}

	},

	destroyDescendants: function(){

		// summary:

		//		Recursively destroy the children of this widget and their

		//		descendants.

		// TODO: should I destroy in the reverse order, to go bottom up?

		dojo.forEach(this.getDescendants(), function(widget){ widget.destroy(); });

	},

	uninitialize: function(){

		// summary:

		//		stub function. Over-ride to implement custom widget tear-down

		//		behavior.

		return false;

	},

	////////////////// MISCELLANEOUS METHODS ///////////////////

	toString: function(){

		// summary:

		//		returns a string that represents the widget. When a widget is

		//		cast to a string, this method will be used to generate the

		//		output. Currently, it does not implement any sort of reversable

		//		serialization.

		return '[Widget ' + this.declaredClass + ', ' + (this.id || 'NO ID') + ']'; // String

	},

	getDescendants: function(){

		// summary:

		//	return all the descendant widgets

		var list = dojo.query('[widgetId]', this.domNode);

		return list.map(dijit.byNode);		// Array

	},

	nodesWithKeyClick : ["input", "button"],

	connect: function(

			/*Object|null*/ obj,

			/*String*/ event,

			/*String|Function*/ method){

		// summary:

		//		Connects specified obj/event to specified method of this object

		//		and registers for disconnect() on widget destroy.

		//		Special event: "ondijitclick" triggers on a click or enter-down or space-up

		//		Similar to dojo.connect() but takes three arguments rather than four.

		var handles =[];

		if(event == "ondijitclick"){

			var w = this;

			// add key based click activation for unsupported nodes.

			if(!this.nodesWithKeyClick[obj.nodeName]){

				handles.push(dojo.connect(obj, "onkeydown", this,

					function(e){

						if(e.keyCode == dojo.keys.ENTER){

							return (dojo.isString(method))?

								w[method](e) : method.call(w, e);

						}else if(e.keyCode == dojo.keys.SPACE){

							// stop space down as it causes IE to scroll

							// the browser window

							dojo.stopEvent(e);

						}

			 		}));

				handles.push(dojo.connect(obj, "onkeyup", this,

					function(e){

						if(e.keyCode == dojo.keys.SPACE){

							return dojo.isString(method) ?

								w[method](e) : method.call(w, e);

						}

			 		}));

			}

			event = "onclick";

		}

		handles.push(dojo.connect(obj, event, this, method));

		// return handles for FormElement and ComboBox

		this._connects.push(handles);

		return handles;

	},

	disconnect: function(/*Object*/ handles){

		// summary:

		//		Disconnects handle created by this.connect.

		//		Also removes handle from this widget's list of connects

		for(var i=0; i<this._connects.length; i++){

			if(this._connects[i]==handles){

				dojo.forEach(handles, dojo.disconnect);

				this._connects.splice(i, 1);

				return;

			}

		}

	},

	isLeftToRight: function(){

		// summary:

		//		Checks the DOM to for the text direction for bi-directional support

		// description:

		//		This method cannot be used during widget construction because the widget

		//		must first be connected to the DOM tree.  Parent nodes are searched for the

		//		'dir' attribute until one is found, otherwise left to right mode is assumed.

		//		See HTML spec, DIR attribute for more information.

		if(typeof this._ltr == "undefined"){

			this._ltr = dojo.getComputedStyle(this.domNode).direction != "rtl";

		}

		return this._ltr; //Boolean

	},

	isFocusable: function(){

		// summary:

		//		Return true if this widget can currently be focused

		//		and false if not

		return this.focus && (dojo.style(this.domNode, "display") != "none");

	}

});

}