Show:

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

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

Constructor

WidgetParent

(
  • config
)

Parameters:

  • config Object

    User configuration object.

Methods

_add

(
  • child
  • index
)
Widget | Array protected

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 | Array

    <p><p>The Widget instance, or configuration object for the Widget, or Array of Widget instances to be added as a child.</p></p>

  • index Number

    <p><p>Number representing the position at which the child should be inserted.</p></p>

Returns:

Widget | Array:

<p><p>Successfully added Widget or Array containing the successfully added Widget instance(s). If no children where added, will will return undefined.</p></p>

_afterActiveDescendantChange

(
  • event
)
protected

Attribute change listener for the <code>activeDescendant</code> attribute, responsible for setting the value of the parent's <code>activeDescendant</code> attribute.

Parameters:

  • event EventFacade

    <p><p>The event facade for the attribute change.</p></p>

_afterDestroyChild

(
  • event
)
protected

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

    <p><p>The event facade for the attribute change.</p></p>

_afterParentSelectedChange

(
  • event
)
protected

Attribute change listener for the <code>selected</code> attribute, responsible for syncing the selected state of all children to match that of their parent Widget.

Parameters:

  • event EventFacade

    <p><p>The event facade for the attribute change.</p></p>

_afterSelectionChange

(
  • event
)
protected

Attribute change listener for the <code>selection</code> attribute, responsible for setting the value of the parent's <code>selected</code> attribute.

Parameters:

  • event EventFacade

    <p><p>The event facade for the attribute change.</p></p>

_bindUIParent

() protected

Sets up DOM and CustomEvent listeners for the parent widget. <p> This method in invoked after bindUI is invoked for the Widget class using YUI's aop infrastructure. </p>

_createChild

(
  • config
)
protected

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

Parameters:

  • config Object

    <p><p>Object literal representing the configuration used to create an instance of a Widget.</p></p>

_defAddChildFn

(
  • event
  • child
  • index
)
protected

Default addChild handler

Parameters:

  • event EventFacade

    <p><p>The Event object</p></p>

  • child Widget

    <p><p>The Widget instance, or configuration object for the Widget to be added as a child.</p></p>

  • index Number

    <p><p>Number representing the position at which the child will be inserted.</p></p>

_defRemoveChildFn

(
  • event
  • child
  • index
)
protected

Default removeChild handler

Parameters:

  • event EventFacade

    <p><p>The Event object</p></p>

  • child Widget

    <p><p>The Widget instance to be removed.</p></p>

  • index Number

    <p><p>Number representing the index of the Widget to be removed.</p></p>

_destroyChildren

() protected

Destroys all child Widgets for the parent. <p> This method is invoked before the destructor is invoked for the Widget class using YUI's aop infrastructure. </p>

_item

(
  • i
)
Mixed protected

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

Parameters:

  • i Integer

    <p><p><p><p><p><p>Index of item to fetch</p></p></p></p></p></p>

Returns:

Mixed:

<p><p><p><p><p><p>The item appropriate for pass through API methods</p></p></p></p></p></p>

_renderChildren

() protected

Renders all child Widgets for the parent. <p> This method in invoked after renderUI is invoked for the Widget class using YUI's aop infrastructure. </p>

_setSelection

(
  • child
)
Widget | Array protected

Default setter for <code>selection</code> attribute changes.

Parameters:

  • child Widget | Array

    <p><p>Widget or Array of Widget instances.</p></p>

Returns:

Widget | Array:

<p><p>Widget or Array of Widget instances.</p></p>

_uiAddChild

(
  • child
  • parentNode
)
protected

Updates the UI in response to a child being added.

Parameters:

  • child Widget

    <p><p>The child Widget instance to render.</p></p>

  • parentNode Object

    <p><p>The Node under which the child Widget is to be rendered.</p></p>

_uiRemoveChild

(
  • child
)
protected

Updates the UI in response to a child being removed.

Parameters:

  • child Widget

    <p><p>The child Widget instance to render.</p></p>

_updateActiveDescendant

(
  • event
)
protected

Attribute change listener for the <code>focused</code> attribute of child Widgets, responsible for setting the value of the parent's <code>activeDescendant</code> attribute.

Parameters:

  • event EventFacade

    <p><p>The event facade for the attribute change.</p></p>

_updateSelection

(
  • event
)
protected

Attribute change listener for the <code>selected</code> attribute of child Widgets, responsible for setting the value of the parent's <code>selection</code> attribute.

Parameters:

  • event EventFacade

    <p><p>The event facade for the attribute change.</p></p>

add

(
  • child
  • index
)
ArrayList

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 | Array

    <p><p>The Widget instance, or configuration object for the Widget, or Array of Widget instances to be added as a child. The configuration object for the child can include a <code>childType</code> 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). <code>childType</code> used to be named <code>type</code>, support for which has been deprecated, but is still maintained for backward compatibility. <code>childType</code> takes precedence over <code>type</code> if both are defined.</p></p>

  • index Number

    <p><p>Number representing the position at which the child should be inserted.</p></p>

