WinJS.UI.Flyout object

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.

Styling the Flyout

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

See also

WinJS.UI Namespace

Menu

MenuCommand

Displaying popups

Laying out your UI

HTML flyout control sample

Designers

Command patterns

Flyout

Guidelines for flyouts

Context menu

Guidelines for context menus