docs/doxygen/overviews/toolbar.h

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