# Yahoo! UI Library

### widget-parent 3.3.0

Yahoo! UI Library > widget-parent > WidgetParent
Search:
Filters Show Private Show Protected Show Deprecated

## Class WidgetParent - uses ArrayList

Widget extension providing functionality enabling a Widget to be a parent of another Widget.

In addition to the set of attributes supported by WidgetParent, the constructor configuration object can also contain a `children` which can be used to add child widgets to the parent during construction. The `children` property is an array of either child widget instances or child widget configuration objects, and is sugar for the add method. See the add for details on the structure of the child widget configuration object.

### Constructor

WidgetParent `( config )`

Parameters:
  `config <Object>` User configuration object.

### Properties

#### _childrenContainer - `protected Node`

By default WidgetParent will render it's children to the parent's content box.

If the children need to be rendered somewhere else, the _childrenContainer property can be set to the Node which the children should be rendered to. This property should be set before the _renderChildren method is invoked, ideally in your renderUI method, as soon as you create the element to be rendered to.

### Methods

#### _add

`protected Widget|Array _add ( child , index )`
Adds a Widget as a child. If the specified Widget already has a parent it will be removed from its current parent before being added as a child.

Parameters:
  `child <Widget|Object>` The Widget instance, or configuration object for the Widget to be added as a child.
  `child <Array>` Array of Widget instances, or configuration objects for the Widgets to be added as a children.
  `index <Number>` (Optional.) Number representing the position at which the child should be inserted.

Returns: `Widget|Array`
  Successfully added Widget or Array containing the successfully added Widget instance(s). If no children where added, will will return undefined.

#### _afterActiveDescendantChange

`protected void _afterActiveDescendantChange ( event )`
Attribute change listener for the `activeDescendant` attribute, responsible for setting the value of the parent's `activeDescendant` attribute.

Parameters:
  `event <EventFacade>` The event facade for the attribute change.

#### _afterDestroyChild

`protected void _afterDestroyChild ( event )`
Destroy event listener for each child Widget, responsible for removing the destroyed child Widget from the parent's internal array of children (_items property).

Parameters:
  `event <EventFacade>` The event facade for the attribute change.

#### _afterParentSelectedChange

`protected void _afterParentSelectedChange ( event )`
Attribute change listener for the `selected` attribute, responsible for syncing the selected state of all children to match that of their parent Widget.

Parameters:
  `event <EventFacade>` The event facade for the attribute change.

#### _afterSelectionChange

`protected void _afterSelectionChange ( event )`
Attribute change listener for the `selection` attribute, responsible for setting the value of the parent's `selected` attribute.

Parameters:
  `event <EventFacade>` The event facade for the attribute change.

#### _bindUIParent

`protected void _bindUIParent ( )`
Sets up DOM and CustomEvent listeners for the parent widget.

This method in invoked after bindUI is invoked for the Widget class using YUI's aop infrastructure.

#### _createChild

`protected void _createChild ( config )`
Creates an instance of a child Widget using the specified configuration. By default Widget instances will be created of the type specified by the `defaultChildType` attribute. Types can be explicitly defined via the `childType` property of the configuration object literal. The use of the `type` property has been deprecated, but will still be used as a fallback, if `childType` is not defined, for backwards compatibility.

Parameters:
  `config <Object>` Object literal representing the configuration used to create an instance of a Widget.

#### _defAddChildFn

`protected void _defAddChildFn ( event , child , index )`
Default addChild handler

Parameters:
  `event <EventFacade>` The Event object
  `child <Widget>` The Widget instance, or configuration object for the Widget to be added as a child.
  `index <Number>` Number representing the position at which the child will be inserted.

#### _defRemoveChildFn

`protected void _defRemoveChildFn ( event , child , index )`
Default removeChild handler

Parameters:
  `event <EventFacade>` The Event object
  `child <Widget>` The Widget instance to be removed.
  `index <Number>` Number representing the index of the Widget to be removed.

#### _destroyChildren

`protected void _destroyChildren ( )`
Destroys all child Widgets for the parent.

This method is invoked before the destructor is invoked for the Widget class using YUI's aop infrastructure.

#### _renderChildren

`protected void _renderChildren ( )`
Renders all child Widgets for the parent.

This method in invoked after renderUI is invoked for the Widget class using YUI's aop infrastructure.

#### _setSelection

`protected Widget|Array _setSelection ( child )`
Default setter for `selection` attribute changes.

Parameters:
  `child <Widget|Array>` Widget or Array of Widget instances.

Returns: `Widget|Array`
  Widget or Array of Widget instances.

#### _uiAddChild

`protected void _uiAddChild ( child , parentNode )`
Updates the UI in response to a child being added.

Parameters:
  `child <Widget>` The child Widget instance to render.
  `parentNode <Object>` The Node under which the child Widget is to be rendered.

