Widget: make destroyDescendants() go bottom up

[Les]

I'd like to answer the TODO question... Yes, I'd prefer reversed order of destruction. Occasionally, when a widget is destroyed I'd like to access the enclosing widget; however, the enclosing widget is already gone. Typically, objects are destroyed from the inside going outside.

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(); });
},

[bill]

I agree, although it isn't as important an issue as it used to be since it's no longer an issue with _Container based widgets:

destroyDescendants: function(/*Boolean*/ preserveDom){
	dojo.forEach(this.getChildren(), function(child){ child.destroyRecursive(preserveDom); });
},

I suppose this is also something to think about w/ContentPane (actually I mean dojo.html) since that keeps it's own list of widgets and destroys them, thus going top down rather than bottom up.

[bill]

Fixed in [15607]: Fix destroyDescendants() to avoid problems with double-deletes of widgets in templates.

Added flag to getDescendants() to only get direct descendants, not nested descendants. getDescendants(true) is similar to getChildren() except that the DOM nodes of the descendant widgets don't need to be direct children of this.containerNode, so it's suitable for free-form contents like ContentPane?.

Fixes #6954, #7550. Refs #7706, #7784, #7823. !strict

[bill]

(In [16904]) 1. Refactor [15607] (refs #6954, #7550, #7706, #7784, #7823) so that getDescendants() works as in 1.2 again, returning all descendant widgets, even nested widgets that are defined in templates. Expose the new functionality from [15607], to find direct descendants only, into a new _Widget.getChildren() method, rather than as flag to getDescendants().

This is because:

• [15607] gave getDescendants() a subtle API change: it no longer found widgets inside of a dijit.Declaration (since no containerNode was defined)
• because of that, Form was broken in that it didn't find form widgets inside of a custom widgets, declared with dijit.Declaration or dojo.declare, which didn't define this.containerNode

2. Also, rolling back #7819: ContentPane?: missing an addChild() method (refs #7819), because of the backwards compatibility issue for custom widgets that extend ContentPane? and also extend _Container/_Contained.

Summary:

• getChildren() is now supported by all widgets, and _Container widgets have (as before) an optimized implementation of getChildren() that overrides the one in _Widget.
• ContentPane? not supporting any _Container methods except getChildren(). Users can set a ContentPane? child by calling attr('value', ...) etc.

!strict