1\section{Toolbar overview}\label{wxtoolbaroverview} 2 3Classes: \helpref{wxToolBar}{wxtoolbar} 4 5The toolbar family of classes allows an application to use toolbars 6in a variety of configurations and styles. 7 8The toolbar is a popular user interface component and contains a set of bitmap 9buttons or toggles. A toolbar gives faster access to an application's facilities than 10menus, which have to be popped up and selected rather laboriously. 11 12Instead of supplying one toolbar class with a number 13of different implementations depending on platform, wxWidgets separates 14out the classes. This is because there are a number of different toolbar 15styles that you may wish to use simultaneously, and also, future 16toolbar implementations will emerge which 17cannot all be shoe-horned into the one class. 18 19For each platform, the symbol {\bf wxToolBar} is defined to be one of the 20specific toolbar classes. 21 22The following is a summary of the toolbar classes and their differences. 23 24\begin{itemize}\itemsep=0pt 25\item {\bf wxToolBarBase.} This is a base class with pure virtual functions, 26and should not be used directly. 27\item {\bf wxToolBarSimple.} A simple toolbar class written entirely with generic wxWidgets 28functionality. A simple 3D effect for buttons is possible, but it is not consistent 29with the Windows look and feel. This toolbar can scroll, and you can have arbitrary 30numbers of rows and columns. 31\item {\bf wxToolBarMSW.} This class implements an old-style Windows toolbar, only on 32Windows. There are small, three-dimensional buttons, which do not (currently) reflect 33the current Windows colour settings: the buttons are grey. This is the default wxToolBar 34on 16-bit windows. 35\item {\bf wxToolBar95.} Uses the native Windows 95 toolbar class. It dynamically adjusts its 36background and button colours according to user colour settings. 37CreateTools must be called after the tools have been added. 38No absolute positioning is supported but you can specify the number 39of rows, and add tool separators with {\bf AddSeparator}. 40Tooltips are supported. {\bf OnRightClick} is not supported. This is the default wxToolBar 41on Windows 95, Windows NT 4 and above. With the style wxTB\_FLAT, the flat toolbar 42look is used, with a border that is highlighted when the cursor moves over the buttons. 43\end{itemize} 44 45A toolbar might appear as a single row of images under 46the menubar, or it might be in a separate frame layout in several rows 47and columns. The class handles the layout of the images, unless explicit 48positioning is requested. 49 50A tool is a bitmap which can either be a button (there is no `state', 51it just generates an event when clicked) or it can be a toggle. If a 52toggle, a second bitmap can be provided to depict the `on' state; if 53the second bitmap is omitted, either the inverse of the first bitmap 54will be used (for monochrome displays) or a thick border is drawn 55around the bitmap (for colour displays where inverting will not have 56the desired result). 57 58The Windows-specific toolbar classes expect 16-colour bitmaps that are 16 pixels wide and 15 pixels 59high. If you want to use a different size, call {\bf SetToolBitmapSize}\rtfsp 60as the demo shows, before adding tools to the button bar. Don't supply more than 61one bitmap for each tool, because the toolbar generates all three images (normal, 62depressed and checked) from the single bitmap you give it. 63 64\subsection{Using the toolbar library}\label{usingtoolbarlibrary} 65 66Include {\tt "wx/toolbar.h"}, or if using a class directly, one of: 67 68\begin{itemize}\itemsep=0pt 69\item {\tt "wx/msw/tbarmsw.h} for wxToolBarMSW 70\item {\tt "wx/msw/tbar95.h} for wxToolBar95 71\item {\tt "wx/tbarsmpl.h} for wxToolBarSimple 72\end{itemize} 73 74Example of toolbar use are given in the sample program ``toolbar''. The 75source is given below. In fact it is out of date because recommended 76practise is to use event handlers (using EVT\_MENU or EVT\_TOOL) instead of 77overriding OnLeftClick. 78 79{\small 80\begin{verbatim} 81///////////////////////////////////////////////////////////////////////////// 82// Name: test.cpp 83// Purpose: wxToolBar sample 84// Author: Julian Smart 85// Modified by: 86// Created: 04/01/98 87// RCS-ID: $Id: ttoolbar.tex 32309 2005-02-22 15:09:56Z ABX $ 88// Copyright: (c) Julian Smart 89// License: wxWindows license 90///////////////////////////////////////////////////////////////////////////// 91 92// For compilers that support precompilation, includes "wx/wx.h". 93#include "wx/wxprec.h" 94 95#ifdef __BORLANDC__ 96#pragma hdrstop 97#endif 98 99#ifndef WX_PRECOMP 100#include "wx/wx.h" 101#endif 102 103#include "wx/toolbar.h" 104#include <wx/log.h> 105 106#include "test.h" 107 108#if defined(__WXGTK__) || defined(__WXMOTIF__) 109#include "mondrian.xpm" 110#include "bitmaps/new.xpm" 111#include "bitmaps/open.xpm" 112#include "bitmaps/save.xpm" 113#include "bitmaps/copy.xpm" 114#include "bitmaps/cut.xpm" 115#include "bitmaps/print.xpm" 116#include "bitmaps/preview.xpm" 117#include "bitmaps/help.xpm" 118#endif 119 120IMPLEMENT_APP(MyApp) 121 122// The `main program' equivalent, creating the windows and returning the 123// main frame 124bool MyApp::OnInit(void) 125{ 126 // Create the main frame window 127 MyFrame* frame = new MyFrame((wxFrame *) NULL, -1, (const wxString) "wxToolBar Sample", 128 wxPoint(100, 100), wxSize(450, 300)); 129 130 // Give it a status line 131 frame->CreateStatusBar(); 132 133 // Give it an icon 134 frame->SetIcon(wxICON(mondrian)); 135 136 // Make a menubar 137 wxMenu *fileMenu = new wxMenu; 138 fileMenu->Append(wxID_EXIT, "E&xit", "Quit toolbar sample" ); 139 140 wxMenu *helpMenu = new wxMenu; 141 helpMenu->Append(wxID_HELP, "&About", "About toolbar sample"); 142 143 wxMenuBar* menuBar = new wxMenuBar; 144 145 menuBar->Append(fileMenu, "&File"); 146 menuBar->Append(helpMenu, "&Help"); 147 148 // Associate the menu bar with the frame 149 frame->SetMenuBar(menuBar); 150 151 // Create the toolbar 152 frame->CreateToolBar(wxNO_BORDER|wxHORIZONTAL|wxTB_FLAT, ID_TOOLBAR); 153 154 frame->GetToolBar()->SetMargins( 2, 2 ); 155 156 InitToolbar(frame->GetToolBar()); 157 158 // Force a resize. This should probably be replaced by a call to a wxFrame 159 // function that lays out default decorations and the remaining content window. 160 wxSizeEvent event(wxSize(-1, -1), frame->GetId()); 161 frame->OnSize(event); 162 frame->Show(true); 163 164 frame->SetStatusText("Hello, wxWidgets"); 165 166 SetTopWindow(frame); 167 168 return true; 169} 170 171bool MyApp::InitToolbar(wxToolBar* toolBar) 172{ 173 // Set up toolbar 174 wxBitmap* toolBarBitmaps[8]; 175 176#ifdef __WXMSW__ 177 toolBarBitmaps[0] = new wxBitmap("icon1"); 178 toolBarBitmaps[1] = new wxBitmap("icon2"); 179 toolBarBitmaps[2] = new wxBitmap("icon3"); 180 toolBarBitmaps[3] = new wxBitmap("icon4"); 181 toolBarBitmaps[4] = new wxBitmap("icon5"); 182 toolBarBitmaps[5] = new wxBitmap("icon6"); 183 toolBarBitmaps[6] = new wxBitmap("icon7"); 184 toolBarBitmaps[7] = new wxBitmap("icon8"); 185#else 186 toolBarBitmaps[0] = new wxBitmap( new_xpm ); 187 toolBarBitmaps[1] = new wxBitmap( open_xpm ); 188 toolBarBitmaps[2] = new wxBitmap( save_xpm ); 189 toolBarBitmaps[3] = new wxBitmap( copy_xpm ); 190 toolBarBitmaps[4] = new wxBitmap( cut_xpm ); 191 toolBarBitmaps[5] = new wxBitmap( preview_xpm ); 192 toolBarBitmaps[6] = new wxBitmap( print_xpm ); 193 toolBarBitmaps[7] = new wxBitmap( help_xpm ); 194#endif 195 196#ifdef __WXMSW__ 197 int width = 24; 198#else 199 int width = 16; 200#endif 201 int currentX = 5; 202 203 toolBar->AddTool(wxID_NEW, *(toolBarBitmaps[0]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "New file"); 204 currentX += width + 5; 205 toolBar->AddTool(wxID_OPEN, *(toolBarBitmaps[1]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Open file"); 206 currentX += width + 5; 207 toolBar->AddTool(wxID_SAVE, *(toolBarBitmaps[2]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Save file"); 208 currentX += width + 5; 209 toolBar->AddSeparator(); 210 toolBar->AddTool(wxID_COPY, *(toolBarBitmaps[3]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Copy"); 211 currentX += width + 5; 212 toolBar->AddTool(wxID_CUT, *(toolBarBitmaps[4]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Cut"); 213 currentX += width + 5; 214 toolBar->AddTool(wxID_PASTE, *(toolBarBitmaps[5]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Paste"); 215 currentX += width + 5; 216 toolBar->AddSeparator(); 217 toolBar->AddTool(wxID_PRINT, *(toolBarBitmaps[6]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Print"); 218 currentX += width + 5; 219 toolBar->AddSeparator(); 220 toolBar->AddTool(wxID_HELP, *(toolBarBitmaps[7]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Help"); 221 222 toolBar->Realize(); 223 224 // Can delete the bitmaps since they're reference counted 225 int i; 226 for (i = 0; i < 8; i++) 227 delete toolBarBitmaps[i]; 228 229 return true; 230} 231 232// wxID_HELP will be processed for the 'About' menu and the toolbar help button. 233 234BEGIN_EVENT_TABLE(MyFrame, wxFrame) 235 EVT_MENU(wxID_EXIT, MyFrame::OnQuit) 236 EVT_MENU(wxID_HELP, MyFrame::OnAbout) 237 EVT_CLOSE(MyFrame::OnCloseWindow) 238 EVT_TOOL_RANGE(wxID_OPEN, wxID_PASTE, MyFrame::OnToolLeftClick) 239 EVT_TOOL_ENTER(wxID_OPEN, MyFrame::OnToolEnter) 240END_EVENT_TABLE() 241 242// Define my frame constructor 243MyFrame::MyFrame(wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos, 244 const wxSize& size, long style): 245 wxFrame(parent, id, title, pos, size, style) 246{ 247 m_textWindow = new wxTextCtrl(this, -1, "", wxPoint(0, 0), wxSize(-1, -1), wxTE_MULTILINE); 248} 249 250void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event)) 251{ 252 Close(true); 253} 254 255void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event)) 256{ 257 (void)wxMessageBox("wxWidgets toolbar sample", "About wxToolBar"); 258} 259 260// Define the behaviour for the frame closing 261// - must delete all frames except for the main one. 262void MyFrame::OnCloseWindow(wxCloseEvent& WXUNUSED(event)) 263{ 264 Destroy(); 265} 266 267void MyFrame::OnToolLeftClick(wxCommandEvent& event) 268{ 269 wxString str; 270 str.Printf("Clicked on tool %d", event.GetId()); 271 SetStatusText(str); 272} 273 274void MyFrame::OnToolEnter(wxCommandEvent& event) 275{ 276 if (event.GetSelection() > -1) 277 { 278 wxString str; 279 str.Printf("This is tool number %d", event.GetSelection()); 280 SetStatusText(str); 281 } 282 else 283 SetStatusText(""); 284} 285\end{verbatim} 286} 287 288