ListView.layout property

Article
01/26/2017

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

Syntax

<div 
    data-win-control="WinJS.UI.ListView" 
    data-win-options="{ layout : {type: WinJS.UI.GridLayout}}" >
</div>
- or -
<div 
    data-win-control="WinJS.UI.ListView" 
   data-win-options="{ layout : {type: WinJS.UI.ListLayout}}" >
</div>

var layout = listView.layout;
listView.layout = layout;

Property value

Type: Object

A GridLayout or ListLayout object that specifies the layout for the ListView. The default value is a GridLayout object.

Remarks

Groups and cell-spanning are not supported when using a ListLayout. For more info about cell-spanning, see How to display items that are different sizes.

Examples

Note This series of examples applies only to Windows Store apps.

This series of examples switches a ListView control's layout from GridLayout to ListLayout when the app is in portrait mode.

The first example shows the markup for the PageControl that contains the ListView.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>viewStateExample</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.2.0/css/ui-light.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>

    <link href="viewStateExample.css" rel="stylesheet" />
    <script src="viewStateExample.js"></script>
    <script src="/js/data.js"></script>
</head>
<body>


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

            <!-- Displays the "picture" field. -->
            <img class="mediumListIconTextItem-Image"
                src="#"
                data-win-bind="alt: title; src: picture" />
            <div class="mediumListIconTextItem-Detail">
                <h4 data-win-bind="innerText: title"></h4>
                <h6 data-win-bind="innerText: text"></h6>
            </div>
        </div>
    </div>

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

</body>
</html>

When you create a new Visual Studio project that uses the Grid app, Navigation app, or Split app templates and you use a PageControl, you can use the PageControl object's updateLayout method to respond to view state changes. This example shows the JavaScript for the PageControl that contains the ListView. When the view state changes, the example switches to ListLayout when the app is in portrait mode.

// For an introduction to the Page Control template, see the following documentation:
// https://go.microsoft.com/fwlink/?LinkId=232511
(function () {
    "use strict";
 

    WinJS.UI.Pages.define("/pages/viewState/viewStateExample.html", {
        // This function is called whenever a user navigates to this page. It
        // populates the page elements with the app's data.
        ready: function (element, options) {
            // TODO: Initialize the page here.

            // When the page loads, check the view state and
            // use the appropriate layout.

            this.updateLayout(element, Windows.UI.ViewManagement.ApplicationView, null);

        },

        unload: function () {
            // TODO: Respond to navigations away from this page.
        },

        updateLayout: function (element, viewState, lastViewState) {

            // Respond to changes in viewState.

            // Get the ListView control. 
            var viewStateExampleListView =
                element.querySelector("#viewStateExampleListView").winControl;

            // Use a ListLayout if the app is in portrait mode. 
            if (viewState.getForCurrentView().orientation) {

                // If layout.orientation is horizontal, the ListView
                // is already using a ListLayout, so we don't
                // have to do anything. We only need to switch
                // layouts when layout.orientation is horizontal. 
                if (viewStateExampleListView.layout.orientation == "horizontal") {
                    viewStateExampleListView.layout = new WinJS.UI.ListLayout();
                }
            }

                // Use a GridLayout if the app isn't in portrait mode. 
            else {
                // Only switch layouts if layout.orientation is vertical. 
                if (viewStateExampleListView.layout.orientation == "vertical") {
                    viewStateExampleListView.layout = new WinJS.UI.GridLayout();
                }
            }

        }
    });
})();

(If you're not using a PageControl, you can create your own event handler for the window's resize event and use the Windows.UI.ViewManagement.ApplicationView.getForCurrentView method to get the current view. For more info, see Quickstart: Defining app layouts.)

While you have to use JavaScript to change the layout, you can use CSS media queries to adjust the size of the ListView when it's in different view states. This example shows how.

.win-listview
{
    width: 600px;
    height: 300px;
    border: solid 2px rgba(0, 0, 0, 0.13);
}

/* Template for items */  
.mediumListIconTextItem
{
    width: 282px;
    height: 70px;
    padding: 5px;
    overflow: hidden;
    display: -ms-grid;
}

    .mediumListIconTextItem img.mediumListIconTextItem-Image 
    {
        width: 60px;
        height: 60px;
        margin: 5px;
        -ms-grid-column: 1;
    }

    .mediumListIconTextItem .mediumListIconTextItem-Detail
    {
        margin: 5px;
        -ms-grid-column: 2;
    }

/* Change the size of the ListView when the app is snapped. */
@media screen and (-ms-view-state: snapped) {
     .win-listview
    {
        width: 300px;
        height: 300px;
    }
}
/* Change the size of the ListView when the app is in portrait mode. */
@media screen and (-ms-view-state: fullscreen-portrait) {
     .win-listview
    {
        width: 300px;
        height: 600px;
    }
}

Requirements

Minimum WinJS version	WinJS 3.0
Namespace	WinJS.UI