ToolBar Overview

ToolBar controls are containers for a group of commands or controls which are typically related in their function. A ToolBar usually contains buttons which invoke commands.

This topic contains the following sections.

• ToolBar Control
• Specifying the Position of ToolBars in a ToolBarTray
• ToolBars with Overflow Items
• Related Topics

ToolBar Control

The ToolBar control takes its name from the bar-like arrangement of buttons or other controls into a single row or column. WPF ToolBar controls provide an overflow mechanism which places any items that do not fit naturally within a size-constrained ToolBar into a special overflow area. Also, WPF ToolBar controls are usually used with the related ToolBarTray control, which provides special layout behavior as well as support for user-initiated sizing and arranging of toolbars.

Specifying the Position of ToolBars in a ToolBarTray

Use the Band and BandIndex properties to position the ToolBar in the ToolBarTray. Band indicates the position in which the ToolBar is placed within its parent ToolBarTray. BandIndex indicates the order in which the ToolBar is placed within its band. The following example shows how use this property 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>

ToolBars with Overflow Items

Often ToolBar controls contain more items than can fit into the toolbar's size. When this happens, the ToolBar displays an overflow button. To see the overflow items, a user clicks the overflow button and the items are shown in a pop-up window below the ToolBar. The following graphic shows a ToolBar with overflow items.

Toolbar with Overflow Items

You can specify 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 is responsible for the layout of the items on the toolbar. The ToolBarOverflowPanel is responsible for the layout of the items that do not fit on the ToolBar. For an example of a ControlTemplate for a ToolBar, see

ToolBar Styles and Templates.

See Also

Tasks

How to: Style Controls on a ToolBar

Reference

ToolBarPanel

ToolBarOverflowPanel

Other Resources

WPF Controls Gallery Sample