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, wxWidgets 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 which
  17 cannot all be shoe-horned into the one class.
  18
  19 For each platform, the symbol {\bf wxToolBar} is defined to be one of the
  20 specific toolbar classes.
  21
  22 The 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,
  26 and should not be used directly.
  27 \item {\bf wxToolBarSimple.} A simple toolbar class written entirely with generic wxWidgets
  28 functionality. A simple 3D effect for buttons is possible, but it is not consistent
  29 with the Windows look and feel. This toolbar can scroll, and you can have arbitrary
  30 numbers of rows and columns.
  31 \item {\bf wxToolBarMSW.} This class implements an old-style Windows toolbar, only on
  32 Windows. There are small, three-dimensional buttons, which do not (currently) reflect
  33 the current Windows colour settings: the buttons are grey. This is the default wxToolBar
  34 on 16-bit windows.
  35 \item {\bf wxToolBar95.} Uses the native Windows 95 toolbar class. It dynamically adjusts its
  36 background and button colours according to user colour settings.
  37 CreateTools must be called after the tools have been added.
  38 No absolute positioning is supported but you can specify the number
  39 of rows, and add tool separators with {\bf AddSeparator}.
  40 Tooltips are supported. {\bf OnRightClick} is not supported. This is the default wxToolBar
  41 on Windows 95, Windows NT 4 and above. With the style wxTB\_FLAT, the flat toolbar
  42 look is used, with a border that is highlighted when the cursor moves over the buttons.
  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 \subsection{Using the toolbar library}
  65
  66 Include {\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
  74 Example of toolbar use are given in the sample program ``toolbar''. The
  75 source is given below. In fact it is out of date because recommended
  76 practise is to use event handlers (using EVT\_MENU or EVT\_TOOL) instead of
  77 overriding 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$
  88 // Copyright:   (c) Julian Smart
  89 // License:     wxWidgets 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
 120 IMPLEMENT_APP(MyApp)
 121
 122 // The `main program' equivalent, creating the windows and returning the
 123 // main frame
 124 bool 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
 171 bool 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
 234 BEGIN_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)
 240 END_EVENT_TABLE()
 241
 242 // Define my frame constructor
 243 MyFrame::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
 250 void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
 251 {
 252     Close(true);
 253 }
 254
 255 void 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.
 262 void MyFrame::OnCloseWindow(wxCloseEvent& WXUNUSED(event))
 263 {
 264   Destroy();
 265 }
 266
 267 void MyFrame::OnToolLeftClick(wxCommandEvent& event)
 268 {
 269   wxString str;
 270   str.Printf("Clicked on tool %d", event.GetId());
 271   SetStatusText(str);
 272 }
 273
 274 void 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