WinJS.UI.ToolBar object

Article
01/26/2017

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

Partager via