implemented, tested and documented wxTextCtrl::SetMaxLength()
[wxWidgets.git] / include / wx / tbarbase.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/tbarbase.h
3 // Purpose: Base class for toolbar classes
4 // Author: Julian Smart
5 // Modified by:
6 // Created: 01/02/97
7 // RCS-ID: $Id$
8 // Copyright: (c) Julian Smart and Markus Holzem
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
11
12 #ifndef _WX_TBARBASE_H_
13 #define _WX_TBARBASE_H_
14
15 // ----------------------------------------------------------------------------
16 // headers
17 // ----------------------------------------------------------------------------
18
19 #ifdef __GNUG__
20 #pragma interface "tbarbase.h"
21 #endif
22
23 #include "wx/defs.h"
24
25 #if wxUSE_TOOLBAR
26
27 #include "wx/bitmap.h"
28 #include "wx/list.h"
29 #include "wx/control.h"
30
31 class WXDLLEXPORT wxToolBarBase;
32 class WXDLLEXPORT wxToolBarToolBase;
33
34 // ----------------------------------------------------------------------------
35 // constants
36 // ----------------------------------------------------------------------------
37
38 WXDLLEXPORT_DATA(extern const wxChar*) wxToolBarNameStr;
39 WXDLLEXPORT_DATA(extern const wxSize) wxDefaultSize;
40 WXDLLEXPORT_DATA(extern const wxPoint) wxDefaultPosition;
41
42 enum wxToolBarToolStyle
43 {
44 wxTOOL_STYLE_BUTTON = 1,
45 wxTOOL_STYLE_SEPARATOR = 2,
46 wxTOOL_STYLE_CONTROL
47 };
48
49 // ----------------------------------------------------------------------------
50 // wxToolBarTool is a toolbar element.
51 //
52 // It has a unique id (except for the separators which always have id -1), the
53 // style (telling whether it is a normal button, separator or a control), the
54 // state (toggled or not, enabled or not) and short and long help strings. The
55 // default implementations use the short help string for the tooltip text which
56 // is popped up when the mouse pointer enters the tool and the long help string
57 // for the applications status bar.
58 // ----------------------------------------------------------------------------
59
60 class WXDLLEXPORT wxToolBarToolBase : public wxObject
61 {
62 public:
63 // ctors & dtor
64 // ------------
65
66 wxToolBarToolBase(wxToolBarBase *tbar = (wxToolBarBase *)NULL,
67 int id = wxID_SEPARATOR,
68 const wxBitmap& bitmap1 = wxNullBitmap,
69 const wxBitmap& bitmap2 = wxNullBitmap,
70 bool toggle = FALSE,
71 wxObject *clientData = (wxObject *) NULL,
72 const wxString& shortHelpString = wxEmptyString,
73 const wxString& longHelpString = wxEmptyString)
74 : m_shortHelpString(shortHelpString),
75 m_longHelpString(longHelpString)
76 {
77 m_tbar = tbar;
78 m_id = id;
79 m_clientData = clientData;
80
81 m_bitmap1 = bitmap1;
82 m_bitmap2 = bitmap2;
83
84 m_isToggle = toggle;
85 m_enabled = TRUE;
86 m_toggled = FALSE;
87
88 m_toolStyle = id == wxID_SEPARATOR ? wxTOOL_STYLE_SEPARATOR
89 : wxTOOL_STYLE_BUTTON;
90 }
91
92 wxToolBarToolBase(wxToolBarBase *tbar, wxControl *control)
93 {
94 m_tbar = tbar;
95 m_control = control;
96 m_id = control->GetId();
97
98 m_isToggle = FALSE;
99 m_enabled = TRUE;
100 m_toggled = FALSE;
101
102 m_toolStyle = wxTOOL_STYLE_CONTROL;
103 }
104
105 ~wxToolBarToolBase();
106
107 // accessors
108 // ---------
109
110 // general
111 int GetId() const { return m_id; }
112
113 wxControl *GetControl() const
114 {
115 wxASSERT_MSG( IsControl(), _T("this toolbar tool is not a control") );
116
117 return m_control;
118 }
119
120 wxToolBarBase *GetToolBar() const { return m_tbar; }
121
122 // style
123 int IsButton() const { return m_toolStyle == wxTOOL_STYLE_BUTTON; }
124 int IsControl() const { return m_toolStyle == wxTOOL_STYLE_CONTROL; }
125 int IsSeparator() const { return m_toolStyle == wxTOOL_STYLE_SEPARATOR; }
126 int GetStyle() const { return m_toolStyle; }
127
128 // state
129 bool IsEnabled() const { return m_enabled; }
130 bool IsToggled() const { return m_toggled; }
131 bool CanBeToggled() const { return m_isToggle; }
132
133 // attributes
134 const wxBitmap& GetBitmap1() const { return m_bitmap1; }
135 const wxBitmap& GetBitmap2() const { return m_bitmap2; }
136
137 const wxBitmap& GetBitmap() const
138 { return IsToggled() ? m_bitmap2 : m_bitmap1; }
139
140 wxString GetShortHelp() const { return m_shortHelpString; }
141 wxString GetLongHelp() const { return m_longHelpString; }
142
143 wxObject *GetClientData() const
144 {
145 if ( m_toolStyle == wxTOOL_STYLE_CONTROL )
146 {
147 return (wxObject*)m_control->GetClientData();
148 }
149 else
150 {
151 return m_clientData;
152 }
153 }
154
155 // modifiers: return TRUE if the state really changed
156 bool Enable(bool enable);
157 bool Toggle(bool toggle);
158 bool SetToggle(bool toggle);
159 bool SetShortHelp(const wxString& help);
160 bool SetLongHelp(const wxString& help);
161
162 void Toggle() { Toggle(!IsToggled()); }
163
164 void SetBitmap1(const wxBitmap& bmp) { m_bitmap1 = bmp; }
165 void SetBitmap2(const wxBitmap& bmp) { m_bitmap2 = bmp; }
166
167 void SetClientData(wxObject *clientData)
168 {
169 if ( m_toolStyle == wxTOOL_STYLE_CONTROL )
170 {
171 m_control->SetClientData(clientData);
172 }
173 else
174 {
175 m_clientData = clientData;
176 }
177 }
178
179 // add tool to/remove it from a toolbar
180 virtual void Detach() { m_tbar = (wxToolBarBase *)NULL; }
181 virtual void Attach(wxToolBarBase *tbar) { m_tbar = tbar; }
182
183 protected:
184 wxToolBarBase *m_tbar; // the toolbar to which we belong (may be NULL)
185
186 int m_toolStyle; // see enum wxToolBarToolStyle
187 int m_id; // the tool id, wxID_SEPARATOR for separator
188
189 // as controls have their own client data, no need to waste memory
190 union
191 {
192 wxObject *m_clientData;
193 wxControl *m_control;
194 };
195
196 // tool state
197 bool m_toggled;
198 bool m_isToggle;
199 bool m_enabled;
200
201 // normal and toggles bitmaps
202 wxBitmap m_bitmap1;
203 wxBitmap m_bitmap2;
204
205 // short and long help strings
206 wxString m_shortHelpString;
207 wxString m_longHelpString;
208 };
209
210 // a list of toolbar tools
211 WX_DECLARE_EXPORTED_LIST(wxToolBarToolBase, wxToolBarToolsList);
212
213 // ----------------------------------------------------------------------------
214 // the base class for all toolbars
215 // ----------------------------------------------------------------------------
216
217 class WXDLLEXPORT wxToolBarBase : public wxControl
218 {
219 public:
220 wxToolBarBase();
221 virtual ~wxToolBarBase();
222
223 // toolbar construction
224 // --------------------
225
226 // the most commonly used version of AddTool()
227 wxToolBarToolBase *AddTool(int id,
228 const wxBitmap& bitmap,
229 const wxString& shortHelpString = wxEmptyString,
230 const wxString& longHelpString = wxEmptyString)
231 {
232 return AddTool(id, bitmap, wxNullBitmap, FALSE, NULL,
233 shortHelpString, longHelpString);
234 }
235
236 // If pushedBitmap is NULL, a reversed version of bitmap is created and
237 // used as the pushed/toggled image. If toggle is TRUE, the button toggles
238 // between the two states.
239 wxToolBarToolBase *AddTool(int id,
240 const wxBitmap& bitmap,
241 const wxBitmap& pushedBitmap,
242 bool toggle = FALSE,
243 wxObject *clientData = NULL,
244 const wxString& shortHelpString = wxEmptyString,
245 const wxString& longHelpString = wxEmptyString)
246 {
247 return AddTool(id, bitmap, pushedBitmap, toggle,
248 -1, -1, clientData, shortHelpString, longHelpString);
249 }
250
251 // the old version of AddTool() kept for compatibility
252 virtual wxToolBarToolBase *AddTool
253 (
254 int id,
255 const wxBitmap& bitmap,
256 const wxBitmap& pushedBitmap,
257 bool toggle,
258 wxCoord xPos,
259 wxCoord yPos = -1,
260 wxObject *clientData = NULL,
261 const wxString& helpString1 = wxEmptyString,
262 const wxString& helpString2 = wxEmptyString
263 );
264
265 // insert the new tool at the given position, if pos == GetToolsCount(), it
266 // is equivalent to AddTool()
267 virtual wxToolBarToolBase *InsertTool
268 (
269 size_t pos,
270 int id,
271 const wxBitmap& bitmap,
272 const wxBitmap& pushedBitmap = wxNullBitmap,
273 bool toggle = FALSE,
274 wxObject *clientData = NULL,
275 const wxString& help1 = wxEmptyString,
276 const wxString& help2 = wxEmptyString
277 );
278
279 // add an arbitrary control to the toolbar, return TRUE if ok (notice that
280 // the control will be deleted by the toolbar and that it will also adjust
281 // its position/size)
282 //
283 // NB: the control should have toolbar as its parent
284 virtual wxToolBarToolBase *AddControl(wxControl *control);
285 virtual wxToolBarToolBase *InsertControl(size_t pos, wxControl *control);
286
287 // add a separator to the toolbar
288 virtual wxToolBarToolBase *AddSeparator();
289 virtual wxToolBarToolBase *InsertSeparator(size_t pos);
290
291 // remove the tool from the toolbar: the caller is responsible for actually
292 // deleting the pointer
293 virtual wxToolBarToolBase *RemoveTool(int id);
294
295 // delete tool either by index or by position
296 virtual bool DeleteToolByPos(size_t pos);
297 virtual bool DeleteTool(int id);
298
299 // delete all tools
300 virtual void ClearTools();
301
302 // must be called after all buttons have been created to finish toolbar
303 // initialisation
304 virtual bool Realize();
305
306 // tools state
307 // -----------
308
309 virtual void EnableTool(int id, bool enable);
310 virtual void ToggleTool(int id, bool toggle);
311
312 // Set this to be togglable (or not)
313 virtual void SetToggle(int id, bool toggle);
314
315 // set/get tools client data (not for controls)
316 virtual wxObject *GetToolClientData(int id) const;
317 virtual void SetToolClientData(int id, wxObject *clientData);
318
319 // return TRUE if the tool is toggled
320 virtual bool GetToolState(int id) const;
321
322 virtual bool GetToolEnabled(int id) const;
323
324 virtual void SetToolShortHelp(int id, const wxString& helpString);
325 virtual wxString GetToolShortHelp(int id) const;
326 virtual void SetToolLongHelp(int id, const wxString& helpString);
327 virtual wxString GetToolLongHelp(int id) const;
328
329 // margins/packing/separation
330 // --------------------------
331
332 virtual void SetMargins(int x, int y);
333 void SetMargins(const wxSize& size)
334 { SetMargins((int) size.x, (int) size.y); }
335 virtual void SetToolPacking(int packing)
336 { m_toolPacking = packing; }
337 virtual void SetToolSeparation(int separation)
338 { m_toolSeparation = separation; }
339
340 virtual wxSize GetToolMargins() { return GetMargins(); }
341 virtual int GetToolPacking() { return m_toolPacking; }
342 virtual int GetToolSeparation() { return m_toolSeparation; }
343
344 // for compatibility
345 wxSize GetMargins() const { return wxSize(m_xMargin, m_yMargin); }
346
347 // toolbar geometry
348 // ----------------
349
350 // set the number of toolbar rows
351 virtual void SetRows(int nRows);
352
353 // the toolbar can wrap - limit the number of columns or rows it may take
354 void SetMaxRowsCols(int rows, int cols)
355 { m_maxRows = rows; m_maxCols = cols; }
356 int GetMaxRows() const { return m_maxRows; }
357 int GetMaxCols() const { return m_maxCols; }
358
359 // get/set the size of the bitmaps used by the toolbar: should be called
360 // before adding any tools to the toolbar
361 virtual void SetToolBitmapSize(const wxSize& size)
362 { m_defaultWidth = size.x; m_defaultHeight = size.y; };
363 virtual wxSize GetToolBitmapSize() const
364 { return wxSize(m_defaultWidth, m_defaultHeight); }
365
366 // the button size in some implementations is bigger than the bitmap size:
367 // get the total button size (by default the same as bitmap size)
368 virtual wxSize GetToolSize() const
369 { return GetToolBitmapSize(); } ;
370
371 // returns a (non separator) tool containing the point (x, y) or NULL if
372 // there is no tool at this point (corrdinates are client)
373 virtual wxToolBarToolBase *FindToolForPosition(wxCoord x,
374 wxCoord y) const = 0;
375
376 // event handlers
377 // --------------
378
379 // NB: these functions are deprecated, use EVT_TOOL_XXX() instead!
380
381 // Only allow toggle if returns TRUE. Call when left button up.
382 virtual bool OnLeftClick(int id, bool toggleDown);
383
384 // Call when right button down.
385 virtual void OnRightClick(int id, long x, long y);
386
387 // Called when the mouse cursor enters a tool bitmap.
388 // Argument is -1 if mouse is exiting the toolbar.
389 virtual void OnMouseEnter(int id);
390
391 // more deprecated functions
392 // -------------------------
393
394 #if WXWIN_COMPATIBILITY
395 void SetDefaultSize(int w, int h) { SetDefaultSize(wxSize(w, h)); }
396 long GetDefaultWidth() const { return m_defaultWidth; }
397 long GetDefaultHeight() const { return m_defaultHeight; }
398 int GetDefaultButtonWidth() const { return (int) GetDefaultButtonSize().x; };
399 int GetDefaultButtonHeight() const { return (int) GetDefaultButtonSize().y; };
400 virtual void SetDefaultSize(const wxSize& size) { SetToolBitmapSize(size); }
401 virtual wxSize GetDefaultSize() const { return GetToolBitmapSize(); }
402 virtual wxSize GetDefaultButtonSize() const { return GetToolSize(); }
403 #endif // WXWIN_COMPATIBILITY
404
405 // implementation only from now on
406 // -------------------------------
407
408 size_t GetToolsCount() const { return m_tools.GetCount(); }
409
410 void OnIdle(wxIdleEvent& event);
411
412 // Do the toolbar button updates (check for EVT_UPDATE_UI handlers)
413 virtual void DoToolbarUpdates();
414
415 // don't want toolbars to accept the focus by tabbing to them
416 virtual bool AcceptsFocusFromKeyboard() const { return FALSE; }
417
418 protected:
419 // to implement in derived classes
420 // -------------------------------
421
422 // the tool is not yet inserted into m_tools list when this function is
423 // called and will only be added to it if this function succeeds
424 virtual bool DoInsertTool(size_t pos, wxToolBarToolBase *tool) = 0;
425
426 // the tool is still in m_tools list when this function is called, it will
427 // only be deleted from it if it succeeds
428 virtual bool DoDeleteTool(size_t pos, wxToolBarToolBase *tool) = 0;
429
430 // called when the tools enabled flag changes
431 virtual void DoEnableTool(wxToolBarToolBase *tool, bool enable) = 0;
432
433 // called when the tool is toggled
434 virtual void DoToggleTool(wxToolBarToolBase *tool, bool toggle) = 0;
435
436 // called when the tools "can be toggled" flag changes
437 virtual void DoSetToggle(wxToolBarToolBase *tool, bool toggle) = 0;
438
439 // the functions to create toolbar tools
440 virtual wxToolBarToolBase *CreateTool(int id,
441 const wxBitmap& bitmap1,
442 const wxBitmap& bitmap2,
443 bool toggle,
444 wxObject *clientData,
445 const wxString& shortHelpString,
446 const wxString& longHelpString) = 0;
447 virtual wxToolBarToolBase *CreateTool(wxControl *control) = 0;
448
449 // helper functions
450 // ----------------
451
452 // find the tool by id
453 wxToolBarToolBase *FindById(int id) const;
454
455 // the list of all our tools
456 wxToolBarToolsList m_tools;
457
458 // the offset of the first tool
459 int m_xMargin;
460 int m_yMargin;
461
462 // the maximum number of toolbar rows/columns
463 int m_maxRows;
464 int m_maxCols;
465
466 // the tool packing and separation
467 int m_toolPacking,
468 m_toolSeparation;
469
470 // the size of the toolbar bitmaps
471 wxCoord m_defaultWidth, m_defaultHeight;
472
473 private:
474 DECLARE_EVENT_TABLE()
475 DECLARE_CLASS(wxToolBarBase)
476 };
477
478 #endif // wxUSE_TOOLBAR
479
480 #endif
481 // _WX_TBARBASE_H_
482