Yahoo! UI Library

widget-parent  3.3.0pr1

Yahoo! UI Library > widget-parent > WidgetParent
Search:
 
Filters

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.

Classes

Properties

Copyright © 2010 Yahoo! Inc. All rights reserved.