/////////////////////////////////////////////////////////////////////////////
-// 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$
- // 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.
+*/
projects / wxWidgets.git / blobdiff