WinJS.UI.AppBar object

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
  • Events
  • Methods
  • Properties

Constructors

The AppBar object has these constructors.

Constructor Description
AppBar

Creates a new AppBar object.

 

Events

The AppBar object has these events.

Event Description
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.

Method Description
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.

Property Access type Description

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.

data

Read/write

Gets or sets a List of Command objects to display.

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 class Description

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 WinJS version

WinJS 1.0

Namespace

WinJS.UI

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