WinJS.UI.ToolBar object

Displays a set of commands. A ToolBar can appear in any location, including in a Flyout or an AppBar.

Syntax

<div data-win-control="WinJS.UI.ToolBar"></div>
var object = new WinJS.UI.ToolBar();

Members

The ToolBar object has these types of members:

  • Constructors
  • Events
  • Methods
  • Properties

Constructors

The ToolBar object has these constructors.

Constructor Description
Toolbar

Creates a new Toolbar.

Events

The ToolBar object has these events.

Event Description
onafterclose

Occurs immediately after the ToolBar is closed.

onafteropen

Occurs immediately after the ToolBar is opened.

onbeforeclose

Occurs immediately before the ToolBar is closed.

onbeforeopen

Occurs immediately before the ToolBar is opened.

Methods

The ToolBar object has these methods.

Method Description
addEventListener

Adds an event listener to the ToolBar.

close

Closes the ToolBar.

dispatchEvent

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

dispose

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

forceLayout

Forces the Toolbar to update its layout and redraws the control.

open

Opens the ToolBar.

removeEventListener

Removes an event listener that the addEventListener method registered for the ToolBar.

Properties

The ToolBar object has these properties.

Property Access type Description

closedDisplayMode

Read/write

closedDisplayMode gets or sets the display options for the actionarea when the ToolBar is closed.

data

Read/write

Gets or sets a List of Command objects to display.

element

Read-only

Gets the DOM element that hosts the Toolbar.

extraClass

Read/write

extraClass is no longer available. Gets or appends additional CSS classes to apply to the element that hosts the Toolbar.

opened

Read/write

Gets or sets whether the ToolBar is currently opened.

shownDisplayMode

Read/write

shownDisplayMode is no longer available. Gets or sets a value that specifies how to display overflow content.

Remarks

Known issues

Unlike other overlaying controls (i.e. AppBar, NavBar, Flyout, Menu, SplitView, SettingsFlyout, and ContentDialogue), ToolBars are not subject to stacking context issues that can mask event detection. This means that they can be children of elements other than document.body. However, there is one tradeoff that comes with this capability: ToolBars must always be statically positioned.

The action and overflow areas

This diagram shows the parts of a standard ToolBar:

Part Description

1.

The action area, where primary commands are displayed.

2.

The show more button ("...") that users touch or click to display the overflow area.

3.

The overflow area, which contains the commands that couldn't fit into the action area or that are designated secondary commands.

By default, the ToolBar displays as many commands as possible in the action area. Commands that don't fit in the action area appear in the ToolBar control's overflow area.

When space is limited, the ToolBar moves commands at the end of the list or with lower priority values to the overflow area. You can use the commands' section property to influence whether they appear in the action area or the overflow area. If you want the command to appear in the action area (if space permits), set its section to "primary". If you want a command to always appear in the overflow area (regardless of whether there is space in the action area), set its section property to "secondary".

CSS classes

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

CSS class Description

win-toolbar

Styles the entire ToolBar.

win-toolbar-actionarea

Styles the action area of the ToolBar.

win-toolbar-overflowarea

Styles the overflow area of the ToolBar.

win-toolbar-overflowareabutton

Styles the view more ("...") button.

Requirements

Minimum WinJS version

WinJS 4.0

Namespace

WinJS.UI

See also

Command