Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
MSDN Library
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

WinJS.UI.AppBar object

Applies to Windows and Windows Phone

The application toolbar used to display commands (AppBarCommand) that are relevant to the user's context, typically the current page or the current selection.

Explore this functionality in more depth as part of our App features, start to finish series:  Flat navigation, start to finish (HTML) and Hierarchical navigation, start to finish (HTML)

Syntax


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


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

Members

The AppBar object has these types of members:

Constructors

The AppBar object has these constructors.

ConstructorDescription
AppBar

Creates a new AppBar object.

 

Events

The AppBar object has these events.

EventDescription
onafterclose

Occurs immediately after the AppBar is hidden.

onafteropen

Occurs immediately after the AppBar is displayed.

onbeforeclose

Occurs immediately before the AppBar is hidden

onbeforeopen

Occurs immediately before a closed AppBar is displayed.

 

Methods

The AppBar object has these methods.

MethodDescription
addEventListener

Registers an event handler for the specified event.

close

Closes the app bar on Windows and the secondary command menu on Windows Phone.

dispatchEvent

Raises an event of the specified type and with additional properties.

dispose

Releases resources held by this AppBar. Call this method when the AppBar is no longer needed. After calling this method, the AppBar becomes unusable.

getCommandById

Returns the AppBarCommand object identified by id.

open

If the app bar is not disabled, opens the app bar on Windows and opens the secondary command menu on Windows Phone

removeEventListener

Removes an event handler that the addEventListener method registered.

showOnlyCommands

Shows the specified commands in the AppBar while hiding all other commands.

 

Properties

The AppBar object has these properties.

PropertyAccess typeDescription

closedDisplayMode

Read/write

Gets or sets how the AppBar is displayed while hidden.

commands

Write-only

Gets and sets the AppBarCommand objects that appear in the app bar.

element

Read-only

Gets the DOM element that hosts the AppBar.

opened

Read-only

Gets a value that indicates whether the AppBar is opened or in the process of becoming opened.

placement

Read/write

Gets or sets a value that specifies whether the AppBar appears at the top or bottom of the main display view.

 

Remarks

Known Issues

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

Styling the AppBar

CSS classes

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

CSS classDescription

win-appbar

Styles an AppBar that uses a custom layout.

win-appbar-closed

Styles the AppBar when it is closed.

win-command

Styles commands within the AppBar.

win-commandicon

Styles the icon box for AppBar commands.

win-commandimage

Styles the images for AppBar commands.

win-commandring

Styles the icon rings for AppBar commands.

win-label

Styles labels for AppBar commands.

win-reduced

Styles commands to shrink (or drop labels) based on the window size and the number of visible AppBar buttons.

 

Note  There are several CSS classes that are shared between multiple WinJS controls. To limit your custom styles to a specific control, assign the control an ID or custom class name and use that as part of your style selector.
 

For a list of icons that you can use in an AppBar, see AppBarIcon.

The AppBar control observes the following conventions when interacting with the AppBarCommand.section property:

  • "primary" is for primary commands that should appear in the AppBar’s action area.

    Depending on the AppBar.closedDisplayMode property, primary commands in the action area can remain visible even when the AppBar is closed.

    If there is not enough room in the action area to fit all primary commands, the commands with the weakest priority order, (as determined by the AppBarCommand.priority property) will move into the overflow area and appear as secondary commands.

  • "secondary" is for commands that always appear in the overflow area.

Examples

Here we show how to declare an app bar that contains each of the supported AppBarCommand types.


<!-- Define the app bar -->
<div id="appBar" 
     data-win-control="WinJS.UI.AppBar" 
     data-win-options="{placement:'bottom'}">
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'secondary1',
            type:'button',
            label:'Secondary1',
            section:'secondary'}"></button>
    <div data-win-control="WinJS.UI.AppBarCommand"
         data-win-options="{ id: 'list',
         type: 'content',
         label:'List',
         section: 'secondary'}">
        <select class="options">
            <option>Option1</option>
            <option>Option2</option>
            <option>Option3</option>
            <option>Option4</option>
        </select>
    </div>
    <div data-win-control="WinJS.UI.AppBarCommand"
         data-win-options="{ id: 'textfield',
         type: 'content',
         label:'Text field',
         section: 'secondary' }">
        <input type="text" value="Text" />
    </div>
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'flyoutButton',
            type:'flyout',
            label:'Flyout',
            icon:'openpane',
            section: 'secondary',
            flyout:select('#exampleFlyout')}"></button>
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'cmdToggle',
            type:'toggle',
            label:'Toggle',
            icon:'audio',
            section:'primary',
            tooltip:'Toggle'}"></button>
    <hr data-win-control="WinJS.UI.AppBarCommand"
        data-win-options="{id:'separator',
        type:'separator',
        section:'primary'}" />
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'helpButton',
            type: 'button',
            label:'Help',
            tooltip:'Help',
            icon:'help',
            section:'primary'
            }"></button>
</div>


Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

Minimum supported phone

Windows Phone 8.1

Namespace

WinJS.UI

Library

Ui.js

See also

WinJS.UI Namespace
AppBarCommand
AppBarIcon
BackButton
NavBar
Your first app - Part 3: PageControl objects and navigation
Navigating between pages (HTML)
Adding app bars
Adding nav bars
HTML AppBar control sample
HTML NavBar control sample
Navigation and navigation history sample
Designers
Command patterns
Navigation patterns
Guidelines for app bars
Bottom app bar
Top app bar

 

 

Show:
© 2015 Microsoft