No changes, just refactor wxToolBarToolBase ctors.
[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
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
11
12 #ifndef _WX_TBARBASE_H_
13 #define _WX_TBARBASE_H_
14
15 // ----------------------------------------------------------------------------
16 // headers
17 // ----------------------------------------------------------------------------
18
19 #include "wx/defs.h"
20
21 #if wxUSE_TOOLBAR
22
23 #include "wx/bitmap.h"
24 #include "wx/list.h"
25 #include "wx/control.h"
26
27 class WXDLLIMPEXP_FWD_CORE wxToolBarBase;
28 class WXDLLIMPEXP_FWD_CORE wxToolBarToolBase;
29 class WXDLLIMPEXP_FWD_CORE wxImage;
30
31 // ----------------------------------------------------------------------------
32 // constants
33 // ----------------------------------------------------------------------------
34
35 extern WXDLLIMPEXP_DATA_CORE(const char) wxToolBarNameStr[];
36 extern WXDLLIMPEXP_DATA_CORE(const wxSize) wxDefaultSize;
37 extern WXDLLIMPEXP_DATA_CORE(const wxPoint) wxDefaultPosition;
38
39 enum wxToolBarToolStyle
40 {
41 wxTOOL_STYLE_BUTTON = 1,
42 wxTOOL_STYLE_SEPARATOR = 2,
43 wxTOOL_STYLE_CONTROL
44 };
45
46 // ----------------------------------------------------------------------------
47 // wxToolBarTool is a toolbar element.
48 //
49 // It has a unique id (except for the separators which always have id wxID_ANY), the
50 // style (telling whether it is a normal button, separator or a control), the
51 // state (toggled or not, enabled or not) and short and long help strings. The
52 // default implementations use the short help string for the tooltip text which
53 // is popped up when the mouse pointer enters the tool and the long help string
54 // for the applications status bar.
55 // ----------------------------------------------------------------------------
56
57 class WXDLLIMPEXP_CORE wxToolBarToolBase : public wxObject
58 {
59 public:
60 // ctors & dtor
61 // ------------
62
63 // generic ctor for any kind of tool
64 wxToolBarToolBase(wxToolBarBase *tbar = NULL,
65 int toolid = wxID_SEPARATOR,
66 const wxString& label = wxEmptyString,
67 const wxBitmap& bmpNormal = wxNullBitmap,
68 const wxBitmap& bmpDisabled = wxNullBitmap,
69 wxItemKind kind = wxITEM_NORMAL,
70 wxObject *clientData = NULL,
71 const wxString& shortHelpString = wxEmptyString,
72 const wxString& longHelpString = wxEmptyString)
73 : m_label(label),
74 m_shortHelpString(shortHelpString),
75 m_longHelpString(longHelpString)
76 {
77 Init
78 (
79 tbar,
80 toolid == wxID_SEPARATOR ? wxTOOL_STYLE_SEPARATOR
81 : wxTOOL_STYLE_BUTTON,
82 toolid == wxID_ANY ? wxWindow::NewControlId()
83 : toolid,
84 kind
85 );
86
87 m_clientData = clientData;
88
89 m_bmpNormal = bmpNormal;
90 m_bmpDisabled = bmpDisabled;
91 }
92
93 // ctor for controls only
94 wxToolBarToolBase(wxToolBarBase *tbar,
95 wxControl *control,
96 const wxString& label)
97 : m_label(label)
98 {
99 Init(tbar, wxTOOL_STYLE_CONTROL, control->GetId(), wxITEM_MAX);
100
101 m_control = control;
102 }
103
104 m_toolStyle = wxTOOL_STYLE_CONTROL;
105
106 m_dropdownMenu = 0;
107 }
108
109 virtual ~wxToolBarToolBase();
110
111 // accessors
112 // ---------
113
114 // general
115 int GetId() const { return m_id; }
116
117 wxControl *GetControl() const
118 {
119 wxASSERT_MSG( IsControl(), wxT("this toolbar tool is not a control") );
120
121 return m_control;
122 }
123
124 wxToolBarBase *GetToolBar() const { return m_tbar; }
125
126 // style
127 bool IsButton() const { return m_toolStyle == wxTOOL_STYLE_BUTTON; }
128 bool IsControl() const { return m_toolStyle == wxTOOL_STYLE_CONTROL; }
129 bool IsSeparator() const { return m_toolStyle == wxTOOL_STYLE_SEPARATOR; }
130 int GetStyle() const { return m_toolStyle; }
131 wxItemKind GetKind() const
132 {
133 wxASSERT_MSG( IsButton(), wxT("only makes sense for buttons") );
134
135 return m_kind;
136 }
137
138 // state
139 bool IsEnabled() const { return m_enabled; }
140 bool IsToggled() const { return m_toggled; }
141 bool CanBeToggled() const
142 { return m_kind == wxITEM_CHECK || m_kind == wxITEM_RADIO; }
143
144 // attributes
145 const wxBitmap& GetNormalBitmap() const { return m_bmpNormal; }
146 const wxBitmap& GetDisabledBitmap() const { return m_bmpDisabled; }
147
148 const wxBitmap& GetBitmap() const
149 { return IsEnabled() ? GetNormalBitmap() : GetDisabledBitmap(); }
150
151 const wxString& GetLabel() const { return m_label; }
152
153 const wxString& GetShortHelp() const { return m_shortHelpString; }
154 const wxString& GetLongHelp() const { return m_longHelpString; }
155
156 wxObject *GetClientData() const
157 {
158 if ( m_toolStyle == wxTOOL_STYLE_CONTROL )
159 {
160 return (wxObject*)m_control->GetClientData();
161 }
162 else
163 {
164 return m_clientData;
165 }
166 }
167
168 // modifiers: return true if the state really changed
169 virtual bool Enable(bool enable);
170 virtual bool Toggle(bool toggle);
171 virtual bool SetToggle(bool toggle);
172 virtual bool SetShortHelp(const wxString& help);
173 virtual bool SetLongHelp(const wxString& help);
174
175 void Toggle() { Toggle(!IsToggled()); }
176
177 virtual void SetNormalBitmap(const wxBitmap& bmp) { m_bmpNormal = bmp; }
178 virtual void SetDisabledBitmap(const wxBitmap& bmp) { m_bmpDisabled = bmp; }
179
180 virtual void SetLabel(const wxString& label) { m_label = label; }
181
182 void SetClientData(wxObject *clientData)
183 {
184 if ( m_toolStyle == wxTOOL_STYLE_CONTROL )
185 {
186 m_control->SetClientData(clientData);
187 }
188 else
189 {
190 m_clientData = clientData;
191 }
192 }
193
194 // add tool to/remove it from a toolbar
195 virtual void Detach() { m_tbar = NULL; }
196 virtual void Attach(wxToolBarBase *tbar) { m_tbar = tbar; }
197
198 // these methods are only for tools of wxITEM_DROPDOWN kind (but even such
199 // tools can have a NULL associated menu)
200 virtual void SetDropdownMenu(wxMenu *menu);
201 wxMenu *GetDropdownMenu() const { return m_dropdownMenu; }
202
203 protected:
204 // common part of all ctors
205 void Init(wxToolBarBase *tbar,
206 wxToolBarToolStyle style,
207 int toolid,
208 wxItemKind kind)
209 {
210 m_tbar = tbar;
211 m_toolStyle = style;
212 m_id = toolid;
213 m_kind = kind;
214
215 m_clientData = NULL;
216
217 m_toggled = false;
218 m_enabled = true;
219
220 m_dropdownMenu = NULL;
221 }
222
223 wxToolBarBase *m_tbar; // the toolbar to which we belong (may be NULL)
224
225 // tool parameters
226 int m_toolStyle; // see enum wxToolBarToolStyle
227 wxWindowIDRef m_id; // the tool id, wxID_SEPARATOR for separator
228 wxItemKind m_kind; // for normal buttons may be wxITEM_NORMAL/CHECK/RADIO
229
230 // as controls have their own client data, no need to waste memory
231 union
232 {
233 wxObject *m_clientData;
234 wxControl *m_control;
235 };
236
237 // tool state
238 bool m_toggled;
239 bool m_enabled;
240
241 // normal and disabled bitmaps for the tool, both can be invalid
242 wxBitmap m_bmpNormal;
243 wxBitmap m_bmpDisabled;
244
245 // the button label
246 wxString m_label;
247
248 // short and long help strings
249 wxString m_shortHelpString;
250 wxString m_longHelpString;
251
252 wxMenu *m_dropdownMenu;
253
254 DECLARE_DYNAMIC_CLASS_NO_COPY(wxToolBarToolBase)
255 };
256
257 // a list of toolbar tools
258 WX_DECLARE_EXPORTED_LIST(wxToolBarToolBase, wxToolBarToolsList);
259
260 // ----------------------------------------------------------------------------
261 // the base class for all toolbars
262 // ----------------------------------------------------------------------------
263
264 class WXDLLIMPEXP_CORE wxToolBarBase : public wxControl
265 {
266 public:
267 wxToolBarBase();
268 virtual ~wxToolBarBase();
269
270 // toolbar construction
271 // --------------------
272
273 // the full AddTool() function
274 //
275 // If bmpDisabled is wxNullBitmap, a shadowed version of the normal bitmap
276 // is created and used as the disabled image.
277 wxToolBarToolBase *AddTool(int toolid,
278 const wxString& label,
279 const wxBitmap& bitmap,
280 const wxBitmap& bmpDisabled,
281 wxItemKind kind = wxITEM_NORMAL,
282 const wxString& shortHelp = wxEmptyString,
283 const wxString& longHelp = wxEmptyString,
284 wxObject *data = NULL)
285 {
286 return DoAddTool(toolid, label, bitmap, bmpDisabled, kind,
287 shortHelp, longHelp, data);
288 }
289
290 // the most common AddTool() version
291 wxToolBarToolBase *AddTool(int toolid,
292 const wxString& label,
293 const wxBitmap& bitmap,
294 const wxString& shortHelp = wxEmptyString,
295 wxItemKind kind = wxITEM_NORMAL)
296 {
297 return AddTool(toolid, label, bitmap, wxNullBitmap, kind, shortHelp);
298 }
299
300 // add a check tool, i.e. a tool which can be toggled
301 wxToolBarToolBase *AddCheckTool(int toolid,
302 const wxString& label,
303 const wxBitmap& bitmap,
304 const wxBitmap& bmpDisabled = wxNullBitmap,
305 const wxString& shortHelp = wxEmptyString,
306 const wxString& longHelp = wxEmptyString,
307 wxObject *data = NULL)
308 {
309 return AddTool(toolid, label, bitmap, bmpDisabled, wxITEM_CHECK,
310 shortHelp, longHelp, data);
311 }
312
313 // add a radio tool, i.e. a tool which can be toggled and releases any
314 // other toggled radio tools in the same group when it happens
315 wxToolBarToolBase *AddRadioTool(int toolid,
316 const wxString& label,
317 const wxBitmap& bitmap,
318 const wxBitmap& bmpDisabled = wxNullBitmap,
319 const wxString& shortHelp = wxEmptyString,
320 const wxString& longHelp = wxEmptyString,
321 wxObject *data = NULL)
322 {
323 return AddTool(toolid, label, bitmap, bmpDisabled, wxITEM_RADIO,
324 shortHelp, longHelp, data);
325 }
326
327
328 // insert the new tool at the given position, if pos == GetToolsCount(), it
329 // is equivalent to AddTool()
330 virtual wxToolBarToolBase *InsertTool
331 (
332 size_t pos,
333 int toolid,
334 const wxString& label,
335 const wxBitmap& bitmap,
336 const wxBitmap& bmpDisabled = wxNullBitmap,
337 wxItemKind kind = wxITEM_NORMAL,
338 const wxString& shortHelp = wxEmptyString,
339 const wxString& longHelp = wxEmptyString,
340 wxObject *clientData = NULL
341 );
342
343 virtual wxToolBarToolBase *AddTool (wxToolBarToolBase *tool);
344 virtual wxToolBarToolBase *InsertTool (size_t pos, wxToolBarToolBase *tool);
345
346 // add an arbitrary control to the toolbar (notice that the control will be
347 // deleted by the toolbar and that it will also adjust its position/size)
348 //
349 // the label is optional and, if specified, will be shown near the control
350 // NB: the control should have toolbar as its parent
351 virtual wxToolBarToolBase *
352 AddControl(wxControl *control, const wxString& label = wxEmptyString);
353
354 virtual wxToolBarToolBase *
355 InsertControl(size_t pos, wxControl *control,
356 const wxString& label = wxEmptyString);
357
358 // get the control with the given id or return NULL
359 virtual wxControl *FindControl( int toolid );
360
361 // add a separator to the toolbar
362 virtual wxToolBarToolBase *AddSeparator();
363 virtual wxToolBarToolBase *InsertSeparator(size_t pos);
364
365 // remove the tool from the toolbar: the caller is responsible for actually
366 // deleting the pointer
367 virtual wxToolBarToolBase *RemoveTool(int toolid);
368
369 // delete tool either by index or by position
370 virtual bool DeleteToolByPos(size_t pos);
371 virtual bool DeleteTool(int toolid);
372
373 // delete all tools
374 virtual void ClearTools();
375
376 // must be called after all buttons have been created to finish toolbar
377 // initialisation
378 //
379 // derived class versions should call the base one first, before doing
380 // platform-specific stuff
381 virtual bool Realize();
382
383 // tools state
384 // -----------
385
386 virtual void EnableTool(int toolid, bool enable);
387 virtual void ToggleTool(int toolid, bool toggle);
388
389 // Set this to be togglable (or not)
390 virtual void SetToggle(int toolid, bool toggle);
391
392 // set/get tools client data (not for controls)
393 virtual wxObject *GetToolClientData(int toolid) const;
394 virtual void SetToolClientData(int toolid, wxObject *clientData);
395
396 // returns tool pos, or wxNOT_FOUND if tool isn't found
397 virtual int GetToolPos(int id) const;
398
399 // return true if the tool is toggled
400 virtual bool GetToolState(int toolid) const;
401
402 virtual bool GetToolEnabled(int toolid) const;
403
404 virtual void SetToolShortHelp(int toolid, const wxString& helpString);
405 virtual wxString GetToolShortHelp(int toolid) const;
406 virtual void SetToolLongHelp(int toolid, const wxString& helpString);
407 virtual wxString GetToolLongHelp(int toolid) const;
408
409 virtual void SetToolNormalBitmap(int WXUNUSED(id),
410 const wxBitmap& WXUNUSED(bitmap)) {}
411 virtual void SetToolDisabledBitmap(int WXUNUSED(id),
412 const wxBitmap& WXUNUSED(bitmap)) {}
413
414
415 // margins/packing/separation
416 // --------------------------
417
418 virtual void SetMargins(int x, int y);
419 void SetMargins(const wxSize& size)
420 { SetMargins((int) size.x, (int) size.y); }
421 virtual void SetToolPacking(int packing)
422 { m_toolPacking = packing; }
423 virtual void SetToolSeparation(int separation)
424 { m_toolSeparation = separation; }
425
426 virtual wxSize GetToolMargins() const { return wxSize(m_xMargin, m_yMargin); }
427 virtual int GetToolPacking() const { return m_toolPacking; }
428 virtual int GetToolSeparation() const { return m_toolSeparation; }
429
430 // toolbar geometry
431 // ----------------
432
433 // set the number of toolbar rows
434 virtual void SetRows(int nRows);
435
436 // the toolbar can wrap - limit the number of columns or rows it may take
437 void SetMaxRowsCols(int rows, int cols)
438 { m_maxRows = rows; m_maxCols = cols; }
439 int GetMaxRows() const { return m_maxRows; }
440 int GetMaxCols() const { return m_maxCols; }
441
442 // get/set the size of the bitmaps used by the toolbar: should be called
443 // before adding any tools to the toolbar
444 virtual void SetToolBitmapSize(const wxSize& size)
445 { m_defaultWidth = size.x; m_defaultHeight = size.y; }
446 virtual wxSize GetToolBitmapSize() const
447 { return wxSize(m_defaultWidth, m_defaultHeight); }
448
449 // the button size in some implementations is bigger than the bitmap size:
450 // get the total button size (by default the same as bitmap size)
451 virtual wxSize GetToolSize() const
452 { return GetToolBitmapSize(); }
453
454 // returns a (non separator) tool containing the point (x, y) or NULL if
455 // there is no tool at this point (corrdinates are client)
456 virtual wxToolBarToolBase *FindToolForPosition(wxCoord x,
457 wxCoord y) const = 0;
458
459 // find the tool by id
460 wxToolBarToolBase *FindById(int toolid) const;
461
462 // return true if this is a vertical toolbar, otherwise false
463 bool IsVertical() const;
464
465 #if WXWIN_COMPATIBILITY_2_8
466 // the old versions of the various methods kept for compatibility
467 // don't use in the new code!
468 // --------------------------------------------------------------
469 wxDEPRECATED_INLINE(
470 wxToolBarToolBase *AddTool(int toolid,
471 const wxBitmap& bitmap,
472 const wxBitmap& bmpDisabled,
473 bool toggle = false,
474 wxObject *clientData = NULL,
475 const wxString& shortHelpString = wxEmptyString,
476 const wxString& longHelpString = wxEmptyString)
477 ,
478 return AddTool(toolid, wxEmptyString,
479 bitmap, bmpDisabled,
480 toggle ? wxITEM_CHECK : wxITEM_NORMAL,
481 shortHelpString, longHelpString, clientData);
482 )
483 wxDEPRECATED_INLINE(
484 wxToolBarToolBase *AddTool(int toolid,
485 const wxBitmap& bitmap,
486 const wxString& shortHelpString = wxEmptyString,
487 const wxString& longHelpString = wxEmptyString)
488 ,
489 return AddTool(toolid, wxEmptyString,
490 bitmap, wxNullBitmap, wxITEM_NORMAL,
491 shortHelpString, longHelpString, NULL);
492 )
493 wxDEPRECATED_INLINE(
494 wxToolBarToolBase *AddTool(int toolid,
495 const wxBitmap& bitmap,
496 const wxBitmap& bmpDisabled,
497 bool toggle,
498 wxCoord xPos,
499 wxCoord yPos = wxDefaultCoord,
500 wxObject *clientData = NULL,
501 const wxString& shortHelp = wxEmptyString,
502 const wxString& longHelp = wxEmptyString)
503 ,
504 return DoAddTool(toolid, wxEmptyString, bitmap, bmpDisabled,
505 toggle ? wxITEM_CHECK : wxITEM_NORMAL,
506 shortHelp, longHelp, clientData, xPos, yPos);
507 )
508 wxDEPRECATED_INLINE(
509 wxToolBarToolBase *InsertTool(size_t pos,
510 int toolid,
511 const wxBitmap& bitmap,
512 const wxBitmap& bmpDisabled = wxNullBitmap,
513 bool toggle = false,
514 wxObject *clientData = NULL,
515 const wxString& shortHelp = wxEmptyString,
516 const wxString& longHelp = wxEmptyString)
517 ,
518 return InsertTool(pos, toolid, wxEmptyString, bitmap, bmpDisabled,
519 toggle ? wxITEM_CHECK : wxITEM_NORMAL,
520 shortHelp, longHelp, clientData);
521 )
522 #endif // WXWIN_COMPATIBILITY_2_8
523
524 // event handlers
525 // --------------
526
527 // NB: these functions are deprecated, use EVT_TOOL_XXX() instead!
528
529 // Only allow toggle if returns true. Call when left button up.
530 virtual bool OnLeftClick(int toolid, bool toggleDown);
531
532 // Call when right button down.
533 virtual void OnRightClick(int toolid, long x, long y);
534
535 // Called when the mouse cursor enters a tool bitmap.
536 // Argument is wxID_ANY if mouse is exiting the toolbar.
537 virtual void OnMouseEnter(int toolid);
538
539 // more deprecated functions
540 // -------------------------
541
542 // use GetToolMargins() instead
543 wxSize GetMargins() const { return GetToolMargins(); }
544
545 // implementation only from now on
546 // -------------------------------
547
548 size_t GetToolsCount() const { return m_tools.GetCount(); }
549
550 // Do the toolbar button updates (check for EVT_UPDATE_UI handlers)
551 virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE) ;
552
553 // don't want toolbars to accept the focus
554 virtual bool AcceptsFocus() const { return false; }
555
556 // Set dropdown menu
557 bool SetDropdownMenu(int toolid, wxMenu *menu);
558
559 protected:
560 // to implement in derived classes
561 // -------------------------------
562
563 // create a new toolbar tool and add it to the toolbar, this is typically
564 // implemented by just calling InsertTool()
565 virtual wxToolBarToolBase *DoAddTool
566 (
567 int toolid,
568 const wxString& label,
569 const wxBitmap& bitmap,
570 const wxBitmap& bmpDisabled,
571 wxItemKind kind,
572 const wxString& shortHelp = wxEmptyString,
573 const wxString& longHelp = wxEmptyString,
574 wxObject *clientData = NULL,
575 wxCoord xPos = wxDefaultCoord,
576 wxCoord yPos = wxDefaultCoord
577 );
578
579 // the tool is not yet inserted into m_tools list when this function is
580 // called and will only be added to it if this function succeeds
581 virtual bool DoInsertTool(size_t pos, wxToolBarToolBase *tool) = 0;
582
583 // the tool is still in m_tools list when this function is called, it will
584 // only be deleted from it if it succeeds
585 virtual bool DoDeleteTool(size_t pos, wxToolBarToolBase *tool) = 0;
586
587 // called when the tools enabled flag changes
588 virtual void DoEnableTool(wxToolBarToolBase *tool, bool enable) = 0;
589
590 // called when the tool is toggled
591 virtual void DoToggleTool(wxToolBarToolBase *tool, bool toggle) = 0;
592
593 // called when the tools "can be toggled" flag changes
594 virtual void DoSetToggle(wxToolBarToolBase *tool, bool toggle) = 0;
595
596 // the functions to create toolbar tools
597 virtual wxToolBarToolBase *CreateTool(int toolid,
598 const wxString& label,
599 const wxBitmap& bmpNormal,
600 const wxBitmap& bmpDisabled,
601 wxItemKind kind,
602 wxObject *clientData,
603 const wxString& shortHelp,
604 const wxString& longHelp) = 0;
605
606 virtual wxToolBarToolBase *CreateTool(wxControl *control,
607 const wxString& label) = 0;
608
609 // helper functions
610 // ----------------
611
612 // call this from derived class ctor/Create() to ensure that we have either
613 // wxTB_HORIZONTAL or wxTB_VERTICAL style, there is a lot of existing code
614 // which randomly checks either one or the other of them and gets confused
615 // if neither is set (and making one of them 0 is not an option neither as
616 // then the existing tests would break down)
617 void FixupStyle();
618
619 // un-toggle all buttons in the same radio group
620 void UnToggleRadioGroup(wxToolBarToolBase *tool);
621
622 // make the size of the buttons big enough to fit the largest bitmap size
623 void AdjustToolBitmapSize();
624
625 // calls InsertTool() and deletes the tool if inserting it failed
626 wxToolBarToolBase *DoInsertNewTool(size_t pos, wxToolBarToolBase *tool)
627 {
628 if ( !InsertTool(pos, tool) )
629 {
630 delete tool;
631 return NULL;
632 }
633
634 return tool;
635 }
636
637 // the list of all our tools
638 wxToolBarToolsList m_tools;
639
640 // the offset of the first tool
641 int m_xMargin;
642 int m_yMargin;
643
644 // the maximum number of toolbar rows/columns
645 int m_maxRows;
646 int m_maxCols;
647
648 // the tool packing and separation
649 int m_toolPacking,
650 m_toolSeparation;
651
652 // the size of the toolbar bitmaps
653 wxCoord m_defaultWidth, m_defaultHeight;
654
655 private:
656 DECLARE_EVENT_TABLE()
657 wxDECLARE_NO_COPY_CLASS(wxToolBarBase);
658 };
659
660 // deprecated function for creating the image for disabled buttons, use
661 // wxImage::ConvertToGreyscale() instead
662 #if WXWIN_COMPATIBILITY_2_8
663
664 wxDEPRECATED( bool wxCreateGreyedImage(const wxImage& in, wxImage& out) );
665
666 #endif // WXWIN_COMPATIBILITY_2_8
667
668
669 #endif // wxUSE_TOOLBAR
670
671 #endif
672 // _WX_TBARBASE_H_
673