docs/latex/wx/ttoolbar.tex

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