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