WinJS.UI.ListView object

Displays data items in a customizable list or grid.

Syntax

<div data-win-control="WinJS.UI.ListView"></div>
var object = new WinJS.UI.ListView(parentObject, options);

Members

The ListView object has these types of members:

  • Constructors
  • Events
  • Methods
  • Properties

Constructors

The ListView object has these constructors.

Constructor Description
ListView

Creates a new ListView.

 

Events

The ListView object has these events.

Event Description
oncontentanimating

Raised when the ListView is about to play an entrance or contentTransition animation.

onfootervisibilitychanged

Raised when the footer's visibility property changes.

ongroupheaderinvoked

Raised when the user taps or clicks a group header.

onheadervisibilitychanged

Raised when the header's visibility property changes.

onitemdragbetween

Raised when the ListView is a drop target and the onitemdragenter has been disabled. This is raised every time the cursor is moved between a new pair of items. If you call preventDefault on this event, then the ListView doesn't move the items slightly above/below the cursor to provide visual feedback for a drop.

onitemdragchanged

Raised when the user is dragging an item from the ListView and the itemDataSource changes while the user is dragging.

onitemdragdrop

Raised when an item is dropped onto the ListView as the result of a drag operation.

onitemdragend

Raised when the user drops an item dragged from a ListView.

onitemdragenter

Raised when an dragged item enters the bounds of the ListView control.

onitemdragleave

Raised when a draggable item leaves the bounds of a ListView control.

onitemdragstart

Raised when the user begins to drag an item from a ListView control.

oniteminvoked

Raised when the user taps or clicks an item.

onkeyboardnavigating

Raised when the focused item changes.

onloadingstatechanged

Raised when the ListView control's loadingState changes.

onselectionchanged

Raised after the current selection changes.

onselectionchanging

Raised just before the current selection changes.

 

Methods

The ListView object has these methods.

Method Description
addEventListener

Registers an event handler for the specified event.

dispatchEvent

Raises an event of the specified type and with additional properties.

dispose

Releases resources held by this object. Call this method when the object is no longer needed. After calling this method, the object becomes unusable.

elementFromIndex

Returns the DOM element that represents the item at the specified index.

ensureVisible

Makes the item at the specified index visible. If necessary, the ListView will scroll to the item.

forceLayout

Forces the ListView to update its layout. Use this method when you make the ListView visible again after its style.display property had been set to "none".

indexOfElement

Returns the index of the item that the specified DOM element displays.

loadMorePages

Loads the next set of pages if the ListView control's loadingBehavior is set to "incremental" (otherwise, it does nothing). The number of pages to be loaded is determined by the pagesToLoad property.

recalculateItemPosition

Repositions all the visible items in the ListView to adjust for items whose sizes have changed. Most apps won'’t ever need to call this method. For more info, see the Remarks section.

removeEventListener

Removes an event handler that the addEventListener method registered.

triggerDispose

Triggers the ListView disposal service manually.

 

Properties

The ListView object has these properties.

Property Access type Description

automaticallyLoadPages

Read/write

Gets or sets a value that indicates whether the next set of pages is automatically loaded when the user scrolls beyond the number of pages specified by the pagesToLoadThreshold property.

currentItem

Read/write

Gets or sets an object that indicates which item should have keyboard focus and the focus state of that item.

element

Read-only

Gets the DOM element that hosts this ListView.

footer

Read/write

Gets or sets the HTML element that contains the footer.

groupDataSource

Read/write

Gets or sets the data source that contains the groups for the items in the itemDataSource.

groupHeaderTapBehavior

Read/write

Gets or sets how the ListView reacts when the user taps or clicks a group header.

groupHeaderTemplate

Read/write

Gets or sets the Template or function that creates the DOM elements for each group header in the groupDataSource. Each group header can contain multiple elements, but it must have a single root element.

header

Read/write

Gets or sets the HTML element that contains the header.

indexOfFirstVisible

Read/write

Gets or sets the first visible item.

indexOfLastVisible

Read-only

Gets the index of the last visible item in the ListView.

itemDataSource

Read/write

