WinJS.UI.GridLayout object

Article
01/26/2017

Represents a grid layout for the ListView in which items are arranged in a horizontal grid.

Syntax

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

var object = new WinJS.UI.GridLayout();

Members

The GridLayout object has these types of members:

Constructors
Methods
Properties

Constructors

The GridLayout object has these constructors.

Constructor	Description
GridLayout Constructor	Creates a new GridLayout object.

Methods

The GridLayout object has these methods.

Method	Description
calculateFirstVisible	This method is no longer supported.
calculateLastVisible	This method is no longer supported.
dragLeave	This API supports the WinJS infrastructure and is not intended to be used directly from your code.
dragOver	This API supports the WinJS infrastructure and is not intended to be used directly from your code.
endLayout Method	This method is no longer supported.
executeAnimations	This API supports the WinJS infrastructure and is not intended to be used directly from your code.
getItemPosition Method	This method is no longer supported.
getKeyboardNavigatedItem	This method is no longer supported.
getScrollbarRange Method	This method is no longer supported.
hitTest Method	This API supports the WinJS infrastructure and is not intended to be used directly from your code.
init Method	This method is no longer supported.
initialize	This API supports the WinJS infrastructure and is not intended to be used directly from your code.
itemsAdded	This method is no longer supported.
itemsFromRange	This API supports the WinJS infrastructure and is not intended to be used directly from your code.
itemsMoved	This method is no longer supported.
itemsRemoved	This method is no longer supported.
layout	This API supports the WinJS infrastructure and is not intended to be used directly from your code.
layoutHeader Method	This method is no longer supported.
layoutItem Method	This method is no longer supported.
prepareHeader	This method is no longer supported.
prepareItem Method	This method is no longer supported.
releaseItem	This method is no longer supported.
reset Method	This method is no longer supported.
setSite Method	This method is no longer supported.
setupAnimations	This API supports the WinJS infrastructure and is not intended to be used directly from your code.
startLayout Method	This method is no longer supported.
uninitialize	This API supports the WinJS infrastructure and is not intended to be used directly from your code.
updateBackdrop	This method is no longer supported.

Properties

The GridLayout object has these properties.

Property	Access type	Description
backdropColor	Read/write	This property is no longer supported. Starting with Windows Library for JavaScript 2.0, use the `.win-listview.win-container.win-backdrop` CSS selector.
disableBackdrop	Read/write	This property is no longer supported. Starting with Windows Library for JavaScript 2.0, use the `.win-listview.win-container.win-backdrop` CSS selector.
groupHeaderPosition Property	Read/write	Gets or sets the position of group headers.
groupInfo Property	Read/write	This property is no longer supported. Starting with the Windows Library for JavaScript 2.0, use a CellSpanningLayout.
horizontal Property	Read-only	This property is no longer supported. Starting with the Windows Library for JavaScript 2.0, use the orientation property instead.
itemInfo	Read/write	This property is no longer supported. Starting with the Windows Library for JavaScript 2.0, use a CellSpanningLayout.
maximumRowsOrColumns	Read/write	Gets or set the maximum number of rows or columns, depending on the orientation, to display before content begins to wrap.
maxRows Property	Read/write	This property is no longer supported. Starting with Windows Library for JavaScript 2.0, use the maximumRowsOrColumns property.
numberOfItemsPerItemsBlock	Read-only	This API supports the WinJS infrastructure and is not intended to be used directly from your code.
orientation	Read/write	Gets or sets the orientation of the GridLayout.

Remarks

This object implements the ILayout interface. Most of the GridLayout methods are for internal use by the ListView control and should not be called directly from your code. However, you can use the GridLayout object's properties.

The GridLayout supports grouped data sources. For more info, see How to group items in a ListView.

The GridLayout supports items that span multiple cells. For more info, 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 snapped or 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

Share via