#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# WidgetParent Class

Uses

- ArrayList

Defined in: `widget-parent/js/Widget-Parent.js:11`
Module: widget-parent

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`

)

Defined in `widget-parent/js/Widget-Parent.js:11`

#### Parameters:

- `config` Object

  User configuration object.

- Index
- Methods
- Properties
- Attributes
- Events

## Item Index

### Methods

- _add
- _afterActiveDescendantChange
- _afterDestroyChild
- _afterParentSelectedChange
- _afterSelectionChange
- _bindUIParent
- _createChild
- _defAddChildFn
- _defRemoveChildFn
- _destroyChildren
- _item
- _renderChildren
- _setSelection
- _uiAddChild
- _uiRemoveChild
- _updateActiveDescendant
- _updateSelection
- add
- deselectAll
- destructor
- each
- filter deprecated
- indexOf
- isEmpty
- item
- itemsAreEqual deprecated
- remove
- removeAll
- selectAll
- selectChild
- size
- some
- toJSON

### Properties

- _childrenContainer

### Attributes

- activeDescendant
- defaultChildType
- multiple
- selection

### Events

- addChild
- removeChild

## Methods

### `_add`

(

- `child`
- `child`
- `index`

)
Widget | Array protected

Defined in `widget-parent/js/Widget-Parent.js:533`

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`

(

- `event`

)
protected

Defined in `widget-parent/js/Widget-Parent.js:271`

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`

(

- `event`

)
protected

Defined in `widget-parent/js/Widget-Parent.js:217`

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`

(

- `event`

)
protected

Defined in `widget-parent/js/Widget-Parent.js:288`

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`

(

- `event`

)
protected

Defined in `widget-parent/js/Widget-Parent.js:234`

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

Defined in `widget-parent/js/Widget-Parent.js:787`

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`

(

- `config`

)
protected

Defined in `widget-parent/js/Widget-Parent.js:419`

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`

(

- `event`
- `child`
- `index`

)
protected

Defined in `widget-parent/js/Widget-Parent.js:462`

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`

(

- `event`
- `child`
- `index`

)
protected

Defined in `widget-parent/js/Widget-Parent.js:502`

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

Defined in `widget-parent/js/Widget-Parent.js:835`

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.

### `_item`

(

- `i`

)
Mixed protected

Inherited from ArrayList: `collection/js/arraylist.js:138`

Protected method for optimizations that may be appropriate for API mirroring. Similar in functionality to `item`, but is used by methods added with `ArrayList.addMethod()`.

#### Parameters:

- `i` Integer

  Index of item to fetch

#### Returns:

Mixed: The item appropriate for pass through API methods

### `_renderChildren`

() protected

Defined in `widget-parent/js/Widget-Parent.js:802`

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`

(

- `child`

)
Widget | Array protected

Defined in `widget-parent/js/Widget-Parent.js:320`

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`

(

- `child`
- `parentNode`

)
protected

Defined in `widget-parent/js/Widget-Parent.js:704`

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`

(

- `child`

)
protected

Defined in `widget-parent/js/Widget-Parent.js:760`

Updates the UI in response to a child being removed.

#### Parameters:

- `child` Widget

  The child Widget instance to render.

### `_updateActiveDescendant`

(

- `event`

)
protected

Defined in `widget-parent/js/Widget-Parent.js:405`

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`

(

- `event`

)
protected

