ListView.onselectionchanging event

Article
01/26/2017

Raised just before the current selection changes.

Syntax

<div data-win-control="WinJS.UI.ListView" 
    data-win-options="{onselectionchanging : handler}">
</div>

function handler(eventInfo) { /* Your code */ }
 
// addEventListener syntax
listView.addEventListener("selectionchanging", handler);
listView.removeEventListener("selectionchanging", handler);
 
- or -

listView.onselectionchanging = handler;

Event information

Synchronous	No
Bubbles	Yes
Cancelable	Yes

Event handler parameters

eventInfo
Type: CustomEvent**

An object that contains info about the event. The detail property of this object contains the following sub-properties:

Property	Meaning
detail.newSelection	An ISelection object that contains the newly selected items. These items are a guess at what might be selected after the user interaction completes.
detail.preventTapBehavior	A function that you can call to prevent the object that contains the ListView item from being selected when the user taps it. It also prevents the user from selecting the item by making a left mouse click or by pressing the Enter key. Calling this function also prevents the pressed animation from playing. The item can still be selected through other actions, such as with a swipe. To prevent the item from being selected in any way, use eventInfo.preventDefault.

detail.newSelection

An ISelection object that contains the newly selected items. These items are a guess at what might be selected after the user interaction completes.

detail.preventTapBehavior

A function that you can call to prevent the object that contains the ListView item from being selected when the user taps it. It also prevents the user from selecting the item by making a left mouse click or by pressing the Enter key. Calling this function also prevents the pressed animation from playing.

The item can still be selected through other actions, such as with a swipe. To prevent the item from being selected in any way, use eventInfo.preventDefault.

Remarks

Warning Don't make changes to the itemDataSource or groupDataSource in your event handler. Instead, call setImmediate from your event handler and pass it a function that makes the changes to the data source.

This event doesn't fire if you delete the data source or reload it.

Avoid performing expensive operations in your event handler

ListView events execute synchronously, so avoid performing expensive operations in your event handler. Performing expensive operations in your event handler can make the ListView seem unresponsive to the user. If you need the event handler to perform an expensive operation, call setImmediate from your event handler and pass it a function that performs the operation or perform the operation as an asynchronous operation. For more info about asynchronous programming, see Asynchronous programming in JavaScript.

Setting event handlers declaratively (in HTML)

To set the event handler declaratively, it must be accessible to the global scope, and you must also call WinJS.Utilities.markSupportedForProcessing or WinJS.UI.eventHandler on the handler. You can make the handler accessible to the global scope by using WinJS.Namespace.define. For more information, see How to set event handlers declaratively.

Updating your AppBar when the selection changes

When the ListView selection changes or is the process of changing, consider the right way to update the your AppBar. For example, if the user selects a ListView item that contains an image, you might display a custom AppBar that shows image editing commands and set the AppBar controls sticky property to true so that it won'’t light dismiss. For info about creating custom AppBar controls, see Quickstart: Adding a custom app bar. For general guidelines for using AppBar controls (such as when to use sticky mode), see the Guidelines and checklist for app bars.

Requirements

Minimum WinJS version	WinJS 3.0
Namespace	WinJS.UI

Share via