OOUI/Toolbars

Toolbars are complex interface components that permit users to easily access a variety of tools (e.g., formatting commands) and actions, which are additional commands that are part of the toolbar, but not configured as tools.

Developers create and customize the individual tools, which are then registered with a tool factory, which creates the tools on demand. Each tool has a symbolic name (used when registering the tool), a title (e.g., ‘Insert picture’), and an icon.

Individual tools are organized in tool groups, which are displayed as menus of tools, lists of tools, or as a single bar of tools. The arrangement and order of the tool groups is customized when the toolbar is set up. Tools can be presented in any order, but each can only appear once in the toolbar.

The following is an example of a basic toolbar. We will be looking more closely at each of the components making up this example later in this documentation. To see this demo live, please see the code-generated documentation.

Tools
Tools are created by extending the abstract Tool class or one of its subclasses, PopupTool or ToolGroupTool. Each tool must be configured with a static name, title, and icon property: In addition to the static properties, tools must also specify the following two methods:
 * name: The static name is used internally to register the tool with a ToolFactory. Tools must be registered with a tool factory before they can be used in a toolbar.
 * title: The title text is used in different ways depending on the type of group the tool is placed inside (ToolBarGroup, ToolMenuGroup, or ToolListGroup). For ‘bar’ groups, where only an icon is displayed to identify the tool, the title text is used as a tooltip that is displayed when a user moves the mouse over the tool. For ‘list’ groups, the title text is used to identify the tool in the dropdown menus used in the user interface. If a keyboard shortcut has been defined for the tool, the shortcut will automatically be displayed. For tools in ‘bar’ and ‘list’ groups, the keyboard shortcut is displayed in a tooltip; for tools in ‘menu’ groups, the shortcut appears to the right of each menu item.
 * icon: The icon is also used in different ways depending on the type of group that the tool is inside. For ‘bar’ groups, the icon is displayed in the toolbar to identify the tool. For ‘list’ groups, the icon is displayed beside the title text in the dropdown menu. For ‘menu’ groups, the icon is ignored.
 * onSelect, used to specify the action the tool will carry out when it is selected


 * onUpdateState, used to synchronize the state of the tool with the state of its larger context. For example, this method could be used to select the ‘bold’ tool in the toolbar when the text cursor is moved inside an area of bolded text.

For a complete list of supported methods and configuration options, please see the code-level documentation for the Tool class.

Adding shadows
Documentation for toolbars is currently under construction. In the meantime, for more information, please see:
 * code-generated documentation for OO.ui.Toolbar, which has an annotated example of a simple toolbar
 * The OOjs UI demo, which has additional examples (see the source)