]> git.saurik.com Git - wxWidgets.git/blobdiff - docs/doxygen/overviews/toolbar.h
removed wxAcceleratorTable copy ctor docs, no port implements it
[wxWidgets.git] / docs / doxygen / overviews / toolbar.h
index 8a2639cac6a87f9fad01c5430370f1d09368cb38..9f0784058da4678611cc515d947a8615d28e7ed3 100644 (file)
 /////////////////////////////////////////////////////////////////////////////
-// Name:        toolbar
+// Name:        toolbar.h
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
-/*!
+/**
 
- @page toolbar_overview Toolbar overview
+@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.
+Classes: wxToolBar
 
+@li @ref overview_toolbar_intro
+@li @ref overview_toolbar_library
 
-  @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.
 
+<hr>
 
- 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 usingtoolbarlibrary_overview
 
+@section overview_toolbar_intro Introduction
 
- @section usingtoolbarlibrary Using the toolbar library
+The toolbar family of classes allows an application to use toolbars in a
+variety of configurations and styles.
 
- Include @c "wx/toolbar.h", or if using a class directly, one of:
+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.
 
-  @c "wx/msw/tbarmsw.h for wxToolBarMSW
-  @c "wx/msw/tbar95.h for wxToolBar95
-  @c "wx/tbarsmpl.h for wxToolBarSimple
+For each platform, the symbol wxToolBar is defined to be one of the specific
+toolbar classes.
 
+The following is a summary of the toolbar classes and their differences:
 
- 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.
+@li wxToolBarBase: This is a base class with pure virtual functions, and should
+    not be used directly.
+@li 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.
+@li 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.
+@li wxToolBar95: Uses the native Windows 95 toolbar class. It dynamically
+    adjusts it's 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 @c AddSeparator. Tooltips are supported.
+    @c 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.
 
- @code
- /////////////////////////////////////////////////////////////////////////////
- // Name:        test.cpp
- // Purpose:     wxToolBar sample
- // Author:      Julian Smart
- // Modified by:
- // Created:     04/01/98
- // RCS-ID:      $Id: ttoolbar.tex 47878 2007-08-05 10:10:37Z JS $
- // Copyright:   (c) Julian Smart
- // License:    wxWindows license
- /////////////////////////////////////////////////////////////////////////////
+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).
 
- // For compilers that support precompilation, includes "wx/wx.h".
- #include "wx/wxprec.h"
+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
+@c 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.
 
- #ifdef __BORLANDC__
- #pragma hdrstop
- #endif
 
- #ifndef WX_PRECOMP
- #include "wx/wx.h"
- #endif
+@section overview_toolbar_library Using the Toolbar Library
 
- #include "wx/toolbar.h"
- #include wx/log.h
+Include @c "wx/toolbar.h", or if using a class directly, one of:
 
- #include "test.h"
+- @c "wx/msw/tbarmsw.h" for wxToolBarMSW
+- @c "wx/msw/tbar95.h" for wxToolBar95
+- @c "wx/tbarsmpl.h" for wxToolBarSimple
 
- #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
-
- */
+An example of using a toolbar is given in the "toolbar" sample.
 
+*/