]>
git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/overviews/toolbar.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: topic overview
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
11 @page overview_toolbar Toolbar overview
14 The toolbar family of classes allows an application to use toolbars
15 in a variety of configurations and styles.
16 The toolbar is a popular user interface component and contains a set of bitmap
17 buttons or toggles. A toolbar gives faster access to an application's facilities than
18 menus, which have to be popped up and selected rather laboriously.
19 Instead of supplying one toolbar class with a number
20 of different implementations depending on platform, wxWidgets separates
21 out the classes. This is because there are a number of different toolbar
22 styles that you may wish to use simultaneously, and also, future
23 toolbar implementations will emerge which
24 cannot all be shoe-horned into the one class.
25 For each platform, the symbol @b wxToolBar is defined to be one of the
26 specific toolbar classes.
27 The following is a summary of the toolbar classes and their differences.
30 @b wxToolBarBase. This is a base class with pure virtual functions,
31 and should not be used directly.
32 @b wxToolBarSimple. A simple toolbar class written entirely with generic wxWidgets
33 functionality. A simple 3D effect for buttons is possible, but it is not consistent
34 with the Windows look and feel. This toolbar can scroll, and you can have arbitrary
35 numbers of rows and columns.
36 @b wxToolBarMSW. This class implements an old-style Windows toolbar, only on
37 Windows. There are small, three-dimensional buttons, which do not (currently) reflect
38 the current Windows colour settings: the buttons are grey. This is the default wxToolBar
40 @b wxToolBar95. Uses the native Windows 95 toolbar class. It dynamically adjusts its
41 background and button colours according to user colour settings.
42 CreateTools must be called after the tools have been added.
43 No absolute positioning is supported but you can specify the number
44 of rows, and add tool separators with @b AddSeparator.
45 Tooltips are supported. @b OnRightClick is not supported. This is the default wxToolBar
46 on Windows 95, Windows NT 4 and above. With the style wxTB_FLAT, the flat toolbar
47 look is used, with a border that is highlighted when the cursor moves over the buttons.
50 A toolbar might appear as a single row of images under
51 the menubar, or it might be in a separate frame layout in several rows
52 and columns. The class handles the layout of the images, unless explicit
53 positioning is requested.
54 A tool is a bitmap which can either be a button (there is no 'state',
55 it just generates an event when clicked) or it can be a toggle. If a
56 toggle, a second bitmap can be provided to depict the 'on' state; if
57 the second bitmap is omitted, either the inverse of the first bitmap
58 will be used (for monochrome displays) or a thick border is drawn
59 around the bitmap (for colour displays where inverting will not have
61 The Windows-specific toolbar classes expect 16-colour bitmaps that are 16 pixels wide and 15 pixels
62 high. If you want to use a different size, call @b SetToolBitmapSize
63 as the demo shows, before adding tools to the button bar. Don't supply more than
64 one bitmap for each tool, because the toolbar generates all three images (normal,
65 depressed and checked) from the single bitmap you give it.
66 @ref usingtoolbarlibrary_overview
69 @section usingtoolbarlibrary Using the toolbar library
71 Include @c "wx/toolbar.h", or if using a class directly, one of:
74 @c "wx/msw/tbarmsw.h for wxToolBarMSW
75 @c "wx/msw/tbar95.h for wxToolBar95
76 @c "wx/tbarsmpl.h for wxToolBarSimple
79 Example of toolbar use are given in the sample program "toolbar''. The
80 source is given below. In fact it is out of date because recommended
81 practise is to use event handlers (using EVT_MENU or EVT_TOOL) instead of
82 overriding OnLeftClick.
86 /////////////////////////////////////////////////////////////////////////////
88 // Purpose: wxToolBar sample
89 // Author: Julian Smart
93 // Copyright: (c) Julian Smart
94 // License: wxWindows license
95 /////////////////////////////////////////////////////////////////////////////
97 // For compilers that support precompilation, includes "wx/wx.h".
98 #include "wx/wxprec.h"
108 #include "wx/toolbar.h"
113 #if defined(__WXGTK__) || defined(__WXMOTIF__)
114 #include "mondrian.xpm"
115 #include "bitmaps/new.xpm"
116 #include "bitmaps/open.xpm"
117 #include "bitmaps/save.xpm"
118 #include "bitmaps/copy.xpm"
119 #include "bitmaps/cut.xpm"
120 #include "bitmaps/print.xpm"
121 #include "bitmaps/preview.xpm"
122 #include "bitmaps/help.xpm"
127 // The `main program' equivalent, creating the windows and returning the
129 bool MyApp::OnInit(void)
131 // Create the main frame window
132 MyFrame* frame = new MyFrame((wxFrame *) @NULL, -1, (const wxString) "wxToolBar Sample",
133 wxPoint(100, 100), wxSize(450, 300));
135 // Give it a status line
136 frame-CreateStatusBar();
139 frame-SetIcon(wxICON(mondrian));
142 wxMenu *fileMenu = new wxMenu;
143 fileMenu-Append(wxID_EXIT, "E", "Quit toolbar sample" );
145 wxMenu *helpMenu = new wxMenu;
146 helpMenu-Append(wxID_HELP, "", "About toolbar sample");
148 wxMenuBar* menuBar = new wxMenuBar;
150 menuBar-Append(fileMenu, "");
151 menuBar-Append(helpMenu, "");
153 // Associate the menu bar with the frame
154 frame-SetMenuBar(menuBar);
156 // Create the toolbar
157 frame-CreateToolBar(wxBORDER\_NONE|wxHORIZONTAL|wxTB_FLAT, ID_TOOLBAR);
159 frame-GetToolBar()-SetMargins( 2, 2 );
161 InitToolbar(frame-GetToolBar());
163 // Force a resize. This should probably be replaced by a call to a wxFrame
164 // function that lays out default decorations and the remaining content window.
165 wxSizeEvent event(wxSize(-1, -1), frame-GetId());
169 frame-SetStatusText("Hello, wxWidgets");
176 bool MyApp::InitToolbar(wxToolBar* toolBar)
179 wxBitmap* toolBarBitmaps[8];
182 toolBarBitmaps[0] = new wxBitmap("icon1");
183 toolBarBitmaps[1] = new wxBitmap("icon2");
184 toolBarBitmaps[2] = new wxBitmap("icon3");
185 toolBarBitmaps[3] = new wxBitmap("icon4");
186 toolBarBitmaps[4] = new wxBitmap("icon5");
187 toolBarBitmaps[5] = new wxBitmap("icon6");
188 toolBarBitmaps[6] = new wxBitmap("icon7");
189 toolBarBitmaps[7] = new wxBitmap("icon8");
191 toolBarBitmaps[0] = new wxBitmap( new_xpm );
192 toolBarBitmaps[1] = new wxBitmap( open_xpm );
193 toolBarBitmaps[2] = new wxBitmap( save_xpm );
194 toolBarBitmaps[3] = new wxBitmap( copy_xpm );
195 toolBarBitmaps[4] = new wxBitmap( cut_xpm );
196 toolBarBitmaps[5] = new wxBitmap( preview_xpm );
197 toolBarBitmaps[6] = new wxBitmap( print_xpm );
198 toolBarBitmaps[7] = new wxBitmap( help_xpm );
208 toolBar-AddTool(wxID_NEW, *(toolBarBitmaps[0]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "New file");
209 currentX += width + 5;
210 toolBar-AddTool(wxID_OPEN, *(toolBarBitmaps[1]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Open file");
211 currentX += width + 5;
212 toolBar-AddTool(wxID_SAVE, *(toolBarBitmaps[2]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Save file");
213 currentX += width + 5;
214 toolBar-AddSeparator();
215 toolBar-AddTool(wxID_COPY, *(toolBarBitmaps[3]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Copy");
216 currentX += width + 5;
217 toolBar-AddTool(wxID_CUT, *(toolBarBitmaps[4]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Cut");
218 currentX += width + 5;
219 toolBar-AddTool(wxID_PASTE, *(toolBarBitmaps[5]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Paste");
220 currentX += width + 5;
221 toolBar-AddSeparator();
222 toolBar-AddTool(wxID_PRINT, *(toolBarBitmaps[6]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Print");
223 currentX += width + 5;
224 toolBar-AddSeparator();
225 toolBar-AddTool(wxID_HELP, *(toolBarBitmaps[7]), wxNullBitmap, @false, currentX, -1, (wxObject *) @NULL, "Help");
229 // Can delete the bitmaps since they're reference counted
231 for (i = 0; i 8; i++)
232 delete toolBarBitmaps[i];
237 // wxID_HELP will be processed for the 'About' menu and the toolbar help button.
239 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
240 EVT_MENU(wxID_EXIT, MyFrame::OnQuit)
241 EVT_MENU(wxID_HELP, MyFrame::OnAbout)
242 EVT_CLOSE(MyFrame::OnCloseWindow)
243 EVT_TOOL_RANGE(wxID_OPEN, wxID_PASTE, MyFrame::OnToolLeftClick)
244 EVT_TOOL_ENTER(wxID_OPEN, MyFrame::OnToolEnter)
247 // Define my frame constructor
248 MyFrame::MyFrame(wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos,
249 const wxSize& size, long style):
250 wxFrame(parent, id, title, pos, size, style)
252 m_textWindow = new wxTextCtrl(this, -1, "", wxPoint(0, 0), wxSize(-1, -1), wxTE_MULTILINE);
255 void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
260 void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
262 (void)wxMessageBox("wxWidgets toolbar sample", "About wxToolBar");
265 // Define the behaviour for the frame closing
266 // - must delete all frames except for the main one.
267 void MyFrame::OnCloseWindow(wxCloseEvent& WXUNUSED(event))
272 void MyFrame::OnToolLeftClick(wxCommandEvent& event)
275 str.Printf("Clicked on tool %d", event.GetId());
279 void MyFrame::OnToolEnter(wxCommandEvent& event)
281 if (event.GetSelection() -1)
284 str.Printf("This is tool number %d", event.GetSelection());