Gets or sets the data source that provides the ListView with items.

itemsDraggable

Read/write

Gets or sets a value that specifies whether items can be dragged. When this is set to true, the ListView provides built in behaviors related to item dragging.

itemsReorderable

Read/write

Gets or sets a value that specifies whether the ListView control's items can be reordered within itself by dragging and dropping.

itemTemplate

Read/write

Gets or sets the WinJS.Binding.Template or templating function that creates the DOM elements for each item in the itemDataSource. Each item can contain multiple elements, but it must have a single root element.

layout

Read/write

Gets or sets an object that controls the layout of the ListView.

loadingBehavior

Read/write

Gets or sets a value that specifies how the ListView fetches items and adds and removes them to the DOM. Don't change the value of this property after the ListView has begun loading data.

loadingState

Read-only

Gets a value that indicates whether the ListView is still loading or whether loading is complete.

maxDeferredItemCleanup

Read/write

Gets or sets the maximum number of realized items.

maxLeadingPages

Read/write

Gets or sets the maximum number of pages to prefetch for the leading buffer.

maxTrailingPages

Read/write

Gets or sets the maximum number of pages to prefetch for the trailing buffer.

pagesToLoad

Read/write

Gets or sets the number of pages to load when the loadingBehavior property is set to "incremental" and the user scrolls beyond the threshold specified by the pagesToLoadThreshold property.

pagesToLoadThreshold

Read/write

Gets or sets the threshold (in pages) for initiating an incremental load. When the last visible item is within the specified number of pages from the end of the loaded portion of the list, and if automaticallyLoadPages is true and loadingBehavior is set to "incremental", the ListView initiates an incremental load.

resetGroupHeader

Read/write

Gets or sets the function that is called when the ListView discards or recycles the element representation of a group header.

resetItem

Read/write

Gets or sets the function that is called when an item is removed, an item is changed, or an item falls outside of the realized range of the ListView.

scrollPosition

Read/write

Gets or sets the distance, in pixels, of the start of the viewable area within the viewport.

selection

Read-only

Gets an ISelection that contains the range of currently selected items.

selectionMode

Read/write

Gets or sets a value that specifies how many ListView items can be selected.

swipeBehavior

Read/write

Gets or sets how the ListView reacts to the swipe gesture. The swipe gesture can select the swiped items or can have no effect on the current selection.

tapBehavior

Read/write

Gets or sets how the ListView reacts when the user taps or clicks an item.

zoomableView

Read-only

Gets a ZoomableView that supports semantic zoom functionality. This API supports the semantic zoom infrastructure and is not intended to be used directly from your code.

 

Remarks

The ListView can accept data from several different types of sources, such as Really Simple Syndication (RSS) feeds or lists of images. To learn how to create your first ListView, see the Add a ListView Quickstart.

Items in a ListView control can contain other controls, but they can't contain a FlipView or another ListView.

Asynchronous function issue

ListView can be used in an asynchronous environment except when using embedded components that only support synchronous functionality (such as Repeater).

Styling the ListView

CSS classes

To customize the ListView, you can define your own styles for these Cascading Style Sheets (CSS) classes (defined by the Windows Library for JavaScript style sheets):

Note  

  • Windows 8.1 In previous versions of Windows, ListView items can be styled using the CSS selector .win-container .win-item. Starting with Windows 8.1, another element contains items within the ListView, and so CSS selectors to style items need to be written as .win-container .win-itembox .win-item.
  • Windows 8.1 In Windows 8.1, the win-groupheader CSS class introduces noticeable margins in an app. Use win-groupleader instead.

 

CSS class Description

win-container

Styles the container for an item in the ListView.

win-container-even

Styles the container for even item in the ListView.

win-container-odd

Styles the container for odd item in the ListView.

win-groupheader

Styles the group headers of a ListView that contains group information.

win-item

Styles items in the ListView.

win-listview

Styles the entire ListView.

win-progress

Styles the progress indicator of the ListView.

win-selectionbackground

Styles the background of an item's selection checkmark.

win-selectioncheckmark

Styles an item's selection checkmark.

win-surface

