WinJS.UI.AppBarCommand object

Article
01/26/2017

A command to be displayed in an app bar (AppBar).

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

<button data-win-control="WinJS.UI.AppBarCommand"></button>

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

Members

The AppBarCommand object has these types of members:

Constructors
Methods
Properties

Constructors

The AppBarCommand object has these constructors.

Constructor	Description
AppBarCommand	Creates a new AppBarCommand object.

Methods

The AppBarCommand object has these methods.

Method	Description
addEventListener	Registers an event handler for the specified event.
dispose	Releases resources held by the AppBarCommand. Call this method when the AppBarCommand is no longer needed. After calling this method, the AppBarCommand becomes unusable.
removeEventListener	Removes an event handler registered with addEventListener.

Properties

The AppBarCommand object has these properties.

Property	Access type	Description
disabled	Read/write	Gets or sets a value that indicates whether the AppBarCommand is disabled.
element	Read-only	Gets the DOM element that hosts the AppBarCommand.
extraClass	Read/write	Gets or sets additional CSS classes to apply to the element that hosts the AppBarCommand.
firstElementFocus	Read/write	Gets or sets keyboard navigation behavior in the app bar for AppBarCommand elements of type "content". This property identifies the element that receives focus within the AppBarCommand host <div> (or container) when navigating from the left.
flyout	Read/write	Gets or sets a Flyout object that is displayed when the AppBarCommand is invoked.
hidden	Read-only	Gets or sets a value that indicates whether the AppBarCommand is hidden.
icon	Read/write	Gets or sets the AppBarCommand identifier.
id	Read-only	Gets or sets the AppBarCommand identifier.
label	Read/write	Gets or sets the AppBarCommand label.
lastElementFocus	Read/write	Gets or sets keyboard navigation behavior in the app bar for AppBarCommand elements of type "content". This property identifies the element that receives focus within the AppBarCommand host <div> (or container) when navigating from the right.
onclick	Read/write	Gets or sets the event handler function invoked when the AppBarCommand is clicked.
priority	Read/write	Gets or sets the priority of the command.
section	Read-only	Gets or sets the section of the AppBar that hosts this AppBarCommand.
selected	Read/write	Gets or sets the selected state of an AppBarCommand of type "toggle".
tooltip	Read/write	Gets or sets the tooltip of the AppBarCommand.
type	Read/write	Gets or sets the type of the command.

Remarks

Styling the AppBarCommand

CSS classes

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

CSS class	Description
win-command	Styles the entire AppBarCommand.
win-commandicon	Styles the icon box for the AppBarCommand.
win-commandimage	Styles the image for the AppBarCommand.
win-commandring	Styles the icon ring for the AppBarCommand.
win-label	Styles the label for the AppBarCommand.

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 on an AppBar, see AppBarIcon.

Examples

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

AppBarCommand can be one of these types (see type):

"button"
"toggle"
"flyout"
"separator"
"content"

<!-- Standard app bar -->
<!-- Define the example flyout command for the app bar -->
<div id="exampleFlyout" 
     data-win-control="WinJS.UI.Flyout" aria-label="{Example flyout}">
     <div>This is an example AppBarCommand of type 'flyout'.</div>
     <button id="exampleFlyoutButton">Example flyout</button>
</div>
<!-- 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