Class WidgetParent
Widget extension providing functionality enabling a Widget to be a
parent of another Widget.
Properties
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
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.
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.
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.
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.
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.
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.
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 type
property of the configuration object
literal.
- Parameters:
-
config
<Object>
Object literal representing the configuration
used to create an instance of a Widget.
protected
void
_defAddChildFn
(
event
,
child
,
index
)
Default childAdded 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.
protected
void
_defRemoveChildFn
(
event
,
child
,
index
)
Default childRemoved 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.
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.
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.
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.
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.
protected
void
_uiRemoveChild
(
child
)
Updates the UI in response to a child being removed.
- Parameters:
-
child
<Widget>
The child Widget instance to render.
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.
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.
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.
-
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.
void
deselectAll
(
)
Deselects all children.
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.
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.
void
selectAll
(
)
Selects all children.
void
selectChild
(
i
)
Selects the child at the given index (zero-based).
- Parameters:
-
i
<Number>
the index of the child to be selected
Events
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
childAdded
(
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.
childRemoved
(
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.
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
(
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
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
Returns the Widget's currently focused descendant Widget.
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.