]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/ttoolbar.tex
Fixed wxTextCtrl::SetMaxLength for rich edit controls
[wxWidgets.git] / docs / latex / wx / ttoolbar.tex
CommitLineData
a660d684
KB
1\section{Toolbar overview}\label{wxtoolbaroverview}
2
81d66cf3 3Classes: \helpref{wxToolBar}{wxtoolbar}
a660d684
KB
4
5The toolbar family of classes allows an application to use toolbars
6in a variety of configurations and styles.
7
8The toolbar is a popular user interface component and contains a set of bitmap
9buttons or toggles. A toolbar gives faster access to an application's facilities than
10menus, which have to be popped up and selected rather laboriously.
11
12Instead of supplying one toolbar class with a number
fc2171bd 13of different implementations depending on platform, wxWidgets separates
a660d684
KB
14out the classes. This is because there are a number of different toolbar
15styles that you may wish to use simultaneously, and also, future
e702ff0f 16toolbar implementations will emerge which
81d66cf3 17cannot all be shoe-horned into the one class.
a660d684 18
81d66cf3
JS
19For each platform, the symbol {\bf wxToolBar} is defined to be one of the
20specific toolbar classes.
a660d684
KB
21
22The following is a summary of the toolbar classes and their differences.
23
24\begin{itemize}\itemsep=0pt
25\item {\bf wxToolBarBase.} This is a base class with pure virtual functions,
26and should not be used directly.
fc2171bd 27\item {\bf wxToolBarSimple.} A simple toolbar class written entirely with generic wxWidgets
e702ff0f 28functionality. A simple 3D effect for buttons is possible, but it is not consistent
a660d684
KB
29with the Windows look and feel. This toolbar can scroll, and you can have arbitrary
30numbers of rows and columns.
31\item {\bf wxToolBarMSW.} This class implements an old-style Windows toolbar, only on
32Windows. There are small, three-dimensional buttons, which do not (currently) reflect
81d66cf3
JS
33the current Windows colour settings: the buttons are grey. This is the default wxToolBar
34on 16-bit windows.
a660d684
KB
35\item {\bf wxToolBar95.} Uses the native Windows 95 toolbar class. It dynamically adjusts its
36background and button colours according to user colour settings.
37CreateTools must be called after the tools have been added.
38No absolute positioning is supported but you can specify the number
81d66cf3
JS
39of rows, and add tool separators with {\bf AddSeparator}.
40Tooltips are supported. {\bf OnRightClick} is not supported. This is the default wxToolBar
e702ff0f 41on Windows 95, Windows NT 4 and above. With the style wxTB\_FLAT, the flat toolbar
f6bcfd97 42look is used, with a border that is highlighted when the cursor moves over the buttons.
a660d684
KB
43\end{itemize}
44
45A toolbar might appear as a single row of images under
46the menubar, or it might be in a separate frame layout in several rows
47and columns. The class handles the layout of the images, unless explicit
48positioning is requested.
49
50A tool is a bitmap which can either be a button (there is no `state',
51it just generates an event when clicked) or it can be a toggle. If a
52toggle, a second bitmap can be provided to depict the `on' state; if
53the second bitmap is omitted, either the inverse of the first bitmap
54will be used (for monochrome displays) or a thick border is drawn
55around the bitmap (for colour displays where inverting will not have
56the desired result).
57
58The Windows-specific toolbar classes expect 16-colour bitmaps that are 16 pixels wide and 15 pixels
bd0df01f 59high. If you want to use a different size, call {\bf SetToolBitmapSize}\rtfsp
a660d684
KB
60as the demo shows, before adding tools to the button bar. Don't supply more than
61one bitmap for each tool, because the toolbar generates all three images (normal,
62depressed and checked) from the single bitmap you give it.
63
a660d684
KB
64\subsection{Using the toolbar library}
65
81d66cf3 66Include {\tt "wx/toolbar.h"}, or if using a class directly, one of:
a660d684 67
81d66cf3
JS
68\begin{itemize}\itemsep=0pt
69\item {\tt "wx/msw/tbarmsw.h} for wxToolBarMSW
70\item {\tt "wx/msw/tbar95.h} for wxToolBar95
71\item {\tt "wx/tbarsmpl.h} for wxToolBarSimple
72\end{itemize}
73
74Example of toolbar use are given in the sample program ``toolbar''. The
f6bcfd97 75source is given below. In fact it is out of date because recommended
e702ff0f
JS
76practise is to use event handlers (using EVT\_MENU or EVT\_TOOL) instead of
77overriding OnLeftClick.
a660d684 78
81d66cf3
JS
79{\small
80\begin{verbatim}
81/////////////////////////////////////////////////////////////////////////////
82// Name: test.cpp
83// Purpose: wxToolBar sample
84// Author: Julian Smart
85// Modified by:
86// Created: 04/01/98
87// RCS-ID: $Id$
88// Copyright: (c) Julian Smart
fc2171bd 89// License: wxWidgets license
81d66cf3 90/////////////////////////////////////////////////////////////////////////////
a660d684 91
81d66cf3
JS
92// For compilers that support precompilation, includes "wx/wx.h".
93#include "wx/wxprec.h"
a660d684 94
81d66cf3
JS
95#ifdef __BORLANDC__
96#pragma hdrstop
97#endif
a660d684 98
81d66cf3
JS
99#ifndef WX_PRECOMP
100#include "wx/wx.h"
101#endif
a660d684 102
81d66cf3 103#include "wx/toolbar.h"
5b6aa0ff 104#include <wx/log.h>
a660d684 105
5b6aa0ff 106#include "test.h"
81d66cf3 107
5b6aa0ff
JS
108#if defined(__WXGTK__) || defined(__WXMOTIF__)
109#include "mondrian.xpm"
110#include "bitmaps/new.xpm"
111#include "bitmaps/open.xpm"
112#include "bitmaps/save.xpm"
113#include "bitmaps/copy.xpm"
114#include "bitmaps/cut.xpm"
115#include "bitmaps/print.xpm"
116#include "bitmaps/preview.xpm"
117#include "bitmaps/help.xpm"
81d66cf3
JS
118#endif
119
5b6aa0ff
JS
120IMPLEMENT_APP(MyApp)
121
81d66cf3
JS
122// The `main program' equivalent, creating the windows and returning the
123// main frame
124bool MyApp::OnInit(void)
125{
126 // Create the main frame window
5b6aa0ff 127 MyFrame* frame = new MyFrame((wxFrame *) NULL, -1, (const wxString) "wxToolBar Sample",
81d66cf3
JS
128 wxPoint(100, 100), wxSize(450, 300));
129
130 // Give it a status line
131 frame->CreateStatusBar();
132
133 // Give it an icon
5b6aa0ff 134 frame->SetIcon(wxICON(mondrian));
81d66cf3
JS
135
136 // Make a menubar
137 wxMenu *fileMenu = new wxMenu;
5b6aa0ff 138 fileMenu->Append(wxID_EXIT, "E&xit", "Quit toolbar sample" );
81d66cf3
JS
139
140 wxMenu *helpMenu = new wxMenu;
5b6aa0ff 141 helpMenu->Append(wxID_HELP, "&About", "About toolbar sample");
81d66cf3
JS
142
143 wxMenuBar* menuBar = new wxMenuBar;
144
145 menuBar->Append(fileMenu, "&File");
146 menuBar->Append(helpMenu, "&Help");
147
148 // Associate the menu bar with the frame
149 frame->SetMenuBar(menuBar);
150
151 // Create the toolbar
152 frame->CreateToolBar(wxNO_BORDER|wxHORIZONTAL|wxTB_FLAT, ID_TOOLBAR);
5b6aa0ff
JS
153
154 frame->GetToolBar()->SetMargins( 2, 2 );
81d66cf3
JS
155
156 InitToolbar(frame->GetToolBar());
157
158 // Force a resize. This should probably be replaced by a call to a wxFrame
159 // function that lays out default decorations and the remaining content window.
5b6aa0ff
JS
160 wxSizeEvent event(wxSize(-1, -1), frame->GetId());
161 frame->OnSize(event);
cc81d32f 162 frame->Show(true);
81d66cf3 163
fc2171bd 164 frame->SetStatusText("Hello, wxWidgets");
81d66cf3
JS
165
166 SetTopWindow(frame);
167
cc81d32f 168 return true;
81d66cf3
JS
169}
170
171bool MyApp::InitToolbar(wxToolBar* toolBar)
172{
81d66cf3
JS
173 // Set up toolbar
174 wxBitmap* toolBarBitmaps[8];
175
176#ifdef __WXMSW__
a660d684
KB
177 toolBarBitmaps[0] = new wxBitmap("icon1");
178 toolBarBitmaps[1] = new wxBitmap("icon2");
179 toolBarBitmaps[2] = new wxBitmap("icon3");
81d66cf3
JS
180 toolBarBitmaps[3] = new wxBitmap("icon4");
181 toolBarBitmaps[4] = new wxBitmap("icon5");
182 toolBarBitmaps[5] = new wxBitmap("icon6");
183 toolBarBitmaps[6] = new wxBitmap("icon7");
184 toolBarBitmaps[7] = new wxBitmap("icon8");
5b6aa0ff
JS
185#else
186 toolBarBitmaps[0] = new wxBitmap( new_xpm );
187 toolBarBitmaps[1] = new wxBitmap( open_xpm );
188 toolBarBitmaps[2] = new wxBitmap( save_xpm );
189 toolBarBitmaps[3] = new wxBitmap( copy_xpm );
190 toolBarBitmaps[4] = new wxBitmap( cut_xpm );
191 toolBarBitmaps[5] = new wxBitmap( preview_xpm );
192 toolBarBitmaps[6] = new wxBitmap( print_xpm );
193 toolBarBitmaps[7] = new wxBitmap( help_xpm );
81d66cf3
JS
194#endif
195
196#ifdef __WXMSW__
197 int width = 24;
198#else
199 int width = 16;
200#endif
81d66cf3
JS
201 int currentX = 5;
202
cc81d32f 203 toolBar->AddTool(wxID_NEW, *(toolBarBitmaps[0]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "New file");
81d66cf3 204 currentX += width + 5;
cc81d32f 205 toolBar->AddTool(wxID_OPEN, *(toolBarBitmaps[1]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Open file");
81d66cf3 206 currentX += width + 5;
cc81d32f 207 toolBar->AddTool(wxID_SAVE, *(toolBarBitmaps[2]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Save file");
81d66cf3
JS
208 currentX += width + 5;
209 toolBar->AddSeparator();
cc81d32f 210 toolBar->AddTool(wxID_COPY, *(toolBarBitmaps[3]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Copy");
81d66cf3 211 currentX += width + 5;
cc81d32f 212 toolBar->AddTool(wxID_CUT, *(toolBarBitmaps[4]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Cut");
81d66cf3 213 currentX += width + 5;
cc81d32f 214 toolBar->AddTool(wxID_PASTE, *(toolBarBitmaps[5]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Paste");
81d66cf3
JS
215 currentX += width + 5;
216 toolBar->AddSeparator();
cc81d32f 217 toolBar->AddTool(wxID_PRINT, *(toolBarBitmaps[6]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Print");
81d66cf3
JS
218 currentX += width + 5;
219 toolBar->AddSeparator();
cc81d32f 220 toolBar->AddTool(wxID_HELP, *(toolBarBitmaps[7]), wxNullBitmap, false, currentX, -1, (wxObject *) NULL, "Help");
81d66cf3
JS
221
222 toolBar->Realize();
223
224 // Can delete the bitmaps since they're reference counted
225 int i;
226 for (i = 0; i < 8; i++)
227 delete toolBarBitmaps[i];
228
cc81d32f 229 return true;
81d66cf3
JS
230}
231
232// wxID_HELP will be processed for the 'About' menu and the toolbar help button.
233
234BEGIN_EVENT_TABLE(MyFrame, wxFrame)
235 EVT_MENU(wxID_EXIT, MyFrame::OnQuit)
236 EVT_MENU(wxID_HELP, MyFrame::OnAbout)
237 EVT_CLOSE(MyFrame::OnCloseWindow)
238 EVT_TOOL_RANGE(wxID_OPEN, wxID_PASTE, MyFrame::OnToolLeftClick)
5b6aa0ff 239 EVT_TOOL_ENTER(wxID_OPEN, MyFrame::OnToolEnter)
81d66cf3
JS
240END_EVENT_TABLE()
241
242// Define my frame constructor
243MyFrame::MyFrame(wxFrame* parent, wxWindowID id, const wxString& title, const wxPoint& pos,
244 const wxSize& size, long style):
245 wxFrame(parent, id, title, pos, size, style)
246{
247 m_textWindow = new wxTextCtrl(this, -1, "", wxPoint(0, 0), wxSize(-1, -1), wxTE_MULTILINE);
248}
249
5b6aa0ff 250void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
81d66cf3 251{
cc81d32f 252 Close(true);
81d66cf3 253}
a660d684 254
5b6aa0ff 255void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
81d66cf3 256{
fc2171bd 257 (void)wxMessageBox("wxWidgets toolbar sample", "About wxToolBar");
81d66cf3 258}
a660d684 259
81d66cf3
JS
260// Define the behaviour for the frame closing
261// - must delete all frames except for the main one.
5b6aa0ff 262void MyFrame::OnCloseWindow(wxCloseEvent& WXUNUSED(event))
81d66cf3
JS
263{
264 Destroy();
265}
a660d684 266
81d66cf3
JS
267void MyFrame::OnToolLeftClick(wxCommandEvent& event)
268{
269 wxString str;
270 str.Printf("Clicked on tool %d", event.GetId());
271 SetStatusText(str);
272}
a660d684 273
81d66cf3
JS
274void MyFrame::OnToolEnter(wxCommandEvent& event)
275{
276 if (event.GetSelection() > -1)
277 {
278 wxString str;
279 str.Printf("This is tool number %d", event.GetSelection());
280 SetStatusText(str);
281 }
282 else
283 SetStatusText("");
284}
a660d684 285\end{verbatim}
81d66cf3 286}
a660d684 287