WinJS.UI.SettingsFlyout object

Article
01/26/2017

[SettingFlyout is no longer available for use as of Windows Library for JavaScript (WinJS) 4.0 Preview.]

Provides users with fast, in-context access to settings that affect the current Windows Store app.

Syntax

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

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

Members

The SettingsFlyout object has these types of members:

Constructors
Events
Methods
Properties

Constructors

The SettingsFlyout object has these constructors.

Constructor	Description
SettingsFlyout	Creates a new SettingsFlyout object.

Events

The SettingsFlyout object has these events.

Event	Description
onafterhide	Raised immediately after the SettingsFlyout is completely hidden.
onaftershow	Raised immediately after a SettingsFlyout is fully shown.
onbeforehide	Raised just before hiding a SettingsFlyout.
onbeforeshow	Raised just before showing a SettingsFlyout

Methods

The SettingsFlyout object has these methods.

Method	Description
addEventListener	Registers an event handler for the specified event.
dispatchEvent	Raises an event of the specified type and with additional properties.
dispose	Releases resources held by this SettingsFlyout. Call this method when the SettingsFlyout is no longer needed. After calling this method, the SettingsFlyout becomes unusable.
hide	Hides the SettingsFlyout, if visible, regardless of other states.
populateSettings	Loads a fragment of the SettingsFlyout. Your app calls this when the user invokes a settings command and the WinJS.Application.onsettings event occurs.
removeEventListener	Removes an event handler that the addEventListener method registered.
show	Shows the SettingsPane UI, if hidden, regardless of other state.
showSettings	Show the Settings flyout using the Settings element identifier (ID) and the path of the page that contains the Settings element.

Properties

The SettingsFlyout object has these properties.

Property	Access type	Description
element	Read-only	Gets the DOM element the SettingsFlyout is attached to.
hidden	Read-only	Gets whether the SettingsFlyout is hidden.
settingsCommandId	Read/write	Gets or sets the settings command Id for the SettingsFlyout control.
width	Read/write	This property may be unavailable or altered in future versions. Use the CSS width property of the element that has the `win-settingsflyout` class instead.

Remarks

Styling the SettingsFlyout

CSS classes

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

CSS class	Description
win-settingsflyout	Styles the entire SettingsFlyout control.

Examples

The following example shows how to create a Settings flyout. For the full example, see App settings sample. (The sample contains a JavaScript and HTML example, as well as VB/C#/C++ and XAML examples.)

<!doctype HTML>
<html>
    <head>
        <title>App Settings flyout</title>
    </head>
    <body>
        <!-- BEGINSETTINGSFLYOUT -->
        <div data-win-control="WinJS.UI.SettingsFlyout" 
             aria-label="App Settings flyout" 
             data-win-options="{settingsCommandId:'defaults',width:'wide'}">
            <!-- Use either 'win-ui-light' or 'win-ui-dark' depending on the contrast between the header title and background color -->
            <div 
                class="win-ui-dark win-header" 
                style="background-color:#00b2f0"> <!-- Background color reflects app's personality -->
                <button type="button" onclick="WinJS.UI.SettingsFlyout.show()" 
                    class="win-backbutton"></button>
                <div class="win-label">Defaults</div>
                <img src="../images/smallTile-sdk.png" 
                    style="position: absolute; right: 40px;"/>
            </div>
            <div class="win-content">
                <div class="win-settings-section">
                    <h3>Toggle switch</h3>
                    <p>Use toggle switches to let users set Boolean values.</p>
                    <div id="Toggle1" data-win-control="WinJS.UI.ToggleSwitch" 
                        data-win-options="{title:'Download updates automatically',checked:true}">
                    </div>
                    <div id="Toggle2" data-win-control="WinJS.UI.ToggleSwitch" 
                        data-win-options="{title:'Install updates automatically'}">
                    </div>
                </div>
                <div class="win-settings-section">
                    <h3>Push button</h3>
                    <p>With a push button, users initiate an immediate action.</p>
                    <label>Button label</label>
                    <button type="button" onclick="WinJS.log && WinJS.log(
                        'Clear history button pressed', 'samples', 'status')">Clear</button>
                </div>
                <div class="win-settings-section">
                    <h3>Select control</h3>
                    <p>Use the select control to allow users to select one item 
                       from a set of text-only items.</p>
                    <label>State</label>
                    <select aria-label="State select control">
                        <option value="AK">Alaska</option>
                        <option value="CA">California</option>
                        <option value="CO">Colorado</option>
                        <option value="HI">Hawaii</option>
                        <option value="ID">Idaho</option>
                        <option value="KS">Kansas</option>
                        <option value="MT">Montana</option>
                        <option value="NE">Nebraska</option>
                        <option value="NV">Nevada</option>
                        <option value="NM">New Mexico</option>
                        <option value="ND">North Dakota</option>
                        <option value="OR">Oregon</option>
                        <option value="SD">South Dakota</option>
                        <option value="TX">Texas</option>
                        <option value="UT">Utah</option>
                        <option value="WA" selected>Washington</option>
                        <option value="WY">Wyoming</option>
                    </select>
                </div>
                <div class="win-settings-section">
                    <h3>Hyperlink</h3>
                    <p>Use a hyperlink when the associated action will take the user out of 
                       this flyout.</p>
                    <a href="https://go.microsoft.com/fwlink/p/?linkid=190175" 
                       target="fix_link_too">View privacy statement</a>
                </div>
                <div class="win-settings-section">
                    <h3>Text input box</h3>
                    <p>Use a text input box to allow users to enter text. Set the type of 
                       the text input box according to the type of text you're capturing 
                       from the user (e.g. email or password).</p>
                    <label>Email account</label>
                    <input type="text" aria-label="Enter email account" />
                    <button type="button" onclick="WinJS.log && WinJS.log(
                    'Add email account button pressed', 'samples', 'status')">Add</button>
                </div>
                <div class="win-settings-section">
                    <h3>Radio button group</h3>
                    <p>Lets users choose one item from a small set of mutually exclusive, 
                       related options.</p>
                    <label>Video quality</label>
                    <label><input type="radio" name="video" value="High" checked />High</label>
                    <label><input type="radio" name="video" value="Medium" />Medium</label>
                    <label><input type="radio" name="video" value="Low" />Low</label>
                </div>
            </div>
        </div>
        <!-- ENDSETTINGSFLYOUT -->
    </body>
</html>

Requirements

Minimum WinJS version	WinJS 1.0
Namespace	WinJS.UI