Share via


WinJS.UI.SettingsFlyout object

[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

See also

Quickstart: Adding app settings using Windows Library for JavaScript

Quickstart: Add app settings (Windows Store apps using C#/VB/C++ and XAML)

App settings sample