Toolbar overview

Classes: wxToolBar

The toolbar family of classes allows an application to use toolbars in a variety of configurations and styles.

The toolbar is a popular user interface component and contains 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.

Instead of supplying one toolbar class with a number of different implementations depending on platform, wxWindows separates out the classes. This is because there are a number of different toolbar styles that you may wish to use simultaneously, and also, future toolbar implementations will emerge (for example, using the new-style Windows 'coolbar' as seen in Microsoft applications) which cannot all be shoe-horned into the one class.

For each platform, the symbol wxToolBar is defined to be one of the specific toolbar classes.

The following is a summary of the toolbar classes and their differences.

• wxToolBarBase. This is a base class with pure virtual functions, and should not be used directly.
• wxToolBarSimple. A simple toolbar class written entirely with generic wxWindows functionality. A simply 3D effect for buttons is possible, but it is not consistent with the Windows look and feel. This toolbar can scroll, and you can have arbitrary numbers of rows and columns.
• wxToolBarMSW. This class implements an old-style Windows toolbar, only on Windows. There are small, three-dimensional buttons, which do not (currently) reflect the current Windows colour settings: the buttons are grey. This is the default wxToolBar on 16-bit windows.
• wxToolBar95. Uses the native Windows 95 toolbar class. It dynamically adjusts its background and button colours according to user colour settings. CreateTools must be called after the tools have been added. No absolute positioning is supported but you can specify the number of rows, and add tool separators with AddSeparator. Tooltips are supported. OnRightClick is not supported. This is the default wxToolBar on Windows 95, Windows NT 4 and above.

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).

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

To intercept

Using the toolbar library

Using the toolbar library

Include "wx/toolbar.h", or if using a class directly, one of:

• "wx/msw/tbarmsw.h for wxToolBarMSW
• "wx/msw/tbar95.h for wxToolBar95
• "wx/tbarsmpl.h for wxToolBarSimple

Example of toolbar use are given in the sample program "toolbar''. The source is given below.

/////////////////////////////////////////////////////////////////////////////
// Name:        test.cpp
// Purpose:     wxToolBar sample
// Author:      Julian Smart
// Modified by:
// Created:     04/01/98
// RCS-ID:      $Id: ttoolbar.tex,v 1.5 1999/02/09 21:22:33 JS Exp $
// Copyright:   (c) Julian Smart
// Licence:   	wxWindows licence
/////////////////////////////////////////////////////////////////////////////

// For compilers that support precompilation, includes "wx/wx.h".
#include "wx/wxprec.h"

#ifdef __BORLANDC__
#pragma hdrstop
#endif

#ifndef WX_PRECOMP
#include "wx/wx.h"
#endif

#include "wx/toolbar.h"
#include <wx/log.h>

#include "test.h"

#if defined(__WXGTK__) || defined(__WXMOTIF__)
#include "mondrian.xpm"
#include "bitmaps/new.xpm"
#include "bitmaps/open.xpm"
#include "bitmaps/save.xpm"
#include "bitmaps/copy.xpm"
#include "bitmaps/cut.xpm"
#include "bitmaps/print.xpm"
#include "bitmaps/preview.xpm"
#include "bitmaps/help.xpm"
#endif

IMPLEMENT_APP(MyApp)