Returns:

ArrayList:

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

deselectAll

()

Deselects all children.

destructor

()

The destructor implementation for Parent widgets. Destroys all children.

each

(
  • fn
  • context
)
ArrayList chainable

<p><p>Execute a function on each item of the list, optionally providing a custom execution context. Default context is the item.</p></p> <p><p>The callback signature is <code>callback( item, index )</code>.</p></p>

Parameters:

  • fn Function

    <p><p><p><p><p><p>the function to execute</p></p></p></p></p></p>

  • context Mixed

    <p><p><p><p><p><p>optional override 'this' in the function</p></p></p></p></p></p>

Returns:

ArrayList:

<p><p><p><p><p><p>this instance</p></p></p></p></p></p>

filter

(
  • validator
)
ArrayList deprecated

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

Deprecated: Use ModelList or a custom subclass implementation

<p><p>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.</p></p> <p><p>The validator signature is <code>validator( item )</code>.</p></p>

Parameters:

  • validator Function

    <p><p><p><p><p><p>Boolean function to determine in or out.</p></p></p></p></p></p>

Returns:

ArrayList:

<p><p><p><p><p><p>New instance based on who passed the validator.</p></p></p></p></p></p>

indexOf

(
  • needle
)
Integer

<p>Finds the first index of the needle in the managed array of items.</p>

Parameters:

  • needle Mixed

    <p><p><p><p><p><p>The item to search for</p></p></p></p></p></p>

Returns:

Integer:

<p><p><p><p><p><p>Array index if found. Otherwise -1</p></p></p></p></p></p>

isEmpty

() Boolean

<p>Is this instance managing any items?</p>

Returns:

Boolean:

<p><p><p><p><p><p>true if 1 or more items are being managed</p></p></p></p></p></p>

item

(
  • i
)
Mixed

<p>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.</p>

Parameters:

  • i Integer

    <p><p><p><p><p><p>index to fetch</p></p></p></p></p></p>

Returns:

Mixed:

<p><p><p><p><p><p>the item at the requested index</p></p></p></p></p></p>

itemsAreEqual

(
  • a
  • b
)
Boolean deprecated

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

Deprecated: Use ModelList or a custom ArrayList subclass

<p>Default comparator for items stored in this list. Used by remove().</p>

Parameters:

  • a Mixed

    <p><p><p><p><p><p>item to test equivalence with.</p></p></p></p></p></p>

  • b Mixed

    <p><p><p><p><p><p>other item to test equivalance.</p></p></p></p></p></p>

Returns:

Boolean:

<p><p><p><p><p><p>true if items are deemed equivalent.</p></p></p></p></p></p>

remove

(
  • index
)
Widget

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

Parameters:

  • index Number

    <p><p>(Optional.) Number representing the index of the child to be removed.</p></p>

Returns:

Widget:

<p><p>Widget instance that was successfully removed, otherwise undefined.</p></p>

removeAll

() ArrayList

Removes all of the children from the Widget.

Returns:

ArrayList:

<p><p>Y.ArrayList instance containing Widgets that were successfully removed. If no children where removed, will return an empty Y.ArrayList instance.</p></p>

selectAll

()

Selects all children.

selectChild

(
  • i
)

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

Parameters:

  • i Number

    <p><p>the index of the child to be selected</p></p>

size

() Integer

<p>How many items are in this list?</p>

Returns:

Integer:

<p><p><p><p><p><p>Number of items in the list</p></p></p></p></p></p>

some

(
  • fn
  • context
)
Boolean

<p><p>Execute a function on each item of the list, optionally providing a custom execution context. Default context is the item.</p></p> <p><p>The callback signature is <code>callback( item, index )</code>.</p></p> <p><p>Unlike <code>each</code>, if the callback returns true, the iteration will stop.</p></p>

Parameters:

  • fn Function

    <p><p><p><p><p><p>the function to execute</p></p></p></p></p></p>

  • context Mixed

    <p><p><p><p><p><p>optional override 'this' in the function</p></p></p></p></p></p>

Returns:

Boolean:

<p><p><p><p><p><p>True if the function returned true on an item</p></p></p></p></p></p>

toJSON

() Array

<p>Provides an array-like representation for JSON.stringify.</p>

Returns:

Array:

<p><p><p><p><p><p>an array representation of the ArrayList</p></p></p></p></p></p>

Properties

_childrenContainer

Node protected

<p>By default WidgetParent will render it's children to the parent's content box.</p>

<p>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.</p>

Attributes

activeDescendant

Widget readonly

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

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 <code>multiple</code> attribute of the root widget in the object hierarchy.

Default: false

selection

ArrayList | Widget readonly

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

Events

addChild

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. <p> Subscribers to the "on" moment of this event, will be notified before a child is added. </p> <p> Subscribers to the "after" moment of this event, will be notified after a child is added. </p>

Event Payload:

removeChild

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. <p> Subscribers to the "on" moment of this event, will be notified before a child is removed. </p> <p> Subscribers to the "after" moment of this event, will be notified after a child is removed. </p>

Event Payload: