source: Dev/branches/rest-dojo-ui/client/dijit/_WidgetBase.js @ 256

define([
        "require",                      // require.toUrl
        "dojo/_base/array", // array.forEach array.map
        "dojo/aspect",
        "dojo/_base/config", // config.blankGif
        "dojo/_base/connect", // connect.connect
        "dojo/_base/declare", // declare
        "dojo/dom", // dom.byId
        "dojo/dom-attr", // domAttr.set domAttr.remove
        "dojo/dom-class", // domClass.add domClass.replace
        "dojo/dom-construct", // domConstruct.create domConstruct.destroy domConstruct.place
        "dojo/dom-geometry",    // isBodyLtr
        "dojo/dom-style", // domStyle.set, domStyle.get
        "dojo/_base/kernel",
        "dojo/_base/lang", // mixin(), isArray(), etc.
        "dojo/on",
        "dojo/ready",
        "dojo/Stateful", // Stateful
        "dojo/topic",
        "dojo/_base/window", // win.doc.createTextNode
        "./registry"    // registry.getUniqueId(), registry.findWidgets()
], function(require, array, aspect, config, connect, declare,
                        dom, domAttr, domClass, domConstruct, domGeometry, domStyle, kernel,
                        lang, on, ready, Stateful, topic, win, registry){

/*=====
var Stateful = dojo.Stateful;
=====*/

// module:
//              dijit/_WidgetBase
// summary:
//              Future base class for all Dijit widgets.

// For back-compat, remove in 2.0.
if(!kernel.isAsync){
        ready(0, function(){
                var requires = ["dijit/_base/manager"];
                require(requires);      // use indirection so modules not rolled into a build
        });
}

// Nested hash listing attributes for each tag, all strings in lowercase.
// ex: {"div": {"style": true, "tabindex" true}, "form": { ...
var tagAttrs = {};
function getAttrs(obj){
        var ret = {};
        for(var attr in obj){
                ret[attr.toLowerCase()] = true;
        }
        return ret;
}

function nonEmptyAttrToDom(attr){
        // summary:
        //              Returns a setter function that copies the attribute to this.domNode,
        //              or removes the attribute from this.domNode, depending on whether the
        //              value is defined or not.
        return function(val){
                domAttr[val ? "set" : "remove"](this.domNode, attr, val);
                this._set(attr, val);
        };
}

return declare("dijit._WidgetBase", Stateful, {
        // summary:
        //              Future base class for all Dijit widgets.
        // description:
        //              Future base class for all Dijit widgets.
        //              _Widget extends this class adding support for various features needed by desktop.
        //
        //              Provides stubs for widget lifecycle methods for subclasses to extend, like postMixInProperties(), buildRendering(),
        //              postCreate(), startup(), and destroy(), and also public API methods like set(), get(), and watch().
        //
        //              Widgets can provide custom setters/getters for widget attributes, which are called automatically by set(name, value).
        //              For an attribute XXX, define methods _setXXXAttr() and/or _getXXXAttr().
        //
        //              _setXXXAttr can also be a string/hash/array mapping from a widget attribute XXX to the widget's DOMNodes:
        //
        //              - DOM node attribute
        // |            _setFocusAttr: {node: "focusNode", type: "attribute"}
        // |            _setFocusAttr: "focusNode"      (shorthand)
        // |            _setFocusAttr: ""               (shorthand, maps to this.domNode)
        //              Maps this.focus to this.focusNode.focus, or (last example) this.domNode.focus
        //
        //              - DOM node innerHTML
        //      |               _setTitleAttr: { node: "titleNode", type: "innerHTML" }
        //              Maps this.title to this.titleNode.innerHTML
        //
        //              - DOM node innerText
        //      |               _setTitleAttr: { node: "titleNode", type: "innerText" }
        //              Maps this.title to this.titleNode.innerText
        //
        //              - DOM node CSS class
        // |            _setMyClassAttr: { node: "domNode", type: "class" }
        //              Maps this.myClass to this.domNode.className
        //
        //              If the value of _setXXXAttr is an array, then each element in the array matches one of the
        //              formats of the above list.
        //
        //              If the custom setter is null, no action is performed other than saving the new value
        //              in the widget (in this).
        //
        //              If no custom setter is defined for an attribute, then it will be copied
        //              to this.focusNode (if the widget defines a focusNode), or this.domNode otherwise.
        //              That's only done though for attributes that match DOMNode attributes (title,
        //              alt, aria-labelledby, etc.)

        // id: [const] 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: "",
        _setIdAttr: "domNode",  // to copy to this.domNode even for auto-generated id's

        // lang: [const] String
        //              Rarely used.  Overrides the default Dojo locale used to render this widget,
        //              as defined by the [HTML LANG](http://www.w3.org/TR/html401/struct/dirlang.html#adef-lang) attribute.
        //              Value must be among the list of locales specified during by the Dojo bootstrap,
        //              formatted according to [RFC 3066](http://www.ietf.org/rfc/rfc3066.txt) (like en-us).
        lang: "",
        // set on domNode even when there's a focus node.   but don't set lang="", since that's invalid.
        _setLangAttr: nonEmptyAttrToDom("lang"),

        // dir: [const] String
        //              Bi-directional support, as defined by the [HTML DIR](http://www.w3.org/TR/html401/struct/dirlang.html#adef-dir)
        //              attribute. Either left-to-right "ltr" or right-to-left "rtl".  If undefined, widgets renders in page's
        //              default direction.
        dir: "",
        // set on domNode even when there's a focus node.   but don't set dir="", since that's invalid.
        _setDirAttr: nonEmptyAttrToDom("dir"),  // to set on domNode even when there's a focus node

        // textDir: String
        //              Bi-directional support, the main variable which is responsible for the direction of the text.
        //              The text direction can be different than the GUI direction by using this parameter in creation
        //              of a widget.
        //              Allowed values:
        //                      1. "ltr"
        //                      2. "rtl"
        //                      3. "auto" - contextual the direction of a text defined by first strong letter.
        //              By default is as the page direction.
        textDir: "",

        // class: String
        //              HTML class attribute
        "class": "",
        _setClassAttr: { node: "domNode", type: "class" },

        // style: String||Object
        //              HTML style attributes as cssText string or name/value hash
        style: "",

        // title: String
        //              HTML title attribute.
        //
        //              For form widgets this specifies a tooltip to display when hovering over
        //              the widget (just like the native HTML title attribute).
        //
        //              For TitlePane or for when this widget is a child of a TabContainer, AccordionContainer,
        //              etc., it's used to specify the tab label, accordion pane title, etc.
        title: "",

        // tooltip: String
        //              When this widget's title attribute is used to for a tab label, accordion pane title, etc.,
        //              this specifies the tooltip to appear when the mouse is hovered over that text.
        tooltip: "",

        // baseClass: [protected] String
        //              Root CSS class of the widget (ex: dijitTextBox), used to construct CSS classes to indicate
        //              widget state.
        baseClass: "",

        // srcNodeRef: [readonly] DomNode
        //              pointer to original DOM node
        srcNodeRef: null,

        // domNode: [readonly] DomNode
        //              This is our visible representation of the widget! Other DOM
        //              Nodes may by assigned to other properties, usually through the
        //              template system's data-dojo-attach-point syntax, but the domNode
        //              property is the canonical "top level" node in widget UI.
        domNode: null,

        // containerNode: [readonly] DomNode
        //              Designates where children of the source DOM node will be placed.
        //              "Children" in this case refers to both DOM nodes and widgets.
        //              For example, for myWidget:
        //
        //              |       <div data-dojo-type=myWidget>
        //              |               <b> here's a plain DOM node
        //              |               <span data-dojo-type=subWidget>and a widget</span>
        //              |               <i> and another plain DOM node </i>
        //              |       </div>
        //
        //              containerNode would point to:
        //
        //              |               <b> here's a plain DOM node
        //              |               <span data-dojo-type=subWidget>and a widget</span>
        //              |               <i> and another plain DOM node </i>
        //
        //              In templated widgets, "containerNode" is set via a
        //              data-dojo-attach-point assignment.
        //
        //              containerNode must be defined for any widget that accepts innerHTML
        //              (like ContentPane or BorderContainer or even Button), and conversely
        //              is null for widgets that don't, like TextBox.
        containerNode: null,

/*=====
        // _started: Boolean
        //              startup() has completed.
        _started: false,
=====*/

        // attributeMap: [protected] Object
        //              Deprecated.   Instead of attributeMap, widget should have a _setXXXAttr attribute
        //              for each XXX attribute to be mapped to the DOM.
        //
        //              attributeMap sets up a "binding" between attributes (aka properties)
        //              of the widget and the widget's DOM.
        //              Changes to widget attributes listed in attributeMap will be
        //              reflected into the DOM.
        //
        //              For example, calling set('title', 'hello')
        //              on a TitlePane will automatically cause the TitlePane's DOM to update
        //              with the new title.
        //
        //              attributeMap is a hash where the key is an attribute of the widget,
        //              and the value reflects a binding to a:
        //
        //              - DOM node attribute
        // |            focus: {node: "focusNode", type: "attribute"}
        //              Maps this.focus to this.focusNode.focus
        //
        //              - DOM node innerHTML
        //      |               title: { node: "titleNode", type: "innerHTML" }
        //              Maps this.title to this.titleNode.innerHTML
        //
        //              - DOM node innerText
        //      |               title: { node: "titleNode", type: "innerText" }
        //              Maps this.title to this.titleNode.innerText
        //
        //              - DOM node CSS class
        // |            myClass: { node: "domNode", type: "class" }
        //              Maps this.myClass to this.domNode.className
        //
        //              If the value is an array, then each element in the array matches one of the
        //              formats of the above list.
        //
        //              There are also some shorthands for backwards compatibility:
        //              - string --> { node: string, type: "attribute" }, for example:
        //      |       "focusNode" ---> { node: "focusNode", type: "attribute" }
        //              - "" --> { node: "domNode", type: "attribute" }
        attributeMap: {},

        // _blankGif: [protected] String
        //              Path to a blank 1x1 image.
        //              Used by <img> nodes in templates that really get their image via CSS background-image.
        _blankGif: config.blankGif || require.toUrl("dojo/resources/blank.gif"),

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

        postscript: function(/*Object?*/params, /*DomNode|String*/srcNodeRef){
                // summary:
                //              Kicks off widget instantiation.  See create() for details.
                // tags:
                //              private
                this.create(params, srcNodeRef);
        },

        create: function(/*Object?*/params, /*DomNode|String?*/srcNodeRef){
                // summary:
                //              Kick off the life-cycle of a widget
                // params:
                //              Hash of initialization parameters for widget, including
                //              scalar values (like title, duration etc.) and functions,
                //              typically callbacks like onClick.
                // srcNodeRef:
                //              If a srcNodeRef (DOM node) is specified:
                //                      - use srcNodeRef.innerHTML as my contents
                //                      - if this is a behavioral widget then apply behavior
                //                        to that srcNodeRef
                //                      - otherwise, replace srcNodeRef with my generated DOM
                //                        tree
                // description:
                //              Create calls a number of widget methods (postMixInProperties, buildRendering, postCreate,
                //              etc.), some of which of you'll want to override. See http://dojotoolkit.org/reference-guide/dijit/_WidgetBase.html
                //              for a discussion of the widget creation lifecycle.
                //
                //              Of course, adventurous developers could override create entirely, but this should
                //              only be done as a last resort.
                // tags:
                //              private

                // store pointer to original DOM tree
                this.srcNodeRef = dom.byId(srcNodeRef);

                // For garbage collection.  An array of listener handles returned by this.connect() / this.subscribe()
                this._connects = [];

                // For widgets internal to this widget, invisible to calling code
                this._supportingWidgets = [];

                // this is here for back-compat, remove in 2.0 (but check NodeList-instantiate.html test)
                if(this.srcNodeRef && (typeof this.srcNodeRef.id == "string")){ this.id = this.srcNodeRef.id; }

                // mix in our passed parameters
                if(params){
                        this.params = params;
                        lang.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 = registry.getUniqueId(this.declaredClass.replace(/\./g,"_"));
                }
                registry.add(this);

                this.buildRendering();

                if(this.domNode){
                        // Copy attributes listed in attributeMap into the [newly created] DOM for the widget.
                        // Also calls custom setters for all attributes with custom setters.
                        this._applyAttributes();

                        // If srcNodeRef was specified, then swap out original srcNode for this widget's DOM tree.
                        // For 2.0, move this after postCreate().  postCreate() shouldn't depend on the
                        // widget being attached to the DOM since it isn't when a widget is created programmatically like
                        // new MyWidget({}).   See #11635.
                        var source = this.srcNodeRef;
                        if(source && source.parentNode && this.domNode !== source){
                                source.parentNode.replaceChild(this.domNode, source);
                        }
                }

                if(this.domNode){
                        // Note: for 2.0 may want to rename widgetId to dojo._scopeName + "_widgetId",
                        // assuming that dojo._scopeName even exists in 2.0
                        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;
                }

                this._created = true;
        },

        _applyAttributes: function(){
                // summary:
                //              Step during widget creation to copy  widget attributes to the
                //              DOM according to attributeMap and _setXXXAttr objects, and also to call
                //              custom _setXXXAttr() methods.
                //
                //              Skips over blank/false attribute values, unless they were explicitly specified
                //              as parameters to the widget, since those are the default anyway,
                //              and setting tabIndex="" is different than not setting tabIndex at all.
                //
                //              For backwards-compatibility reasons attributeMap overrides _setXXXAttr when
                //              _setXXXAttr is a hash/string/array, but _setXXXAttr as a functions override attributeMap.
                // tags:
                //              private

                // Get list of attributes where this.set(name, value) will do something beyond
                // setting this[name] = value.  Specifically, attributes that have:
                //              - associated _setXXXAttr() method/hash/string/array
                //              - entries in attributeMap.
                var ctor = this.constructor,
                        list = ctor._setterAttrs;
                if(!list){
                        list = (ctor._setterAttrs = []);
                        for(var attr in this.attributeMap){
                                list.push(attr);
                        }

                        var proto = ctor.prototype;
                        for(var fxName in proto){
                                if(fxName in this.attributeMap){ continue; }
                                var setterName = "_set" + fxName.replace(/^[a-z]|-[a-zA-Z]/g, function(c){ return c.charAt(c.length-1).toUpperCase(); }) + "Attr";
                                if(setterName in proto){
                                        list.push(fxName);
                                }
                        }
                }

                // Call this.set() for each attribute that was either specified as parameter to constructor,
                // or was found above and has a default non-null value.   For correlated attributes like value and displayedValue, the one
                // specified as a parameter should take precedence, so apply attributes in this.params last.
                // Particularly important for new DateTextBox({displayedValue: ...}) since DateTextBox's default value is
                // NaN and thus is not ignored like a default value of "".
                array.forEach(list, function(attr){
                        if(this.params && attr in this.params){
                                // skip this one, do it below
                        }else if(this[attr]){
                                this.set(attr, this[attr]);
                        }
                }, this);
                for(var param in this.params){
                        this.set(param, this[param]);
                }
        },

        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.
                // tags:
                //              protected
        },

        buildRendering: function(){
                // summary:
                //              Construct the UI for this widget, setting this.domNode.
                //              Most widgets will mixin `dijit._TemplatedMixin`, which implements this method.
                // tags:
                //              protected

                if(!this.domNode){
                        // Create root node if it wasn't created by _Templated
                        this.domNode = this.srcNodeRef || domConstruct.create('div');
                }

                // baseClass is a single class name or occasionally a space-separated list of names.
                // Add those classes to the DOMNode.  If RTL mode then also add with Rtl suffix.
                // TODO: make baseClass custom setter
                if(this.baseClass){
                        var classes = this.baseClass.split(" ");
                        if(!this.isLeftToRight()){
                                classes = classes.concat( array.map(classes, function(name){ return name+"Rtl"; }));
                        }
                        domClass.add(this.domNode, classes);
                }
        },

        postCreate: function(){
                // summary:
                //              Processing after the DOM fragment is created
                // description:
                //              Called after the DOM fragment has been created, but not necessarily
                //              added to the document.  Do not include any operations which rely on
                //              node dimensions or placement.
                // tags:
                //              protected
        },

        startup: function(){
                // summary:
                //              Processing after the DOM fragment is added to the document
                // description:
                //              Called after a widget and its children have been created and added to the page,
                //              and all related widgets have finished their create() cycle, up through postCreate().
                //              This is useful for composite widgets that need to control or layout sub-widgets.
                //              Many layout widgets can use this as a wiring phase.
                if(this._started){ return; }
                this._started = true;
                array.forEach(this.getChildren(), function(obj){
                        if(!obj._started && !obj._destroyed && lang.isFunction(obj.startup)){
                                obj.startup();
                                obj._started = true;
                        }
                });
        },

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

        destroyRecursive: function(/*Boolean?*/ preserveDom){
                // summary:
                //              Destroy this widget and its descendants
                // description:
                //              This is the generic "destructor" function that all widget users
                //              should call to cleanly discard with a widget. Once a widget is
                //              destroyed, it is removed from the manager object.
                // preserveDom:
                //              If true, this method will leave the original DOM structure
                //              alone of descendant Widgets. Note: This will NOT work with
                //              dijit._Templated widgets.

                this._beingDestroyed = true;
                this.destroyDescendants(preserveDom);
                this.destroy(preserveDom);
        },

        destroy: function(/*Boolean*/ preserveDom){
                // summary:
                //              Destroy this widget, but not its descendants.
                //              This method will, however, destroy internal widgets such as those used within a template.
                // preserveDom: Boolean
                //              If true, this method will leave the original DOM structure alone.
                //              Note: This will not yet work with _Templated widgets

                this._beingDestroyed = true;
                this.uninitialize();

                // remove this.connect() and this.subscribe() listeners
                var c;
                while(c = this._connects.pop()){
                        c.remove();
                }

                // destroy widgets created as part of template, etc.
                var w;
                while(w = this._supportingWidgets.pop()){
                        if(w.destroyRecursive){
                                w.destroyRecursive();
                        }else if(w.destroy){
                                w.destroy();
                        }
                }

                this.destroyRendering(preserveDom);
                registry.remove(this.id);
                this._destroyed = true;
        },

        destroyRendering: function(/*Boolean?*/ preserveDom){
                // summary:
                //              Destroys the DOM nodes associated with this widget
                // preserveDom:
                //              If true, this method will leave the original DOM structure alone
                //              during tear-down. Note: this will not work with _Templated
                //              widgets yet.
                // tags:
                //              protected

                if(this.bgIframe){
                        this.bgIframe.destroy(preserveDom);
                        delete this.bgIframe;
                }

                if(this.domNode){
                        if(preserveDom){
                                domAttr.remove(this.domNode, "widgetId");
                        }else{
                                domConstruct.destroy(this.domNode);
                        }
                        delete this.domNode;
                }

                if(this.srcNodeRef){
                        if(!preserveDom){
                                domConstruct.destroy(this.srcNodeRef);
                        }
                        delete this.srcNodeRef;
                }
        },

        destroyDescendants: function(/*Boolean?*/ preserveDom){
                // summary:
                //              Recursively destroy the children of this widget and their
                //              descendants.
                // preserveDom:
                //              If true, the preserveDom attribute is passed to all descendant
                //              widget's .destroy() method. Not for use with _Templated
                //              widgets.

                // get all direct descendants and destroy them recursively
                array.forEach(this.getChildren(), function(widget){
                        if(widget.destroyRecursive){
                                widget.destroyRecursive(preserveDom);
                        }
                });
        },

        uninitialize: function(){
                // summary:
                //              Stub function. Override to implement custom widget tear-down
                //              behavior.
                // tags:
                //              protected
                return false;
        },

        ////////////////// GET/SET, CUSTOM SETTERS, ETC. ///////////////////

        _setStyleAttr: function(/*String||Object*/ value){
                // summary:
                //              Sets the style attribute of the widget according to value,
                //              which is either a hash like {height: "5px", width: "3px"}
                //              or a plain string
                // description:
                //              Determines which node to set the style on based on style setting
                //              in attributeMap.
                // tags:
                //              protected

                var mapNode = this.domNode;

                // Note: technically we should revert any style setting made in a previous call
                // to his method, but that's difficult to keep track of.

                if(lang.isObject(value)){
                        domStyle.set(mapNode, value);
                }else{
                        if(mapNode.style.cssText){
                                mapNode.style.cssText += "; " + value;
                        }else{
                                mapNode.style.cssText = value;
                        }
                }

                this._set("style", value);
        },

        _attrToDom: function(/*String*/ attr, /*String*/ value, /*Object?*/ commands){
                // summary:
                //              Reflect a widget attribute (title, tabIndex, duration etc.) to
                //              the widget DOM, as specified by commands parameter.
                //              If commands isn't specified then it's looked up from attributeMap.
                //              Note some attributes like "type"
                //              cannot be processed this way as they are not mutable.
                //
                // tags:
                //              private

                commands = arguments.length >= 3 ? commands : this.attributeMap[attr];

                array.forEach(lang.isArray(commands) ? commands : [commands], function(command){

                        // Get target node and what we are doing to that node
                        var mapNode = this[command.node || command || "domNode"];       // DOM node
                        var type = command.type || "attribute"; // class, innerHTML, innerText, or attribute

                        switch(type){
                                case "attribute":
                                        if(lang.isFunction(value)){ // functions execute in the context of the widget
                                                value = lang.hitch(this, value);
                                        }

                                        // Get the name of the DOM node attribute; usually it's the same
                                        // as the name of the attribute in the widget (attr), but can be overridden.
                                        // Also maps handler names to lowercase, like onSubmit --> onsubmit
                                        var attrName = command.attribute ? command.attribute :
                                                (/^on[A-Z][a-zA-Z]*$/.test(attr) ? attr.toLowerCase() : attr);

                                        domAttr.set(mapNode, attrName, value);
                                        break;
                                case "innerText":
                                        mapNode.innerHTML = "";
                                        mapNode.appendChild(win.doc.createTextNode(value));
                                        break;
                                case "innerHTML":
                                        mapNode.innerHTML = value;
                                        break;
                                case "class":
                                        domClass.replace(mapNode, value, this[attr]);
                                        break;
                        }
                }, this);
        },

        get: function(name){
                // summary:
                //              Get a property from a widget.
                //      name:
                //              The property to get.
                // description:
                //              Get a named property from a widget. The property may
                //              potentially be retrieved via a getter method. If no getter is defined, this
                //              just retrieves the object's property.
                //
                //              For example, if the widget has properties `foo` and `bar`
                //              and a method named `_getFooAttr()`, calling:
                //              `myWidget.get("foo")` would be equivalent to calling
                //              `widget._getFooAttr()` and `myWidget.get("bar")`
                //              would be equivalent to the expression
                //              `widget.bar2`
                var names = this._getAttrNames(name);
                return this[names.g] ? this[names.g]() : this[name];
        },

        set: function(name, value){
                // summary:
                //              Set a property on a widget
                //      name:
                //              The property to set.
                //      value:
                //              The value to set in the property.
                // description:
                //              Sets named properties on a widget which may potentially be handled by a
                //              setter in the widget.
                //
                //              For example, if the widget has properties `foo` and `bar`
                //              and a method named `_setFooAttr()`, calling
                //              `myWidget.set("foo", "Howdy!")` would be equivalent to calling
                //              `widget._setFooAttr("Howdy!")` and `myWidget.set("bar", 3)`
                //              would be equivalent to the statement `widget.bar = 3;`
                //
                //              set() may also be called with a hash of name/value pairs, ex:
                //
                //      |       myWidget.set({
                //      |               foo: "Howdy",
                //      |               bar: 3
                //      |       });
                //
                //      This is equivalent to calling `set(foo, "Howdy")` and `set(bar, 3)`

                if(typeof name === "object"){
                        for(var x in name){
                                this.set(x, name[x]);
                        }
                        return this;
                }
                var names = this._getAttrNames(name),
                        setter = this[names.s];
                if(lang.isFunction(setter)){
                        // use the explicit setter
                        var result = setter.apply(this, Array.prototype.slice.call(arguments, 1));
                }else{
                        // Mapping from widget attribute to DOMNode attribute/value/etc.
                        // Map according to:
                        //              1. attributeMap setting, if one exists (TODO: attributeMap deprecated, remove in 2.0)
                        //              2. _setFooAttr: {...} type attribute in the widget (if one exists)
                        //              3. apply to focusNode or domNode if standard attribute name, excluding funcs like onClick.
                        // Checks if an attribute is a "standard attribute" by whether the DOMNode JS object has a similar
                        // attribute name (ex: accept-charset attribute matches jsObject.acceptCharset).
                        // Note also that Tree.focusNode() is a function not a DOMNode, so test for that.
                        var defaultNode = this.focusNode && !lang.isFunction(this.focusNode) ? "focusNode" : "domNode",
                                tag = this[defaultNode].tagName,
                                attrsForTag = tagAttrs[tag] || (tagAttrs[tag] = getAttrs(this[defaultNode])),
                                map =   name in this.attributeMap ? this.attributeMap[name] :
                                                names.s in this ? this[names.s] :
                                                ((names.l in attrsForTag && typeof value != "function") ||
                                                        /^aria-|^data-|^role$/.test(name)) ? defaultNode : null;
                        if(map != null){
                                this._attrToDom(name, value, map);
                        }
                        this._set(name, value);
                }
                return result || this;
        },

        _attrPairNames: {},             // shared between all widgets
        _getAttrNames: function(name){
                // summary:
                //              Helper function for get() and set().
                //              Caches attribute name values so we don't do the string ops every time.
                // tags:
                //              private

                var apn = this._attrPairNames;
                if(apn[name]){ return apn[name]; }
                var uc = name.replace(/^[a-z]|-[a-zA-Z]/g, function(c){ return c.charAt(c.length-1).toUpperCase(); });
                return (apn[name] = {
                        n: name+"Node",
                        s: "_set"+uc+"Attr",    // converts dashes to camel case, ex: accept-charset --> _setAcceptCharsetAttr
                        g: "_get"+uc+"Attr",
                        l: uc.toLowerCase()             // lowercase name w/out dashes, ex: acceptcharset
                });
        },

        _set: function(/*String*/ name, /*anything*/ value){
                // summary:
                //              Helper function to set new value for specified attribute, and call handlers
                //              registered with watch() if the value has changed.
                var oldValue = this[name];
                this[name] = value;
                if(this._watchCallbacks && this._created && value !== oldValue){
                        this._watchCallbacks(name, oldValue, value);
                }
        },

        on: function(/*String*/ type, /*Function*/ func){
                // summary:
                //              Call specified function when event occurs, ex: myWidget.on("click", function(){ ... }).
                // description:
                //              Call specified function when event `type` occurs, ex: `myWidget.on("click", function(){ ... })`.
                //              Note that the function is not run in any particular scope, so if (for example) you want it to run in the
                //              widget's scope you must do `myWidget.on("click", lang.hitch(myWidget, func))`.

                return aspect.after(this, this._onMap(type), func, true);
        },

        _onMap: function(/*String*/ type){
                // summary:
                //              Maps on() type parameter (ex: "mousemove") to method name (ex: "onMouseMove")
                var ctor = this.constructor, map = ctor._onMap;
                if(!map){
                        map = (ctor._onMap = {});
                        for(var attr in ctor.prototype){
                                if(/^on/.test(attr)){
                                        map[attr.replace(/^on/, "").toLowerCase()] = attr;
                                }
                        }
                }
                return map[type.toLowerCase()]; // String
        },

        toString: function(){
                // summary:
                //              Returns a string that represents the widget
                // description:
                //              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 reversible
                //              serialization.
                return '[Widget ' + this.declaredClass + ', ' + (this.id || 'NO ID') + ']'; // String
        },

        getChildren: function(){
                // summary:
                //              Returns all the widgets contained by this, i.e., all widgets underneath this.containerNode.
                //              Does not return nested widgets, nor widgets that are part of this widget's template.
                return this.containerNode ? registry.findWidgets(this.containerNode) : []; // dijit._Widget[]
        },

        getParent: function(){
                // summary:
                //              Returns the parent widget of this widget
                return registry.getEnclosingWidget(this.domNode.parentNode);
        },

        connect: function(
                        /*Object|null*/ obj,
                        /*String|Function*/ event,
                        /*String|Function*/ method){
                // summary:
                //              Connects specified obj/event to specified method of this object
                //              and registers for disconnect() on widget destroy.
                // description:
                //              Provide widget-specific analog to dojo.connect, except with the
                //              implicit use of this widget as the target object.
                //              Events connected with `this.connect` are disconnected upon
                //              destruction.
                // returns:
                //              A handle that can be passed to `disconnect` in order to disconnect before
                //              the widget is destroyed.
                // example:
                //      |       var btn = new dijit.form.Button();
                //      |       // when foo.bar() is called, call the listener we're going to
                //      |       // provide in the scope of btn
                //      |       btn.connect(foo, "bar", function(){
                //      |               console.debug(this.toString());
                //      |       });
                // tags:
                //              protected

                var handle = connect.connect(obj, event, this, method);
                this._connects.push(handle);
                return handle;          // _Widget.Handle
        },

        disconnect: function(handle){
                // summary:
                //              Disconnects handle created by `connect`.
                //              Also removes handle from this widget's list of connects.
                // tags:
                //              protected
                var i = array.indexOf(this._connects, handle);
                if(i != -1){
                        handle.remove();
                        this._connects.splice(i, 1);
                }
        },

        subscribe: function(t, method){
                // summary:
                //              Subscribes to the specified topic and calls the specified method
                //              of this object and registers for unsubscribe() on widget destroy.
                // description:
                //              Provide widget-specific analog to dojo.subscribe, except with the
                //              implicit use of this widget as the target object.
                // t: String
                //              The topic
                // method: Function
                //              The callback
                // example:
                //      |       var btn = new dijit.form.Button();
                //      |       // when /my/topic is published, this button changes its label to
                //      |   // be the parameter of the topic.
                //      |       btn.subscribe("/my/topic", function(v){
                //      |               this.set("label", v);
                //      |       });
                // tags:
                //              protected
                var handle = topic.subscribe(t, lang.hitch(this, method));
                this._connects.push(handle);
                return handle;          // _Widget.Handle
        },

        unsubscribe: function(/*Object*/ handle){
                // summary:
                //              Unsubscribes handle created by this.subscribe.
                //              Also removes handle from this widget's list of subscriptions
                // tags:
                //              protected
                this.disconnect(handle);
        },

        isLeftToRight: function(){
                // summary:
                //              Return this widget's explicit or implicit orientation (true for LTR, false for RTL)
                // tags:
                //              protected
                return this.dir ? (this.dir == "ltr") : domGeometry.isBodyLtr(); //Boolean
        },

        isFocusable: function(){
                // summary:
                //              Return true if this widget can currently be focused
                //              and false if not
                return this.focus && (domStyle.get(this.domNode, "display") != "none");
        },

        placeAt: function(/* String|DomNode|_Widget */reference, /* String?|Int? */position){
                // summary:
                //              Place this widget's domNode reference somewhere in the DOM based
                //              on standard domConstruct.place conventions, or passing a Widget reference that
                //              contains and addChild member.
                //
                // description:
                //              A convenience function provided in all _Widgets, providing a simple
                //              shorthand mechanism to put an existing (or newly created) Widget
                //              somewhere in the dom, and allow chaining.
                //
                // reference:
                //              The String id of a domNode, a domNode reference, or a reference to a Widget possessing
                //              an addChild method.
                //
                // position:
                //              If passed a string or domNode reference, the position argument
                //              accepts a string just as domConstruct.place does, one of: "first", "last",
                //              "before", or "after".
                //
                //              If passed a _Widget reference, and that widget reference has an ".addChild" method,
                //              it will be called passing this widget instance into that method, supplying the optional
                //              position index passed.
                //
                // returns:
                //              dijit._Widget
                //              Provides a useful return of the newly created dijit._Widget instance so you
                //              can "chain" this function by instantiating, placing, then saving the return value
                //              to a variable.
                //
                // example:
                // |    // create a Button with no srcNodeRef, and place it in the body:
                // |    var button = new dijit.form.Button({ label:"click" }).placeAt(win.body());
                // |    // now, 'button' is still the widget reference to the newly created button
                // |    button.on("click", function(e){ console.log('click'); }));
                //
                // example:
                // |    // create a button out of a node with id="src" and append it to id="wrapper":
                // |    var button = new dijit.form.Button({},"src").placeAt("wrapper");
                //
                // example:
                // |    // place a new button as the first element of some div
                // |    var button = new dijit.form.Button({ label:"click" }).placeAt("wrapper","first");
                //
                // example:
                // |    // create a contentpane and add it to a TabContainer
                // |    var tc = dijit.byId("myTabs");
                // |    new dijit.layout.ContentPane({ href:"foo.html", title:"Wow!" }).placeAt(tc)

                if(reference.declaredClass && reference.addChild){
                        reference.addChild(this, position);
                }else{
                        domConstruct.place(this.domNode, reference, position);
                }
                return this;
        },

        getTextDir: function(/*String*/ text,/*String*/ originalDir){
                // summary:
                //              Return direction of the text.
                //              The function overridden in the _BidiSupport module,
                //              its main purpose is to calculate the direction of the
                //              text, if was defined by the programmer through textDir.
                //      tags:
                //              protected.
                return originalDir;
        },

        applyTextDir: function(/*===== element, text =====*/){
                // summary:
                //              The function overridden in the _BidiSupport module,
                //              originally used for setting element.dir according to this.textDir.
                //              In this case does nothing.
                // element: DOMNode
                // text: String
                // tags:
                //              protected.
        }
});

});