X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7f2a1fc841beba9f5d8ae65c041885987ccac211..a25a17732c2d4d34d5d35a5318053dd8c6e29722:/docs/doxygen/overviews/toolbar.h diff --git a/docs/doxygen/overviews/toolbar.h b/docs/doxygen/overviews/toolbar.h index 572b648162..9f0784058d 100644 --- a/docs/doxygen/overviews/toolbar.h +++ b/docs/doxygen/overviews/toolbar.h @@ -1,299 +1,93 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: toolbar +// Name: toolbar.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/*! +/** - @page overview_toolbar Toolbar overview +@page overview_toolbar Toolbar Overview - Classes: #wxToolBar +Classes: wxToolBar - The toolbar family of classes allows an application to use toolbars - in a variety of configurations and styles. +@li @ref overview_toolbar_intro +@li @ref overview_toolbar_library - 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. +@section overview_toolbar_intro Introduction - - @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. +The toolbar family of classes allows an application to use toolbars in a +variety of configurations and styles. - 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. +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. - 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). +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. - 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. +For each platform, the symbol wxToolBar is defined to be one of the specific +toolbar classes. - @ref usingtoolbarlibrary +The following is a summary of the toolbar classes and their differences: +@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. - @section usingtoolbarlibrary Using the toolbar library +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. - Include @c "wx/toolbar.h", or if using a class directly, one of: +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). - - @c "wx/msw/tbarmsw.h for wxToolBarMSW - - @c "wx/msw/tbar95.h for wxToolBar95 - - @c "wx/tbarsmpl.h for wxToolBarSimple +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. - 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. +@section overview_toolbar_library Using the Toolbar Library +Include @c "wx/toolbar.h", or if using a class directly, one of: - @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 - ///////////////////////////////////////////////////////////////////////////// +- @c "wx/msw/tbarmsw.h" for wxToolBarMSW +- @c "wx/msw/tbar95.h" for wxToolBar95 +- @c "wx/tbarsmpl.h" for wxToolBarSimple - // 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 - - */ +An example of using a toolbar is given in the "toolbar" sample. +*/