WinJS.UI.Flyout object

Article
01/26/2017

Displays a lightweight popup that is used to temporarily show UI related to what the user is currently doing. It can be used to reveal a hidden control, show more details about an item, or ask the user to confirm an action. You should only show a flyout in response to a user tap or click. Unlike a MessageDialog, a flyout is always dismissed when the user taps or clicks outside of it.

Note Use a context menu, not a flyout, for contextual actions on a text selection.

Syntax

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

var object = new WinJS.UI.Flyout(element, options);

Members

The Flyout object has these types of members:

Constructors
Events
Methods
Properties

Constructors

The Flyout object has these constructors.

Constructor	Description
Flyout	Creates a new Flyout object.

Events

The Flyout object has these events.

Event	Description
onafterhide Event	Occurs immediately after the Flyout is hidden.
onaftershow Event	Occurs immediately after the Flyout is displayed.
onbeforehide Event	Occurs before the Flyout is hidden
onbeforeshow Event	Occurs immediately before a hidden Flyout is displayed.

Methods

The Flyout object has these methods.

Method	Description
addEventListener	Registers an event handler for the specified event.
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.
hide Method	Hides the Flyout, if visible, regardless of other states.
removeEventListener	Removes an event handler that the addEventListener method registered.
show Method	Shows the Flyout, if hidden, regardless of other states.
showat	Shows the Flyout, if hidden, regardless of other states, top and left aligned at specified coordinates or at the location of the mouse event object.

Properties

The Flyout object has these properties.

Property	Access type	Description
alignment	Read/write	Gets or sets the default alignment to be used for this Flyout relative to its anchor element.
anchor	Read/write	Gets or sets the default anchor to be used for this Flyout.
element	Read-only	Gets the DOM element that hosts the Flyout.
hidden	Read-only	Gets a value that indicates whether the Flyout is hidden or in the process of becoming hidden.
placement	Read/write	Gets or sets the placement to be used for this Flyout relative to the target object.

Remarks

Known Issues

Flyouts should be direct children of document.body. Otherwise, it is possible to mask event detection on the Flyout due to stacking context effects. This is because event detection for other elements is blocked while the Flyout is open. So, if the Flyout is a child of one of those blocked elements, it too will be blocked. This behavior is typical for all overlaying controls.

CSS classes

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

CSS class	Description
win-flyout	Styles the entire Flyout.

Examples

The following example shows how to use a flyout to change app settings. You should add the flyout as a direct child of the <body> element. For the complete example, see HTML flyout control sample.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
    <link rel="stylesheet" href="/css/change-settings.css" />
    <script src="/js/change-settings.js"></script>
</head>
<body>
    <div data-win-control="SdkSample.ScenarioInput">
        <p>
            If there are a small number of settings contextual to a particular object in the
            app rather than the app itself, then use a flyout to commit those settings. 
            Changes should be reflected as soon as the user makes a change.</p>
        <p>
            Click the 'Format output text' button to launch the output text Settings flyout.
        </p>
        <button id="formatTextButton" class="action">
            Format output text</button>
    </div>
    <div data-win-control="SdkSample.ScenarioOutput">
        <p id="outputText">
            Format this text.</p>
        <div id="formatTextFlyout" data-win-control="WinJS.UI.Flyout" 
             aria-label="{Format text flyout}">
            <label for="textColor">
                Text color</label>
            <br />
            <select id="textColor">
                <option value="black">Black</option>
                <option value="red">Red</option>
                <option value="green">Green</option>
                <option value="blue">Blue</option>
                <option value="purple">Purple</option>
            </select>
            <br />
            <label for="textSize">
                Size</label>
            <br />
            <input type="range" id="textSize" min="6" max="75" value="11" />
        </div>
    </div>
</body>
</html>

(function () {
    "use strict";
    var page = WinJS.UI.Pages.define("/html/change-settings.html", {
        ready: function (element, options) {
            document.getElementById("formatTextButton").addEventListener(
                "click", showFormatTextFlyout, false);
            document.getElementById("textColor").addEventListener(
                "change", changeColor, false);
            document.getElementById("textSize").addEventListener(
                "change", changeSize, false);
        }
    });

    // Show the flyout
    function showFormatTextFlyout() {
        var formatTextButton = document.getElementById("formatTextButton");
        document.getElementById("formatTextFlyout").winControl.show(formatTextButton);
    }

    // Change the text color
    function changeColor() {
        document.getElementById("outputText").style.color = document.getElementById(
            "textColor").value;
    }

    // Change the text size
    function changeSize() {
        document.getElementById("outputText").style.fontSize = document.getElementById(
        "textSize").value + "pt";
    }
})();

Requirements

Minimum WinJS version	WinJS 1.0
Namespace	WinJS.UI

Share via