ToolBar

The ToolBar control is a container for a group of commands or controls that are typically related in their function. It usually contains buttons that invoke commands and arranges them in a bar-like layout into a single row or column.

The ToolBar control provides an overflow mechanism that places items that don't fit within a size-constrained toolbar into a special overflow area. You typically use ToolBar controls with the related ToolBarTray control, which provides special layout behavior and supports user-initiated sizing and arranging of toolbars.

Position ToolBars in a ToolBarTray

Use the Band and BandIndex properties to position the ToolBar in the ToolBarTray. The Band property indicates the position where the ToolBar is placed within its parent ToolBarTray. The BandIndex property indicates the order where the ToolBar is placed within its band. The following example shows how to use these properties to place ToolBar controls inside a ToolBarTray.

<ToolBarTray Background="White">
  <ToolBar Band="1" BandIndex="1">
    <Button>
      <Image Source="toolbargraphics\cut.bmp" />
    </Button>
    <Button>
      <Image Source="toolbargraphics\copy.bmp" />
    </Button>
    <Button>
      <Image Source="toolbargraphics\paste.bmp" />
    </Button>
  </ToolBar>
  <ToolBar Band="2" BandIndex="1">
    <Button>
      <Image Source="toolbargraphics\undo.bmp" />
    </Button>
    <Button>
      <Image Source="toolbargraphics\redo.bmp" />
    </Button>
  </ToolBar>
  <ToolBar Band="2" BandIndex="2">
    <Button>
      <Image Source="toolbargraphics\paint.bmp" />
    </Button>
    <Button>
      <Image Source="toolbargraphics\spell.bmp" />
    </Button>
    <Separator/>
    <Button>
      <Image Source="toolbargraphics\save.bmp" />
    </Button>
    <Button>
      <Image Source="toolbargraphics\open.bmp" />
    </Button>
  </ToolBar>
</ToolBarTray>

Handle overflow items

A ToolBar control often contains more items than can fit into the toolbar's size. When this happens, the toolbar displays an overflow button. To see the overflow items, click the overflow button and the items appear in a pop-up window below the toolbar. The following image shows a toolbar with overflow items.

Control when an item on a toolbar is placed on the overflow panel by setting the ToolBar.OverflowMode attached property to OverflowMode.Always, OverflowMode.Never, or OverflowMode.AsNeeded. The following example specifies that the last four buttons on the toolbar should always be on the overflow panel.

<ToolBarTray Background="White">
  <ToolBar Band="1" BandIndex="1">
    <Button>
      <Image Source="toolbargraphics\cut.bmp" />
    </Button>
    <Button>
      <Image Source="toolbargraphics\copy.bmp" />
    </Button>
    <Button>
      <Image Source="toolbargraphics\paste.bmp" />
    </Button>
    <Button>
      <Image Source="toolbargraphics\undo.bmp" />
    </Button>
    <Button>
      <Image Source="toolbargraphics\redo.bmp" />
    </Button>
    <Button>
      <Image Source="toolbargraphics\paint.bmp" />
    </Button>
    <Button>
      <Image Source="toolbargraphics\spell.bmp" />
    </Button>
    <Separator/>
    <Button ToolBar.OverflowMode="Always">
      <Image Source="toolbargraphics\save.bmp" />
    </Button>
    <Button ToolBar.OverflowMode="Always">
      <Image Source="toolbargraphics\open.bmp" />
    </Button>
    <Button ToolBar.OverflowMode="Always">
      <Image Source="toolbargraphics\print.bmp" />
    </Button>
    <Button ToolBar.OverflowMode="Always">
      <Image Source="toolbargraphics\preview.bmp" />
    </Button>
  </ToolBar>
</ToolBarTray>

The ToolBar uses a ToolBarPanel and a ToolBarOverflowPanel in its ControlTemplate. The ToolBarPanel handles the layout of the items on the toolbar. The ToolBarOverflowPanel handles the layout of the items that don't fit on the toolbar.

Styles and templates

You can modify the default ControlTemplate to give the control a unique appearance. For more information, see What are styles and templates? and How to create a template for a control.

Content property

The ToolBar control uses the Items property as its content property. This property allows you to add child items to the toolbar, which are typically buttons or other controls that invoke commands.

Parts

The following table lists the named parts for the ToolBar control.

When you create a ControlTemplate for a ToolBar, your template might contain an ItemsPresenter within a ScrollViewer. The ItemsPresenter displays each item in the toolbar, and the ScrollViewer enables scrolling within the control. If the ItemsPresenter isn't the direct child of the ScrollViewer, you must give the ItemsPresenter the name ItemsPresenter.

Visual states

This control doesn't define any visual states.

See also

• Style controls on a toolbar
• WPF Controls Gallery Sample
• ToolBarOverflowPanel
• ToolBarPanel
• ToolBar
• ToolBarTray