Styles the scrollable region of the ListView.

win-viewport

Styles the viewport of the ListView.

 

Note  Some of these classes (such as win-item) are used by multiple WinJS controls. To apply a style to just the ListView, add .win-listview to the style selector. For more info, see Styling the ListView and its items.

 

Setting the ListView control's height

The ListView does not dynamically adjust its height to fit your content. For a ListView to render, you must specify an absolute value for its height. The WinJS style sheets set the ListView control's height to 400 pixels.

This example overrides the default style for ListView controls and sets their height to 500 pixels.

.win-listview 
{
    height: 500px; 
}

The win-listview class is a class defined by the WinJS that you can use to style the ListView. The example you just saw changes the height of every ListView to 500 pixels. To change just one ListView, add the ID of the ListView control's hosting div element to the selector. This example changes the height of the ListView with the ID "basicListView".

#basicListView.win-listview 
{
    height: 500px; 
}

Maximum number of items

The ListView doesn't support more than 1.5 million pixels worth of items.

Detaching the ListView from the DOM

Don't use a ListView control after you've detached it from the DOM. When you detach a ListView from the DOM, it starts releasing resources to free up memory and won't work properly anymore.

Using a ListView in a PageControl

When you use a ListView inside a PageControl, add this code to your PageControl object's ready method to ensure that the ListView gets the correct reading order:

element.setAttribute("dir", window.getComputedStyle(this._element, null).direction);

Examples

This example creates an item template and a ListView.

<div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template">
    <div style="width: 282px; height: 70px; padding: 5px; overflow: hidden; display: -ms-grid;">

        <!-- Displays the "picture" field. -->
        <img data-win-bind="alt: title; src: picture"
            src="#"
            style="width: 60px; height: 60px; margin: 5px; -ms-grid-column: 1;" />
        <div style="margin: 5px; -ms-grid-column: 2">

            <!-- Displays the "title" field. -->
            <h4 data-win-bind="innerText: title"></h4>

            <!-- Displays the "text" field. -->
            <h6 data-win-bind="innerText: text"></h6>
        </div>
    </div>
</div>

<div id="basicListView" data-win-control="WinJS.UI.ListView"
    data-win-options="{itemDataSource : DataExample.itemList.dataSource, 
    itemTemplate: select('#mediumListIconTextTemplate'),
    layout : {type: WinJS.UI.GridLayout}}">
</div>

The next example defines the data for the ListView in a separate JavaScript file. For the ListView to access the data, add a reference to the JavaScript file to the HTML page that contains the ListView.

// data.js
(function () {
    "use strict";

    var dataArray = [
    { title: "Basic banana", text: "Low-fat frozen yogurt", picture: "images/60banana.png" },
    { title: "Banana blast", text: "Ice cream", picture: "images/60banana.png" },
    { title: "Brilliant banana", text: "Frozen custard", picture: "images/60banana.png" },
    { title: "Orange surprise", text: "Sherbet", picture: "images/60orange.png" },
    { title: "Original orange", text: "Sherbet", picture: "images/60orange.png" },
    { title: "Vanilla", text: "Ice cream", picture: "images/60vanilla.png" },
    { title: "Very vanilla", text: "Frozen custard", picture: "images/60vanilla.png" },
    { title: "Marvelous mint", text: "Gelato", picture: "images/60mint.png" },
    { title: "Succulent strawberry", text: "Sorbet", picture: "images/60strawberry.png" }
    ];

    var itemList = new WinJS.Binding.List(dataArray);

    // Create a namespace to make the data publicly
    // accessible. 
    var publicMembers =
        {
            itemList: itemList
        };
    WinJS.Namespace.define("DataExample", publicMembers);

})();

For a full walkthrough of the code and more info about creating your first ListView, see Quickstart: Add a ListView.

Requirements

Minimum WinJS version

WinJS 1.0

Namespace

WinJS.UI

See also

Quickstart: Add a ListView

Styling the ListView and its items

HTML ListView essentials sample (Windows)

HTML ListView item templates sample (Windows)

HTML ListView grouping and SemanticZoom sample (Windows)