#### _uiRemoveChild

`protected void _uiRemoveChild ( child )`
Updates the UI in response to a child being removed.

Parameters:
  `child <Widget>` The child Widget instance to render.

#### _updateActiveDescendant

`protected void _updateActiveDescendant ( event )`
Attribute change listener for the `focused` attribute of child Widgets, responsible for setting the value of the parent's `activeDescendant` attribute.

Parameters:
  `event <EventFacade>` The event facade for the attribute change.

#### _updateSelection

`protected void _updateSelection ( event )`
Attribute change listener for the `selected` attribute of child Widgets, responsible for setting the value of the parent's `selection` attribute.

Parameters:
  `event <EventFacade>` The event facade for the attribute change.

#### add

`Y.ArrayList add ( child , index )`
Adds a Widget as a child. If the specified Widget already has a parent it will be removed from its current parent before being added as a child.

Parameters:
  `child <Widget|Object>` The Widget instance, or configuration object for the Widget to be added as a child. The configuration object for the child can include a `childType` property, which is either a constructor function or a string which names a constructor function on the Y instance (e.g. "Tab" would refer to Y.Tab) (`childType` used to be named `type`, support for which has been deprecated, but is still maintained for backward compatibility. `childType` takes precedence over `type` if both are defined.
  `child <Array>` Array of Widget instances, or configuration objects for the Widgets to be added as a children.
  `index <Number>` (Optional.) Number representing the position at which the child should be inserted.

Returns: `Y.ArrayList`
  Y.ArrayList containing the successfully added Widget instance(s). If no children where added, will return an empty Y.ArrayList instance.

#### deselectAll

`void deselectAll ( )`
Deselects all children.

#### remove

`Widget remove ( index )`
Removes the Widget from its parent. Optionally, can remove a child by specifying its index.

Parameters:
  `index <Number>` (Optional.) Number representing the index of the child to be removed.

Returns: `Widget`
  Widget instance that was successfully removed, otherwise undefined.

#### removeAll

`Y.ArrayList removeAll ( )`
Removes all of the children from the Widget.

Returns: `Y.ArrayList`
  Y.ArrayList instance containing Widgets that were successfully removed. If no children where removed, will return an empty Y.ArrayList instance.

#### selectAll

`void selectAll ( )`
Selects all children.

#### selectChild

`void selectChild ( i )`
Selects the child at the given index (zero-based).

Parameters:
  `i <Number>` the index of the child to be selected

#### Methods inherited from ArrayList:

`_item, each, indexOf, isEmpty, item, size, some, toJSON`

### Events

#### activeDescendantChange

`activeDescendantChange ( event )`
Fires when the value for the configuration attribute 'activeDescendant' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### addChild

`addChild ( e )`
Fires when a Widget is add as a child. The event object will have a 'child' property that returns a reference to the child Widget, as well as an 'index' property that returns a reference to the index specified when the add() method was called.

Subscribers to the "on" moment of this event, will be notified before a child is added.

Subscribers to the "after" moment of this event, will be notified after a child is added.

Parameters:
  `e <EventFacade>` The Event Facade

Preventable: This event is preventable by method e.preventDefault(). The default function executed by this event is _defAddChildFn.

#### defaultChildTypeChange

`defaultChildTypeChange ( event )`
Fires when the value for the configuration attribute 'defaultChildType' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### multipleChange

`multipleChange ( event )`
Fires when the value for the configuration attribute 'multiple' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### removeChild

`removeChild ( e )`
Fires when a child Widget is removed. The event object will have a 'child' property that returns a reference to the child Widget, as well as an 'index' property that returns a reference child's ordinal position.

Subscribers to the "on" moment of this event, will be notified before a child is removed.

Subscribers to the "after" moment of this event, will be notified after a child is removed.

Parameters:
  `e <EventFacade>` The Event Facade

Preventable: This event is preventable by method e.preventDefault(). The default function executed by this event is _defRemoveChildFn.

#### selectionChange

`selectionChange ( event )`
Fires when the value for the configuration attribute 'selection' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

### Configuration Attributes

#### activeDescendant `- Widget`

Returns the Widget's currently focused descendant Widget.

#### defaultChildType `- {String|Object}`

String representing the default type of the children managed by this Widget. Can also supply default type as a constructor reference.

#### multiple `- writeonce Boolean`

Boolean indicating if multiple children can be selected at once. Whether or not multiple selection is enabled is always delegated to the value of the `multiple` attribute of the root widget in the object hierarchy.
Default Value: false

#### selection `- {Y.ArrayList|Widget}`

Returns the currently selected child Widget. If the `mulitple` attribte is set to `true` will return an Y.ArrayList instance containing the currently selected children. If no children are selected, will return null.

Copyright © 2011 Yahoo! Inc. All rights reserved.