The Uize.Widget class supports a children instance property as well as a children state property, and each has its own purpose.

2.3.1.1. The children Instance Property

2.3.1.2. The children State Property

The new children state property allows properties to be distributed to any or all of a widget's child widgets, or even child widgets of the widget's child widgets - all the way down to the deepest child widgets in a widget's widget tree.

Consider the following example...

EXAMPLE

/*** build up a widget tree under the page widget ***/
  var
    page = new Uize.Widget.Page,
    rgbSliders = page.addChild ('rgbSliders',Uize.Widget)
  ;

  rgbSliders.addChild ('sliderR',Uize.Widget.Bar.Slider);
  rgbSliders.addChild ('sliderG',Uize.Widget.Bar.Slider);
  rgbSliders.addChild ('sliderB',Uize.Widget.Bar.Slider);

/*** now, set values for the deepest widgets in the widget tree ***/
  page.set ({
    children:{
      rgbSlider:{
        children:{
          sliderR:{value:127},
          sliderG:{value:255},
          sliderB:{value:0}
        }
      }
    }
  });

If the sliderR, sliderG, and sliderB slider widgets together represented an RGB color value, then the above code would initialize them to represent the color chartreuse. This is admittedly not a terribly compelling example of how to use the special behavior of the children state property, but it demonstrates the basic principle.

The special behavior of the children state property allows widget properties to be specified for a child widget even before that child widget has been created.

EXAMPLE

/*** create a page widget, specifying properties for child widgets not yet created ***/
  var page = new Uize.Widget.Page ({
    children:{
      rgbSlider:{
        children:{
          sliderR:{value:127},
          sliderG:{value:255},
          sliderB:{value:0}
        }
      }
    }
  });

/*** now, create the child widgets for which properties were specified earlier ***/
  var rgbSliders = page.addChild ('rgbSliders',Uize.Widget);

  rgbSliders.addChild ('sliderR',Uize.Widget.Bar.Slider);
  rgbSliders.addChild ('sliderG',Uize.Widget.Bar.Slider);
  rgbSliders.addChild ('sliderB',Uize.Widget.Bar.Slider);

In the above example, a page widget is being created and a value is being specified for its children state property that is defining widget properties for child widgets in the page widget's widget tree that have not yet been created. Then, after the fact, a widget tree is fleshed out for the page widget, with child widgets that correspond to the structure of the object specified for the children state property when the page widget instance was created. Because of the special way that the children state property works, the widget properties defined earlier are "picked up" by the child widgets when they are created.

Along with using the children state property in the constructor of a widget instance, when calling the instance's set method, or in a widget adoption declaration, the children state property can also be used in the declarative syntax for widget properties.

EXAMPLE

/*** declare widget properties for a page widget ***/
  window.$page = {
    children:{
      rgbSlider:{
        children:{
          sliderR:{value:127},
          sliderG:{value:255},
          sliderB:{value:0}
        }
      }
    }
  };

/*** now, create the page widget and build a widget tree under it ***/
  var
    page = new Uize.Widget.Page,
    rgbSliders = page.addChild ('rgbSliders',Uize.Widget)
  ;
  rgbSliders.addChild ('sliderR',Uize.Widget.Bar.Slider);
  rgbSliders.addChild ('sliderG',Uize.Widget.Bar.Slider);
  rgbSliders.addChild ('sliderB',Uize.Widget.Bar.Slider);

In the above example, a $page property is being defined on the window object. Because the default idPrefix of the page widget is 'page', the $page property is effectively declaring widget properties for the page widget.

In our example, the page widget is created later. What you'll notice is that the value of the $page property is an object that contains a children property, which is itself an object containing a single rgbSlider property. This is declaring widget properties for the rgbSlider child widget of the page widget. Furthermore, the rgbSlider property is an object containing its own children property, which is declaring widget properties for the sliderR, sliderG, and sliderB child widgets of the rgbSlider child widget.

So, the widget properties declared for a widget using the declarative syntax may contain widget properties for any or all of the child widgets of the widget - all the way down to the deepest child widgets in the widget's widget tree.

Setting the value of the children state property is handled in a special way and has no effect on the actual child widgets for a widget, nor does it affect the value or contents of the children instance property.

When you set a value for the children state property, the widget instance tries to distribute any specified child widget properties to the widget's current child widgets. If widget properties are specified for a child that does not yet exist, that child widget is not created. Instead, the unapplied child widget properties are remembered. If a child widget is added later and its name corresponds to the name of a child widget for which unapplied widget properties have been remembered, then those widget properties are applied at the time of creating the child widget (for more details, see the section The children State Children Property Allows Deferred Pickup).