// The `main program' equivalent, creating the windows and returning the
// main frame
bool MyApp::OnInit(void)
{
  // Create the main frame window
  MyFrame* frame = new MyFrame((wxFrame *) NULL, -1, (const wxString) "wxToolBar Sample",
     wxPoint(100, 100), wxSize(450, 300));

  // Give it a status line
  frame->CreateStatusBar();

  // Give it an icon
  frame->SetIcon(wxICON(mondrian));

  // Make a menubar
  wxMenu *fileMenu = new wxMenu;
  fileMenu->Append(wxID_EXIT, "E&xit", "Quit toolbar sample" );

  wxMenu *helpMenu = new wxMenu;
  helpMenu->Append(wxID_HELP, "&About", "About toolbar sample");

  wxMenuBar* menuBar = new wxMenuBar;

  menuBar->Append(fileMenu, "&File");
  menuBar->Append(helpMenu, "&Help");

  // Associate the menu bar with the frame
  frame->SetMenuBar(menuBar);

  // Create the toolbar
  frame->CreateToolBar(wxNO_BORDER|wxHORIZONTAL|wxTB_FLAT, ID_TOOLBAR);
  
  frame->GetToolBar()->SetMargins( 2, 2 );

  InitToolbar(frame->GetToolBar());

  // Force a resize. This should probably be replaced by a call to a wxFrame
  // function that lays out default decorations and the remaining content window.
  wxSizeEvent event(wxSize(-1, -1), frame->GetId());
  frame->OnSize(event);
  frame->Show(TRUE);

  frame->SetStatusText("Hello, wxWindows");
  
  SetTopWindow(frame);

  return TRUE;
}

bool MyApp::InitToolbar(wxToolBar* toolBar)
{
  // Set up toolbar
  wxBitmap* toolBarBitmaps[8];

#ifdef __WXMSW__
  toolBarBitmaps[0] = new wxBitmap("icon1");
  toolBarBitmaps[ wxTabbedDialog,
 wxTabControl

The tab classes provides a way to display rows of tabs (like file divider tabs), which can be
used to switch between panels or other information. Tabs are most
commonly used in dialog boxes where the number of options is too great
to fit on one dialog.

The appearance and behaviour of a wxTabbedDialog

The following screenshot shows the appearance of the sample tabbed dialog application.


By clicking on the tabs, the user can display a different set of controls. In the example,
the Close and Help buttons remain constant. These two buttons are children of the main dialog box,
whereas the other controls are children of panels which are shown and hidden according to
which tab is active.

A tabbed dialog may have several layers (rows) of tabs, each being
offset vertically and horizontally from the previous. Tabs work in
columns, in that when a tab is pressed, it swaps place with the tab on
the first row of the same column, in order to give the effect of
displaying that tab. All tabs must be of the same width.
This is a constraint of the implementation, but it also
means that the user will find it easier to find tabs since there are
distinct tab columns. On some tabbed dialog implementations, tabs jump around
seemingly randomly because tabs have different widths.
In this implementation, a tab can always be found on the same column.

Tabs are always drawn along the top of the view area; the implementation does
not allow for vertical tabs or any other configuration.

Using tabs

The tab classes provide facilities for switching between contexts by
means of 'tabs', which look like file divider tabs.

You must create both a view to handle the tabs, and a window to display the tabs
and related information. The wxTabbedDialog and wxTabbedPanel classes are provided for
convenience, but you could equally well construct your own window class and derived
tab view.

If you wish to display a tabbed dialog - the most common use - you should follow these steps.



 Create a new wxTabbedDialog class, and any buttons you wish always to be displayed
(regardless of which tab is active).
 Create a new wxPanelTabView, passing the dialog as the first argument.
 Set the view rectangle with wxTabView::SetViewRect,
to specify the area in which child panels will be
shown. The tabs will sit on top of this view rectangle.
 Call wxTabView::CalculateTabWidth to calculate
the width of the tabs based on the view area. This is optional if, for example, you have one row
of tabs which does not extend the full width of the view area.
 Call wxTabView::AddTab for each of the tabs you wish to create, passing
a unique identifier and a tab label.
 Construct a number of windows, one for each tab, and call wxPanelTabView::AddTabWindow for
each of these, passing a tab identifier and the window.
 Set the tab selection.
 Show the dialog.


Under Motif, you may also need to size the dialog just before setting the tab selection, for unknown reasons.

Some constraints you need to be aware of:



 All tabs must be of the same width.
 Omit the wxTAB_STYLE_COLOUR_INTERIOR flag to ensure that the dialog background
and tab backgrounds match.