Contents Up Previous Next

Toolbar overview

Classes: wxToolBar, wxButtonBar

The wxToolBar class gives wxWindows programs an extra, and increasingly popular, user interface component: a set of bitmap buttons or toggles. A toolbar gives faster access to an application's facilities than menus, which have to be popped up and selected rather laboriously. Besides which, a toolbar looks prettier than a purely menu-based interface.

wxToolBar uses a canvas subwindow for drawing bitmaps, and so bitmap images cannot be mixed with panel items, but in most cases this won't be important. A toolbar might appear as a single row of images under the menubar, or it might be in a separate frame layout in several rows and columns. The class handles the layout of the images, unless explicit positioning is requested.

A tool is a bitmap which can either be a button (there is no 'state', it just generates an event when clicked) or it can be a toggle. If a toggle, a second bitmap can be provided to depict the 'on' state; if the second bitmap is omitted, either the inverse of the first bitmap will be used (for monochrome displays) or a thick border is drawn around the bitmap (for colour displays where inverting will not have the desired result).

Mouse click events for a given button are sent to a member called OnLeftClick, and so an application must derive from wxToolBar in order to use it. The application can also handle OnMouseEnter events for the tools, to give the user extra feedback about the tools as the mouse moves over them.


This toolbar class does not give as slick an appearance as, or the responsiveness of, conventional Windows toolbars. The buttons are not given a 3D appearance and do not depress like normal buttons. However, you can use the optimized wxButtonBar library for greatly improved Windows behaviour, and behaviour under X identical to wxToolBar. See The wxButtonBar library.

Using the toolbar library
The wxButtonBar library


Using the toolbar library

Include the file wx_tbar.h to use this class.

An example of toolbar use is given in the sample program contained in test.cc and test.h. This creates a main window, and two toolbars: a floating toolbar with 24 tools, and a toolbar along the top of the main drawing canvas, divided into groups. The icons for this second toolbar would normally be quite small.

The test program defines a general-purpose derived frame called wxFrameWithToolBar which can manage a frame with one main subwindow and one horizontal toolbar.

Note that one of the bitmaps on the floating toolbar is a small version of the main graphic: this demonstrates how a memory device context can be used to draw into a bitmap. An application which allowed the user to build up a symbol library dynamically might create this kind of bitmap.

Left clicks and movements over the toolbars are intercepted and information is displayed on the status line.

The following fragment illustrates the essence of creating a toolbar.

  toolBarBitmaps[0] = new wxBitmap("icon1");
  toolBarBitmaps[1] = new wxBitmap("icon2");
  toolBarBitmaps[2] = new wxBitmap("icon3");
  ...

  toolBarFrame = new wxFrame(NULL, "Tools", 0, 0, 300, 200,
    wxSDI | wxDEFAULT_FRAME | wxSTAY_ON_TOP);

  // 5 rows
  toolBar = new TestToolBar(toolBarFrame, 10, 10, -1, -1, 0, wxVERTICAL, 5);
  toolBar->SetMargins(2, 2);
  toolBar->GetDC()->SetBackground(wxGREY_BRUSH);

  for (int i = 10; i < 25; i++)
    toolBar->AddTool(i, toolBarBitmaps[i], NULL, TRUE);

  toolBar->Layout();
  float maxWidth, maxHeight;
  toolBar->GetMaxSize(&maxWidth, &maxHeight);
  toolBarFrame->SetClientSize((int)maxWidth, (int)maxHeight);
  toolBarFrame->Show(TRUE);

The wxButtonBar library

wxToolBar overview

Class: wxButtonBar

wxToolBar does the job, but it isn't as slick as it could be. The wxButtonBar library class presents an almost identical Application Programming Interface, but under Windows, the buttons are 3D and depress properly.

Under Windows, it expects 16-colour bitmaps that are 16 pixels wide and 15 pixels high. If you want to use a different size, call wxButtonBar::SetDefaultSize as the demo shows, before adding tools to the button bar. Don't supply more than one bitmap for each tool, because wxButtonBar generates all three images (normal, depressed and checked) from the single bitmap you give it.

Include the file wx_bbar.h to use this class.

X-optimized (or generic) button bar code may follow at a future date.


Windows 95 differences

Under Windows 95, wxButtonBar behaves slightly differently than under generic WIN32, since it uses the Windows 95 toolbar common control.

  1. CreateTools must be called after the tools have been added.
  2. No absolute positioning is supported but you can specify the number of rows, and add tool separators with AddSeparator. Layout does nothing.
  3. Tooltips are supported.
  4. OnRightClick is not supported.
  5. The device context support is limited, though there is enough to support drawing a border from within OnPaint.
  6. OnEvent and OnChar are not supported.
  7. Scrollbars are not supported.

Note: under Windows 95, a wxButtonBar cannot be moved to any position other than the top-left of the frame. If this is a problem, you may wish to alter wx_bbar.h and wx_bbar.cc to compile the non-Windows 95 code instead.