Controls
FoundationListControl
Control for showing a list of items.
- Object
- SitedObject
- Control
- ContainerControl
- ListControl
Remarks
ListControl is a very flexible control for generating lists of items - generating
tables, ordered/unordered lists, or even simple sequences of paragraphs.
Properties
| ID_allowDrag | Specifies if dragging a drag handle in the list initiates a drag and drop. |
| ID_animators (inherited from Control) | A SitedList of animators. |
| ID_childControls (inherited from ContainerControl) | A SitedList of child controls. |
| ID_columns | |
| ID_controlId (inherited from Control) | The ID this control is known in the nearest binding container parent. |
| ID_dragOpacity | Opacity of items during drag and drop operations. |
| ID_dropOrientation | |
| ID_dropTypeName | |
| ID_dropTypeNames | |
| ID_eventMask (inherited from Control) | (Advanced) A comma-separated list of peer events this control should receive. |
| ID_isBindingContainer (inherited from Control) | (Advanced) Force this control to act as a binding container. |
| ID_isDropTarget | |
| ID_isPeerless (inherited from Control) | (Advanced) Set this to true to prevent this control from generating a peer element in the rendered HTML. |
| ID_items | The data items to show in the list. |
| ID_multiSelectedItems | The list items that are currently multi-selected. |
| ID_selectedIndex | The index of the selected item in the list. |
| ID_selectedItem | The currently selected item in the list. |
| ID_submitters (inherited from Control) | A SitedList of submitters. |
| ID_tagName (inherited from Control) | Overrides the default HTML tag name used for this control. |
| ID_template | |
| ID_templates | |
| ID_visible (inherited from Control) | True if this control is visible, false if it is hidden. |
Events
| ID_mouseDown (inherited from Control) | Event handler called when a mouse button is pressed down. |
| ID_mouseMove (inherited from Control) | Event handler called when the mouse is moved. |
| ID_mouseOut (inherited from Control) | Event handler called when a leaves a control. |
| ID_mouseOver (inherited from Control) | Event handler called when a mouse moves over a control. |
| ID_mouseUp (inherited from Control) | Event handler called when a mouse button is released. |
Methods
| acceptsDrop | (Override) Called to determine if this control will accept a drop. |
| addBinding (inherited from Control) | Adds a databinding between a property on this object and a binding path. |
| addBindingEx (inherited from Control) | Extended entry point for adding a binding. |
| addCalculatedBinding (inherited from Control) | Adds a calculated binding for a property. |
| addChild (inherited from ContainerControl) | Add a child control to this ContainerControl. |
| addClassName (inherited from Control) | Adds a CSS class to this controls "class" attribute |
| addEventHandler (inherited from SitedObject) | Adds a delegate to be called when the specified eventId occurs on this object. |
| animateEx (inherited from Control) | Animates a property to a value. |
| blur (inherited from Control) | Tells this control's peer to relinquish keyboard focus. |
| bubble (inherited from Control) | Bubbles a message up the control hierarchy - calls onBubbleEvent on this control and each of its parents. |
| captureMouse (inherited from Control) | Register a control to receive mouse move/up events |
| construct (inherited from Control) | Used to initialize a markup control. |
| equals (inherited from SitedObject) | Tests if two objects are equal. |
| fireEventHandler (inherited from SitedObject) | Invokes any user event handlers registered for a particular event using SitedObject.addEventHandler(). |
| focus (inherited from Control) | Tells this control's peer to request keyboard focus. |
| getBindingContainer (inherited from Control) | Gets this object's nearest enclosing binding container. |
| getBindingStatus (inherited from SitedObject) | Provides debugging information on bindings for this object. |
| getChild (inherited from ContainerControl) | Gets the n'th child |
| getEventMask (inherited from Control) | Gets an object indicating which peer events this control is interested in. |
| getParent (inherited from Control) | Gets the parent Control of this control. |
| getPathValue (inherited from SitedObject) | Traverses a binding path and returns the value at the end of it. |
| getPeer (inherited from Control) | Gets the peer DOM element associated with this control. |
| getPeerForParent (inherited from Control) | Gets the peer element of this control that the parent control should use in DOM manipulations. |
| getPropertyInfo (inherited from SitedObject) | Gets information on a property. |
| getResource (inherited from Control) | Given the ID of a resource, returns the resource's value. |
| getSite (inherited from SitedObject) | Gets this object's site. |
| getTagName | (Override) Picks the tag name to use for the list. |
| getValue (inherited from Control) | Gets a property, style or attribute. |
| getViewState (inherited from Control) | Retrieve any viewstate that has been saved for this control in a previous session. |
| getViewStateId (inherited from Control) | Get a unique and consistent viewstateId for this control. |
| invalidateLayout (inherited from Control) | Tells the layout system to redo layout. |
| modifyDOM (inherited from ContainerControl) | Called to manipulate the DOM peer node of this control. |
| onBubbleEvent | (Override) Called to handle a bubbled event. |
| onDragEvent | (Override) Called to handle a drag drop event.. |
| onFirstRender | (Override) Called the first time a control is rendered. |
| onPeerCreated (inherited from Control) | Called when a peer is created. |
| onPeerEvent (inherited from Control) | Called to dispatch low level events that arise in the Dom. |
| onSetValue | (Override) Called by SitedObject.setValue() when a property value is set on this object. |
| onSited (inherited from SitedObject) | Called when this object is sited. |
| onSitedRoot (inherited from Control) | Called when a control is added to the main control tree. |
| onUnsited (inherited from SitedObject) | Called when this object is about to lose its site. |
| onUnsitedRoot (inherited from Control) | Called when a control is removed from the main control tree. |
| onValueSited (inherited from ContainerControl) | Called when an object is sited within this object. |
| onValueUnsited (inherited from ContainerControl) | Called when an object is about to be unsited in this. |
| onViewStateChanged (inherited from Control) | Overridable. Controls implement this method to update their viewstate. |
| rebuildInnerHtml (inherited from ContainerControl) | Updates this controls innerHTML. |
| reflectOnBoundValue (inherited from Control) | Gets runtime reflection information on an underlying bound object. |
| removeChild (inherited from ContainerControl) | Remove a child control from this ContainerControl. |
| removeClassName (inherited from Control) | Removes a CSS class from this controls "class" attribute |
| removeEventHandler (inherited from SitedObject) | Remove an existing delegate from the list of delegates for the specified event. |
| render (inherited from Control) | Places the Html representation of this control into the htmlBuilder. |
| renderAttributes (inherited from Control) | Called by Control.render() to render attributes for this control. |
| renderChildren (inherited from ContainerControl) | Places the Html markup for all the Control inside this control into the htmlBuilder. |
| selectItem | Selects the specified item in the list. |
| setBounds (inherited from Control) | Convenience method to set the left/top/width/height of an element. |
| setInitialValues (inherited from SitedObject) | Sets multiple property values on an object (during initialization only) |
| setPathValue (inherited from SitedObject) | Traverses a binding path and sets the value at the end of it. |
| setValue (inherited from Control) | Sets a property, style or attribute. |
| setViewState (inherited from Control) | Save viewstate that should persist across sessions. |
| startAnimator (inherited from Control) | Starts an animation. |
| startDragDrop (inherited from Control) | Start a drag drop operation. |
| stopAnimator (inherited from Control) | Stops an animation. |
| toString (inherited from SitedObject) | Returns a string representation of this object. |
ListControl acceptsDrop method (override)
Called to determine if this control will accept a drop.
JavaScript
listControl.acceptsDrop(dragEventArgs)
Remarks
Used to support ID_allowDrag.
Returns
true if the drop is acceptable, false otherwise.
Base Implementation
ListControl getTagName method (override)
Picks the tag name to use for the list.
JavaScript
listControl.getTagName()
Remarks
If the ID_tagName property is set, this returns the value of that property.
Otherwise, this returns "div".
Returns
An HTML tag name string, e.g. "span", "tr", "div" etc.
Base Implementation
ListControl ID_allowDrag property
Specifies if dragging a drag handle in the list initiates a drag and drop.
JavaScript
var boolVal = listControl.getValue(ID_allowDrag)
listControl.setValue(ID_allowDrag, boolVal)
Xml
<j:List allowDrag="true" ... >
or
<j:List allowDrag="false" ... >
Remarks
If ID_allowDrag is true, and the user presses the mouse button down on an item tagged with ID_isDragHandle, then the list initiates a drag and drop operation. If ID_allowDrag is false, the list does not support using drag and drop to rearrange the items.
For this to work, you must set Expandos.ID_isDragHandle attribute on one of the children in the list template.
ListControl ID_columns property
JavaScript
var intVal = listControl.getValue(ID_columns)
listControl.setValue(ID_columns, intVal)
Xml
<j:List columns="int" ... >
ListControl ID_dragOpacity property
Opacity of items during drag and drop operations.
JavaScript
var numValue = listControl.getValue(ID_dragOpacity)
listControl.setValue(ID_dragOpacity, numValue)
Xml
<j:List dragOpacity="float" ... >
Remarks
This specifies the opacity of dragged items during a drag and drop operation.
If this is 1.0 (the default), dragged items are fully opaque.
If this is less than 1.0, dragged items are semi-transparent.
If this is 0.0, dragged items are invisible.
Not all browsers support opacity.
ListControl ID_dropOrientation property
JavaScript
var idname = listControl.getValue(ID_dropOrientation)
listControl.setValue(ID_dropOrientation, idname)
Xml
<j:List dropOrientation="vertical" ... >
or
<j:List dropOrientation="horizontal" ... >
ListControl ID_dropTypeName property
JavaScript
var strVal = listControl.getValue(ID_dropTypeName)
listControl.setValue(ID_dropTypeName, strVal)
Xml
<j:List dropTypeName="string" ... >
ListControl ID_dropTypeNames property
JavaScript
var stringList = listControl.getValue(ID_dropTypeNames)
listControl.setValue(ID_dropTypeNames, stringList)
Xml
<j:List>
<j:dropTypeNames>
<j:di>string</j:di>
<j:di>string</j:di>
...
<j:/dropTypeNames>
</j:List>
ListControl ID_isDropTarget property
JavaScript
var boolVal = listControl.getValue(ID_isDropTarget)
listControl.setValue(ID_isDropTarget, boolVal)
Xml
<j:List isDropTarget="true" ... >
or
<j:List isDropTarget="false" ... >
ListControl ID_items property
The data items to show in the list.
JavaScript
var objectList = listControl.getValue(ID_items)
listControl.setValue(ID_items, objectList)
Xml
<j:List>
<j:items>
<j:di type="typeName">object</j:di>
<j:di type="typeName">object</j:di>
...
<j:/items>
</j:List>
Remarks
This can be set either to a JavaScript Array, a
a SitedList or a DataList. When set,
ListControl iterates over the list and stamps out a
template for each item in the list. If the list is a
SitedList or a DataList, then ListControl registers listeners
to listen for changes to the list and automatically rebuild the
presentation.
Example
In Xml, items are usualy specified using a databinding:
<j:List items="#bind(data.notes)"/>
In JavaScript, you use setValue to set the list items:
var list = new ListControl(); list.setValue(ID_items, ['Apple','Orange']);
If you use a SitedList, then the ListControl automatically updates if the SitedList changes:
var items = new SitedList('Apple', 'Orange');
var listControl = new ListControl();
listControl.setValue(ID_items, items);
// now if you change the items the list updates automatically.
items.add('Tangerine');ListControl ID_multiSelectedItems property
The list items that are currently multi-selected.
JavaScript
var obj = listControl.getValue(ID_multiSelectedItems)
listControl.setValue(ID_multiSelectedItems, obj)
Xml
<j:List>
<j:multiSelectedItems j:type="typeName">
object
<j:/multiSelectedItems>
</j:List>
Remarks
ListControl supports two independent selection mechanisms: ID_selectedItem/ID_selectedIndex are used to select a single item, e.g. to show details for an item in a Details control.
ID_multiSelectedItems is used to select multiple items - e.g. to select a set of list items to delete.
When you change ID_multiSelectedItems, this does not effect ID_selectedItem/ID_selectedIndex.
Typically, applications add a checkbox to the ListControl template's and specify bubble events on the checkbox to update the ID_multiSelectedItems list when the user clicks on the checkbox.
See Also
ListControl ID_selectedIndex property
The index of the selected item in the list.
JavaScript
var intVal = listControl.getValue(ID_selectedIndex)
listControl.setValue(ID_selectedIndex, intVal)
Xml
<j:List selectedIndex="int" ... >
Remarks
This is -1 if no item is selected.
ListControl ID_selectedItem property
The currently selected item in the list.
JavaScript
var obj = listControl.getValue(ID_selectedItem)
listControl.setValue(ID_selectedItem, obj)
Xml
<j:List>
<j:selectedItem j:type="typeName">
object
<j:/selectedItem>
</j:List>
ListControl ID_template property
JavaScript
var template = listControl.getValue(ID_template)
listControl.setValue(ID_template, template)
Xml
<j:List>
<j:template>
Template
<j:/template>
</j:List>
ListControl ID_templates property
JavaScript
var templateList = listControl.getValue(ID_templates)
listControl.setValue(ID_templates, templateList)
Xml
<j:List>
<j:templates>
<j:Template ... />
<j:Template ... />
...
<j:/templates>
</j:List>
ListControl onBubbleEvent method (override)
Called to handle a bubbled event.
JavaScript
listControl.onBubbleEvent(sender,bubbleEventArgs)
Remarks
This listens for the following bubbled events:
| ID_selectItem | Determines which child bubbled up the event, and selects the item associated with that child. |
| ID_dragButtonDown | Initiates a drag-and-drop interaction on the item associated with the control that bubbled the event. |
Returns
true if dispatching should continue to look for an event handler,
false if the event was "consumed" and dispatching should stop.
Base Implementation
See Also
ListControl onDragEvent method (override)
Called to handle a drag drop event..
JavaScript
listControl.onDragEvent(eventId,dragEventArgs)
Remarks
Adds support for dragging items in lists, if ID_allowDrag is true.
Base Implementation
ListControl onFirstRender method (override)
Called the first time a control is rendered.
JavaScript
listControl.onFirstRender()
ListControl onSetValue method (override)
Called by SitedObject.setValue() when a property value is set
on this object.
JavaScript
listControl.onSetValue(propertyId,oldVal,newVal,notificationSource)
Remarks
Used to listen for changes to ID_items, ID_selectedIndex,
ID_selectedItem, or ID_multiSelectedItems.
Base Implementation
ListControl selectItem method
Selects the specified item in the list.
JavaScript
listControl.selectItem(item)