More doxygen topic overview cleanup.

[wxWidgets.git] / docs / doxygen / overviews / toolbar.h

/////////////////////////////////////////////////////////////////////////////
// Name:        toolbar
// Purpose:     topic overview
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/*!

 @page overview_toolbar Toolbar overview

 Classes: #wxToolBar

 The toolbar family of classes allows an application to use toolbars
 in a variety of configurations and styles.

 The toolbar is a popular user interface component and contains a set of bitmap
 buttons or toggles. A toolbar gives faster access to an application's facilities than
 menus, which have to be popped up and selected rather laboriously.

 Instead of supplying one toolbar class with a number
 of different implementations depending on platform, wxWidgets separates
 out the classes. This is because there are a number of different toolbar
 styles that you may wish to use simultaneously, and also, future
 toolbar implementations will emerge which
 cannot all be shoe-horned into the one class.

 For each platform, the symbol @b wxToolBar is defined to be one of the
 specific toolbar classes.

 The following is a summary of the toolbar classes and their differences.

 - @b wxToolBarBase. This is a base class with pure virtual functions,
 and should not be used directly.
 - @b wxToolBarSimple. A simple toolbar class written entirely with generic wxWidgets
 functionality. A simple 3D effect for buttons is possible, but it is not consistent
 with the Windows look and feel. This toolbar can scroll, and you can have arbitrary
 numbers of rows and columns.
 - @b wxToolBarMSW. This class implements an old-style Windows toolbar, only on
 Windows. There are small, three-dimensional buttons, which do not (currently) reflect
 the current Windows colour settings: the buttons are grey. This is the default wxToolBar
 on 16-bit windows.
 - @b wxToolBar95. Uses the native Windows 95 toolbar class. It dynamically adjusts its
 background and button colours according to user colour settings.
 CreateTools must be called after the tools have been added.
 No absolute positioning is supported but you can specify the number
 of rows, and add tool separators with @b AddSeparator.
 Tooltips are supported. @b OnRightClick is not supported. This is the default wxToolBar
 on Windows 95, Windows NT 4 and above. With the style wxTB_FLAT, the flat toolbar
 look is used, with a border that is highlighted when the cursor moves over the buttons.

 A toolbar might appear as a single row of images under
 the menubar, or it might be in a separate frame layout in several rows
 and columns. The class handles the layout of the images, unless explicit
 positioning is requested.

 A tool is a bitmap which can either be a button (there is no 'state',
 it just generates an event when clicked) or it can be a toggle. If a
 toggle, a second bitmap can be provided to depict the 'on' state; if
 the second bitmap is omitted, either the inverse of the first bitmap
 will be used (for monochrome displays) or a thick border is drawn
 around the bitmap (for colour displays where inverting will not have
 the desired result).

 The Windows-specific toolbar classes expect 16-colour bitmaps that are 16 pixels wide and 15 pixels
 high. If you want to use a different size, call @b SetToolBitmapSize
 as the demo shows, before adding tools to the button bar. Don't supply more than
 one bitmap for each tool, because the toolbar generates all three images (normal,
 depressed and checked) from the single bitmap you give it.

 @ref overview_usingtoolbarlibrary


 @section overview_usingtoolbarlibrary Using the toolbar library

 Include @c "wx/toolbar.h", or if using a class directly, one of:

 - @c "wx/msw/tbarmsw.h for wxToolBarMSW
 - @c "wx/msw/tbar95.h for wxToolBar95
 - @c "wx/tbarsmpl.h for wxToolBarSimple


 Example of toolbar use are given in the sample program "toolbar''. The
 source is given below. In fact it is out of date because recommended
 practise is to use event handlers (using EVT_MENU or EVT_TOOL) instead of
 overriding OnLeftClick.


 @code
 /////////////////////////////////////////////////////////////////////////////
 // Name:        test.cpp
 // Purpose:     wxToolBar sample
 // Author:      Julian Smart
 // Modified by:
 // Created:     04/01/98
 // RCS-ID:      $Id$
 // Copyright:   (c) Julian Smart
 // License:    wxWindows license
 /////////////////////////////////////////////////////////////////////////////

 // For compilers that support precompilation, includes "wx/wx.h".
 #include "wx/wxprec.h"

 #ifdef __BORLANDC__
 #pragma hdrstop
 #endif

 #ifndef WX_PRECOMP
 #include "wx/wx.h"
 #endif

 #include "wx/toolbar.h"
 #include wx/log.h

 #include "test.h"

 #if defined(__WXGTK__) || defined(__WXMOTIF__)
 #include "mondrian.xpm"
 #include "bitmaps/new.xpm"
 #include "bitmaps/open.xpm"
 #include "bitmaps/save.xpm"
 #include "bitmaps/copy.xpm"
 #include "bitmaps/cut.xpm"
 #include "bitmaps/print.xpm"
 #include "bitmaps/preview.xpm"
 #include "bitmaps/help.xpm"
 #endif

 IMPLEMENT_APP(MyApp)

 // The `main program' equivalent, creating the windows and returning the
 // main frame
 bool MyApp::OnInit(void)
 {
   // Create the main frame window
   MyFrame* frame = new MyFrame((wxFrame *) @NULL, -1, (const wxString) "wxToolBar Sample",
      wxPoint(100, 100), wxSize(450, 300));

   // Give it a status line
   frame-CreateStatusBar();

   // Give it an icon
   frame-SetIcon(wxICON(mondrian));

   // Make a menubar
   wxMenu *fileMenu = new wxMenu;
   fileMenu-Append(wxID_EXIT, "E", "Quit toolbar sample" );

   wxMenu *helpMenu = new wxMenu;
   helpMenu-Append(wxID_HELP, "", "About toolbar sample");

   wxMenuBar* menuBar = new wxMenuBar;

   menuBar-Append(fileMenu, "");
   menuBar-Append(helpMenu, "");

   // Associate the menu bar with the frame
   frame-SetMenuBar(menuBar);

   // Create the toolbar
   frame-CreateToolBar(wxBORDER\_NONE|wxHORIZONTAL|wxTB_FLAT, ID_TOOLBAR);

   frame-GetToolBar()-SetMargins( 2, 2 );

   InitToolbar(frame-GetToolBar());

   // Force a resize. This should probably be replaced by a call to a wxFrame
   // function that lays out default decorations and the remaining content window.
   wxSizeEvent event(wxSize(-1, -1), frame-GetId());
   frame-OnSize(event);
   frame-Show(@true);

   frame-SetStatusText("Hello, wxWidgets");

   SetTopWindow(frame);

   return @true;
 }

 bool MyApp::InitToolbar(wxToolBar* toolBar)
 {
   // Set up toolbar
   wxBitmap* toolBarBitmaps[8];

 #ifdef __WXMSW__
   toolBarBitmaps[0] = new wxBitmap("icon1");
   toolBarBitmaps[1] = new wxBitmap("icon2");
   toolBarBitmaps[2] = new wxBitmap("icon3");
   toolBarBitmaps[3] = new wxBitmap("icon4");
   toolBarBitmaps[4] = new wxBitmap("icon5");
   toolBarBitmaps[5] = new wxBitmap("icon6");
   toolBarBitmaps[6] = new wxBitmap("icon7");
   toolBarBitmaps[7] = new wxBitmap("icon8");
 #else
   toolBarBitmaps[0] = new wxBitmap( new_xpm );
   toolBarBitmaps[1] = new wxBitmap( open_xpm );
   toolBarBitmaps[2] = new wxBitmap( save_xpm );
   toolBarBitmaps[3] = new wxBitmap( copy_xpm );
   toolBarBitmaps[4] = new wxBitmap( cut_xpm );
   toolBarBitmaps[5] = new wxBitmap( preview_xpm );
   toolBarBitmaps[6] = new wxBitmap( print_xpm );
   toolBarBitmaps[7] = new wxBitmap( help_xpm );
 #endif

 #ifdef __WXMSW__
   int width = 24;
 #else
   int width = 16;
 #endif
   int currentX = 5;

   toolBar-AddTool(wxID_NEW, *(toolBarBitmaps[0]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "New file");
   currentX += width + 5;
   toolBar-AddTool(wxID_OPEN, *(toolBarBitmaps[1]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Open file");
   currentX += width + 5;
   toolBar-AddTool(wxID_SAVE, *(toolBarBitmaps[2]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Save file");
   currentX += width + 5;
   toolBar-AddSeparator();
   toolBar-AddTool(wxID_COPY, *(toolBarBitmaps[3]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Copy");
   currentX += width + 5;
   toolBar-AddTool(wxID_CUT, *(toolBarBitmaps[4]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Cut");
   currentX += width + 5;
   toolBar-AddTool(wxID_PASTE, *(toolBarBitmaps[5]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Paste");
   currentX += width + 5;
   toolBar-AddSeparator();
   toolBar-AddTool(wxID_PRINT, *(toolBarBitmaps[6]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Print");
   currentX += width + 5;
   toolBar-AddSeparator();
   toolBar-AddTool(wxID_HELP, *(toolBarBitmaps[7]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Help");

   toolBar-Realize();

   // Can delete the bitmaps since they're reference counted
   int i;
   for (i = 0; i  8; i++)
     delete toolBarBitmaps[i];

   return @true;
 }

 // wxID_HELP will be processed for the 'About' menu and the toolbar help button.

 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
     EVT_MENU(wxID_EXIT, MyFrame::OnQuit)
     EVT_MENU(wxID_HELP, MyFrame::OnAbout)
     EVT_CLOSE(MyFrame::OnCloseWindow)
     EVT_TOOL_RANGE(wxID_OPEN, wxID_PASTE, MyFrame::OnToolLeftClick)
     EVT_TOOL_ENTER(wxID_OPEN, MyFrame::OnToolEnter)
 END_EVENT_TABLE()

 // Define my frame constructor
 MyFrame::MyFrame(wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos,
         const wxSize& size, long style):
   wxFrame(parent, id, title, pos, size, style)
 {
   m_textWindow = new wxTextCtrl(this, -1, "", wxPoint(0, 0), wxSize(-1, -1), wxTE_MULTILINE);
 }

 void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
 {
     Close(@true);
 }

 void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
 {
     (void)wxMessageBox("wxWidgets toolbar sample", "About wxToolBar");
 }

 // Define the behaviour for the frame closing
 // - must delete all frames except for the main one.
 void MyFrame::OnCloseWindow(wxCloseEvent& WXUNUSED(event))
 {
   Destroy();
 }

 void MyFrame::OnToolLeftClick(wxCommandEvent& event)
 {
   wxString str;
   str.Printf("Clicked on tool %d", event.GetId());
   SetStatusText(str);
 }

 void MyFrame::OnToolEnter(wxCommandEvent& event)
 {
   if (event.GetSelection()  -1)
   {
     wxString str;
     str.Printf("This is tool number %d", event.GetSelection());
     SetStatusText(str);
   }
   else
     SetStatusText("");
 }
 @endcode

 */