Defined in `widget-parent/js/Widget-Parent.js:363`

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`

(

- `child`
- `child`
- `index`

)
ArrayList

Inherited from ArrayList but overwritten in `widget-parent/js/Widget-Parent.js:596`

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:

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

### `deselectAll`

()

Defined in `widget-parent/js/Widget-Parent.js:695`

Deselects all children.

### `destructor`

()

Defined in `widget-parent/js/Widget-Parent.js:209`

The destructor implementation for Parent widgets. Destroys all children.

### `each`

(

- `fn`
- `context`

)
ArrayList chainable

Inherited from ArrayList: `collection/js/arraylist.js:51`

Execute a function on each item of the list, optionally providing a custom execution context. Default context is the item.

The callback signature is `callback( item, index )`.

#### Parameters:

- `fn` Function

  the function to execute

- `context` Mixed

  optional override 'this' in the function

#### Returns:

ArrayList: this instance

### `filter`

(

- `validator`

)
ArrayList deprecated

Inherited from ArrayList: `collection/js/arraylist-filter.js:13`

Deprecated: Use ModelList or a custom subclass implementation

Create a new ArrayList (or augmenting class instance) from a subset of items as determined by the boolean function passed as the argument. The original ArrayList is unchanged.

The validator signature is `validator( item )`.

#### Parameters:

- `validator` Function

  Boolean function to determine in or out.

#### Returns:

ArrayList: New instance based on who passed the validator.

### `indexOf`

(

- `needle`

)
Integer

Inherited from ArrayList: `collection/js/arraylist.js:95`

Finds the first index of the needle in the managed array of items.

#### Parameters:

- `needle` Mixed

  The item to search for

#### Returns:

Integer: Array index if found. Otherwise -1

### `isEmpty`

() Boolean

Inherited from ArrayList: `collection/js/arraylist.js:116`

Is this instance managing any items?

#### Returns:

Boolean: true if 1 or more items are being managed

### `item`

(

- `i`

)
Mixed

Inherited from ArrayList: `collection/js/arraylist.js:37`

Get an item by index from the list. Override this method if managing a list of objects that have a different public representation (e.g. Node instances vs DOM nodes). The iteration methods that accept a user function will use this method for access list items for operation.

#### Parameters:

- `i` Integer

  index to fetch

#### Returns:

Mixed: the item at the requested index

### `itemsAreEqual`

(

- `a`
- `b`

)
Boolean deprecated

Inherited from ArrayList: `collection/js/arraylist-add.js:68`

Deprecated: Use ModelList or a custom ArrayList subclass

Default comparator for items stored in this list. Used by remove().

#### Parameters:

- `a` Mixed

  item to test equivalence with.

- `b` Mixed

  other item to test equivalance.

#### Returns:

Boolean: true if items are deemed equivalent.

### `remove`

(

- `index`

)
Widget

Inherited from ArrayList but overwritten in `widget-parent/js/Widget-Parent.js:627`

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`

() ArrayList

Defined in `widget-parent/js/Widget-Parent.js:650`

Removes all of the children from the Widget.

#### Returns:

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

### `selectAll`

()

Defined in `widget-parent/js/Widget-Parent.js:686`

Selects all children.

### `selectChild`

(

- `i`

)

Defined in `widget-parent/js/Widget-Parent.js:676`

Selects the child at the given index (zero-based).

#### Parameters:

- `i` Number

  the index of the child to be selected

### `size`

() Integer

Inherited from ArrayList: `collection/js/arraylist.js:106`

How many items are in this list?

#### Returns:

Integer: Number of items in the list

### `some`

(

- `fn`
- `context`

)
Boolean

Inherited from ArrayList: `collection/js/arraylist.js:73`

Execute a function on each item of the list, optionally providing a custom execution context. Default context is the item.

The callback signature is `callback( item, index )`.

Unlike `each`, if the callback returns true, the iteratation will stop.

#### Parameters:

- `fn` Function

  the function to execute

- `context` Mixed

  optional override 'this' in the function

#### Returns:

Boolean: True if the function returned true on an item

### `toJSON`

() Array

Inherited from ArrayList: `collection/js/arraylist.js:126`

Provides an array-like representation for JSON.stringify.

#### Returns:

Array: an array representation of the ArrayList

## Properties

### `_childrenContainer`

Node protected

Defined in `widget-parent/js/Widget-Parent.js:813`

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.

## Attributes

### `activeDescendant`

Widget readonly

Defined in `widget-parent/js/Widget-Parent.js:128`

Returns the Widget's currently focused descendant Widget.

#### Fires event `activeDescendantChange`

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:

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

### `defaultChildType`

String | Object

Defined in `widget-parent/js/Widget-Parent.js:106`

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

#### Fires event `defaultChildTypeChange`

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:

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

### `multiple`

Boolean

Defined in `widget-parent/js/Widget-Parent.js:139`

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: false

#### Fires event `multipleChange`

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:

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

### `selection`

ArrayList | Widget readonly

Defined in `widget-parent/js/Widget-Parent.js:161`

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.

#### Fires event `selectionChange`

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:

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

## Events

### `addChild`

Defined in `widget-parent/js/Widget-Parent.js:29`

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.

#### Event Payload:

- `e` EventFacade

  The Event Facade

### `removeChild`

Defined in `widget-parent/js/Widget-Parent.js:53`

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.

#### Event Payload:

- `e` EventFacade

  The Event Facade