WinJS.UI.ListView object (Windows)

10 out of 16 rated this helpful - Rate this topic

Displays data items in a customizable list or grid.

Syntax


<div data-win-control="WinJS.UI.ListView"></div>

JavaScript


var object = new WinJS.UI.ListView(parentObject, options);

Members

The ListView object has these types of members:

Events
Methods
Properties

Events

The ListView object has these events.

Event	Description
oncontentanimating	Occurs when the ListView is about to play an entrance or contentTransition animation.
oniteminvoked	Occurs when the user taps or clicks an item.
onkeyboardnavigating	Raised when the focused item changes.
onloadingstatechanged	Occurs when the ListView switches between a loading and a ready state.
onselectionchanged	Occurs after the current selection changes.
onselectionchanging	Occurs 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.
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 function when making 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.
ListView	Creates a new ListView.
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	Trigger the ListView disposal service manually.

Properties

The ListView object has these properties.

Property	Description
automaticallyLoadPages	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	Gets or sets an object that indicates which item should get keyboard focus and its focus state.
element	Gets the HTML element that hosts this ListView.
groupDataSource	Gets or sets the data source that contains the groups for the items in the itemDataSource.
groupHeaderTemplate	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.
indexOfFirstVisible	Gets or sets the first visible item.
indexOfLastVisible	Gets the index of the last visible item in the ListView.
itemDataSource	Gets or sets the data source that provides the ListView with items.
itemTemplate	Gets or sets the Template or 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	Gets or sets an object that controls the layout of the ListView.
loadingBehavior	Gets or sets a value that specifies how many items are loaded into the DOM. Don't change the value of this property after the ListView has begun loading data.
loadingState	Gets a value that indicates whether the ListView is still loading or whether loading is complete.
pagesToLoad	Gets or sets the number of pages to load when the user scrolls beyond the threshold the pagesToLoadThreshold property specifies if the loadingBehavior property is set to "incremental".
pagesToLoadThreshold	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	Gets or sets the function that is called when the ListView recycles the element representation of a group header.
resetItem	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	Gets or sets the distance, in pixels, between the first item in the list and the current viewable area.
selection	Gets an ISelection that contains the range of currently selected items.
selectionMode	Gets or sets the selection mode of the ListView.
swipeBehavior	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	Gets or sets how the ListView reacts when the user taps or clicks an item.
zoomableView	Gets a ZoomableView that supports semantic zoom functionality. This API supports the SemanticZoom 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 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.

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):

CSS class	Description
win-container	Styles the container for an 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 that some of these classes (such as win-item) are used by multiple Windows Library for JavaScript controls. To apply a style to just the ListView, add .win-listview to the style selector.

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 Windows Library for JavaScript 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.

CSS


.win-listview 
{
    height: 500px; 
}

The win-listview class is a class defined by the Windows Library for JavaScript 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".

CSS


#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:

JavaScript


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

Examples

This example creates an item template and a ListView.

HTML


    <div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template">
        <div>

            <!-- Displays the "picture" field. -->
            <img data-win-bind="alt: title; src: picture" />
            <div>

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

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

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

JavaScript


(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 dataList = new WinJS.Binding.List(dataArray);

    // Create a namespace to make the data publicly
    // accessible. 
    var publicMembers =
        {
            itemList: dataList 
        };
    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 supported client	Windows 8 [Windows Store apps only]
Minimum supported server	Windows Server 2012 [Windows Store apps only]
Namespace	WinJS.UI
Library	Ui.js

WinJS.UI.ListView object

Syntax

Members

Events

Methods

Properties

Remarks

Styling the ListView

CSS classes

Setting the ListView control's height

Maximum number of items

Detaching the ListView from the DOM

Using a ListView in a PageControl

Examples

Requirements

See also