Class: SC.ListView


Extends SC.CollectionRowDelegate, SC.CollectionView.

A list view renders vertical or horizontal lists of items. It is a specialized form of collection view that is simpler than a table view, but more refined than a generic collection.

You can use a list view just like any collection view, except that often you provide the rowSize, which will be either the height of each row when laying out rows vertically (the default) or the widht of each row when laying out the rows horizontally.

Variable Row Heights

Normally you set the row height or width through the rowSize property, but you can also support custom row sizes by assigning the customRowSizeIndexes property to an index set of all custom sized rows.

Using ListView with Very Large Data Sets

ListView implements incremental rendering, which means it will only render HTML for the items that are currently visible on the screen. This means you can use it to efficiently render lists with 100K+ items or more very efficiently.

If you need to work with very large lists of items however, be aware that calculating variable row sizes can become very expensive since the list view will essentially have to iterate over every item in the collection to determine each the total height or width.

Therefore, to work with very large lists, you should consider using a design that allows your row sizes to remain uniform. This will allow the list view to much more efficiently render content.

Alternatively, to support differently sized and incrementally rendered item views, you may want to consider overriding the offsetForRowAtContentIndex() and rowSizeForContentIndex() methods to perform some specialized faster calculations that do not require inspecting every item in the collection.

Note: row sizes and offsets are cached so once they are calculated the list view will be able to display very quickly.

Dragging and Dropping

When the list view is configured to accept drops onto its items, it will set the isDropTarget property on the target item accordingly. This allows you to modify the appearance of the drop target list item accordingly (@see SC.ListItemView#isDropTarget).

Defined in: list.js

Since:
SproutCore 1.0

Field Summary

Fields borrowed from SC.CollectionView:
action, ACTION_DELAY, actOnSelect, allContentIndexes, calculatedHeight, calculatedWidth, canDeleteContent, canEditContent, canReorderContent, content, contentDelegate, contentExampleViewKey, contentGroupExampleViewKey, contentValueKey, delegate, displayProperties, dragContent, dragDataTypes, exampleView, groupExampleView, isActive, isDropTarget, isEditable, isEnabled, isSelectable, length, nowShowing, proposedDropOperation, proposedInsertionIndex, renderDelegateName, reorderDataType, rightIconAction, rightIconTarget, selection, selectionDelegate, selectOnMouseDown, target, useFastPath, useToggleSelection
Fields borrowed from SC.View:
acceptsMultitouch, ariaHidden, ariaRole, attributeBindings, autoMixins, backgroundColor, childViewLayout, childViewLayoutOptions, childViews, childViewsNeedLayout, classNameBindings, concatenatedProperties, createdByParent, designMode, enabledState, firstKeyView, hasLayout, hasTouch, hasVisibility, isBuildingIn, isBuildingOut, isChildViewLayoutLive, isFixedHeight, isFixedPosition, isFixedSize, isFixedWidth, isKeyResponder, isTextSelectable, isView, isVisible, lastKeyView, layerLocationNeedsUpdate, layerNeedsUpdate, modeAdjust, nextKeyView, page, pane, parentView, previousKeyView, shouldInheritCursor, shouldInheritEnabled, tagName, themeName, toolTip, touchBoundary, transitionAdjust, transitionAdjustOptions, transitionHide, transitionHideOptions, transitionIn, transitionInOptions, transitionOut, transitionOutOptions, transitionShow, transitionShowOptions, useStaticLayout
Fields borrowed from SC.Responder:
hasFirstResponder, isFirstResponder, responderContext
Fields borrowed from SC.Object:
isDestroyed, isObject, nextProperty, object, property, toInvalidate
Fields borrowed from SC.Observable:
isObservable

Instance Methods

Field Detail

acceptsFirstResponder Boolean
Default value:
true
classNames Array
Default value:
['sc-list-view']
See:
SC.View#classNames
insertionPointView SC.View

Default view class used to draw an insertion point, which uses CSS styling to show a horizontal line.

This view's position (top & left) will be automatically adjusted to the point of insertion.

layoutDirection String

Determines the layout direction of the rows of items, either vertically or horizontally. Possible values:

  • SC.LAYOUT_HORIZONTAL
  • SC.LAYOUT_VERTICAL
Default value:
SC.LAYOUT_VERTICAL
rowDelegate Object
Deprecated:

Version 1.11. Please use the rowSizeForContentIndex() function instead. Not implemented by default.

rowHeightForContentIndex Number
showAlternatingRows Boolean

If set to true, the default theme will show alternating rows for the views this ListView created through exampleView property.

Default value:
false

Instance Method Detail

computeLayout()

The layout for a ListView is computed from the total number of rows along with any custom row heights.

contentIndexesInRect(rect)

Override to return an IndexSet with the indexes that are at least partially visible in the passed rectangle. This method is used by the default implementation of computeNowShowing() to determine the new nowShowing range after a scroll.

Override this method to implement incremental rendering.

The default simply returns the current content length.

Parameters:
rect Rect
the visible rect or a point
Returns:
SC.IndexSet
now showing indexes
hideInsertionPoint()
insertionIndexForLocation(loc, dropOperation)

Compute the insertion index for the passed location. The location is a point, relative to the top/left corner of the receiver view. The return value is an index plus a dropOperation, which is computed as such:

  • if outlining is not used and you are within 5px of an edge, DROP_BEFORE the item after the edge.
  • if outlining is used and you are within 5px of an edge and the previous item has a different outline level then the next item, then DROP_AFTER the previous item if you are closer to that outline level.
  • if dropOperation = SC.DROP_ON and you are over the middle of a row, then use DROP_ON.
Parameters:
loc
dropOperation
See:
SC.CollectionView.insertionIndexForLocation
layout(key, value)
Parameters:
key
value
layoutForContentIndex(contentIndex)

Computes the layout for a specific content index by combining the current row heights.

Parameters:
contentIndex Number
Returns:
Hash
layout hash for the index provided
Deprecated:

Version 1.11. Please use the rowSizeDidChangeForIndexes() function instead. Call this method whenever a row height has changed in one or more indexes. This will invalidate the row height cache and reload the content indexes. Pass either an index set or a single index number.

This method is called automatically whenever you change the rowSize, rowPadding or customRowSizeIndexes properties on the collectionRowDelegate.

rowHeightDidChangeForIndexes(indexes)
Parameters:
indexes SC.IndexSet|Number
Returns:
SC.ListView
receiver
rowOffsetForContentIndex(idx)

Returns the top or left offset for the specified content index. This will take into account any custom row sizes and group views.

Parameters:
idx Number
the content index
Returns:
Number
the row offset
rowSizeDidChangeForIndexes(indexes)

Call this method whenever a row size has changed in one or more indexes. This will invalidate the row size cache and reload the content indexes. Pass either an index set or a single index number.

This method is called automatically whenever you change the rowSize, rowPadding or customRowSizeIndexes properties on the collectionRowDelegate.

Parameters:
indexes SC.IndexSet|Number
Returns:
SC.ListView
receiver
rowSizeForContentIndex(idx)

Returns the row size for the specified content index. This will take into account custom row sizes and group rows.

Parameters:
idx Number
content index
Returns:
Number
the row height
showInsertionPoint(itemView, dropOperation)
Default implementation will show an insertion point
Parameters:
itemView
dropOperation
See:
SC.CollectionView#showInsertionPoint
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)