1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: Base class for toolbar classes
4 // Author: Julian Smart
8 // Copyright: (c) Julian Smart
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_TBARBASE_H_
13 #define _WX_TBARBASE_H_
15 // ----------------------------------------------------------------------------
17 // ----------------------------------------------------------------------------
23 #include "wx/bitmap.h"
25 #include "wx/control.h"
27 class WXDLLIMPEXP_FWD_CORE wxToolBarBase
;
28 class WXDLLIMPEXP_FWD_CORE wxToolBarToolBase
;
29 class WXDLLIMPEXP_FWD_CORE wxImage
;
31 // ----------------------------------------------------------------------------
33 // ----------------------------------------------------------------------------
35 extern WXDLLEXPORT_DATA(const wxChar
) wxToolBarNameStr
[];
36 extern WXDLLEXPORT_DATA(const wxSize
) wxDefaultSize
;
37 extern WXDLLEXPORT_DATA(const wxPoint
) wxDefaultPosition
;
39 enum wxToolBarToolStyle
41 wxTOOL_STYLE_BUTTON
= 1,
42 wxTOOL_STYLE_SEPARATOR
= 2,
46 // ----------------------------------------------------------------------------
47 // wxToolBarTool is a toolbar element.
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 // ----------------------------------------------------------------------------
57 class WXDLLEXPORT wxToolBarToolBase
: public wxObject
63 wxToolBarToolBase(wxToolBarBase
*tbar
= (wxToolBarBase
*)NULL
,
64 int toolid
= wxID_SEPARATOR
,
65 const wxString
& label
= wxEmptyString
,
66 const wxBitmap
& bmpNormal
= wxNullBitmap
,
67 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
68 wxItemKind kind
= wxITEM_NORMAL
,
69 wxObject
*clientData
= (wxObject
*) NULL
,
70 const wxString
& shortHelpString
= wxEmptyString
,
71 const wxString
& longHelpString
= wxEmptyString
)
73 m_shortHelpString(shortHelpString
),
74 m_longHelpString(longHelpString
),
80 m_id
= wxWindow::NewControlId();
81 m_clientData
= clientData
;
83 m_bmpNormal
= bmpNormal
;
84 m_bmpDisabled
= bmpDisabled
;
91 m_toolStyle
= toolid
== wxID_SEPARATOR
? wxTOOL_STYLE_SEPARATOR
92 : wxTOOL_STYLE_BUTTON
;
95 wxToolBarToolBase(wxToolBarBase
*tbar
,
97 const wxString
& label
)
102 m_id
= control
->GetId();
104 m_kind
= wxITEM_MAX
; // invalid value
109 m_toolStyle
= wxTOOL_STYLE_CONTROL
;
114 virtual ~wxToolBarToolBase();
120 int GetId() const { return m_id
; }
122 wxControl
*GetControl() const
124 wxASSERT_MSG( IsControl(), _T("this toolbar tool is not a control") );
129 wxToolBarBase
*GetToolBar() const { return m_tbar
; }
132 bool IsButton() const { return m_toolStyle
== wxTOOL_STYLE_BUTTON
; }
133 bool IsControl() const { return m_toolStyle
== wxTOOL_STYLE_CONTROL
; }
134 bool IsSeparator() const { return m_toolStyle
== wxTOOL_STYLE_SEPARATOR
; }
135 int GetStyle() const { return m_toolStyle
; }
136 wxItemKind
GetKind() const
138 wxASSERT_MSG( IsButton(), _T("only makes sense for buttons") );
144 bool IsEnabled() const { return m_enabled
; }
145 bool IsToggled() const { return m_toggled
; }
146 bool CanBeToggled() const
147 { return m_kind
== wxITEM_CHECK
|| m_kind
== wxITEM_RADIO
; }
150 const wxBitmap
& GetNormalBitmap() const { return m_bmpNormal
; }
151 const wxBitmap
& GetDisabledBitmap() const { return m_bmpDisabled
; }
153 const wxBitmap
& GetBitmap() const
154 { return IsEnabled() ? GetNormalBitmap() : GetDisabledBitmap(); }
156 const wxString
& GetLabel() const { return m_label
; }
158 const wxString
& GetShortHelp() const { return m_shortHelpString
; }
159 const wxString
& GetLongHelp() const { return m_longHelpString
; }
161 wxObject
*GetClientData() const
163 if ( m_toolStyle
== wxTOOL_STYLE_CONTROL
)
165 return (wxObject
*)m_control
->GetClientData();
173 // modifiers: return true if the state really changed
174 bool Enable(bool enable
);
175 bool Toggle(bool toggle
);
176 bool SetToggle(bool toggle
);
177 bool SetShortHelp(const wxString
& help
);
178 bool SetLongHelp(const wxString
& help
);
180 void Toggle() { Toggle(!IsToggled()); }
182 void SetNormalBitmap(const wxBitmap
& bmp
) { m_bmpNormal
= bmp
; }
183 void SetDisabledBitmap(const wxBitmap
& bmp
) { m_bmpDisabled
= bmp
; }
185 virtual void SetLabel(const wxString
& label
) { m_label
= label
; }
187 void SetClientData(wxObject
*clientData
)
189 if ( m_toolStyle
== wxTOOL_STYLE_CONTROL
)
191 m_control
->SetClientData(clientData
);
195 m_clientData
= clientData
;
199 // add tool to/remove it from a toolbar
200 virtual void Detach() { m_tbar
= (wxToolBarBase
*)NULL
; }
201 virtual void Attach(wxToolBarBase
*tbar
) { m_tbar
= tbar
; }
203 // these methods are only for tools of wxITEM_DROPDOWN kind (but even such
204 // tools can have a NULL associated menu)
205 void SetDropdownMenu(wxMenu
*menu
);
206 wxMenu
*GetDropdownMenu() const { return m_dropdownMenu
; }
209 wxToolBarBase
*m_tbar
; // the toolbar to which we belong (may be NULL)
212 int m_toolStyle
; // see enum wxToolBarToolStyle
213 int m_id
; // the tool id, wxID_SEPARATOR for separator
214 wxItemKind m_kind
; // for normal buttons may be wxITEM_NORMAL/CHECK/RADIO
216 // as controls have their own client data, no need to waste memory
219 wxObject
*m_clientData
;
220 wxControl
*m_control
;
227 // normal and disabled bitmaps for the tool, both can be invalid
228 wxBitmap m_bmpNormal
;
229 wxBitmap m_bmpDisabled
;
234 // short and long help strings
235 wxString m_shortHelpString
;
236 wxString m_longHelpString
;
238 wxMenu
*m_dropdownMenu
;
240 DECLARE_DYNAMIC_CLASS_NO_COPY(wxToolBarToolBase
)
243 // a list of toolbar tools
244 WX_DECLARE_EXPORTED_LIST(wxToolBarToolBase
, wxToolBarToolsList
);
246 // ----------------------------------------------------------------------------
247 // the base class for all toolbars
248 // ----------------------------------------------------------------------------
250 class WXDLLEXPORT wxToolBarBase
: public wxControl
254 virtual ~wxToolBarBase();
256 // toolbar construction
257 // --------------------
259 // the full AddTool() function
261 // If bmpDisabled is wxNullBitmap, a shadowed version of the normal bitmap
262 // is created and used as the disabled image.
263 wxToolBarToolBase
*AddTool(int toolid
,
264 const wxString
& label
,
265 const wxBitmap
& bitmap
,
266 const wxBitmap
& bmpDisabled
,
267 wxItemKind kind
= wxITEM_NORMAL
,
268 const wxString
& shortHelp
= wxEmptyString
,
269 const wxString
& longHelp
= wxEmptyString
,
270 wxObject
*data
= NULL
)
272 return DoAddTool(toolid
, label
, bitmap
, bmpDisabled
, kind
,
273 shortHelp
, longHelp
, data
);
276 // the most common AddTool() version
277 wxToolBarToolBase
*AddTool(int toolid
,
278 const wxString
& label
,
279 const wxBitmap
& bitmap
,
280 const wxString
& shortHelp
= wxEmptyString
,
281 wxItemKind kind
= wxITEM_NORMAL
)
283 return AddTool(toolid
, label
, bitmap
, wxNullBitmap
, kind
, shortHelp
);
286 // add a check tool, i.e. a tool which can be toggled
287 wxToolBarToolBase
*AddCheckTool(int toolid
,
288 const wxString
& label
,
289 const wxBitmap
& bitmap
,
290 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
291 const wxString
& shortHelp
= wxEmptyString
,
292 const wxString
& longHelp
= wxEmptyString
,
293 wxObject
*data
= NULL
)
295 return AddTool(toolid
, label
, bitmap
, bmpDisabled
, wxITEM_CHECK
,
296 shortHelp
, longHelp
, data
);
299 // add a radio tool, i.e. a tool which can be toggled and releases any
300 // other toggled radio tools in the same group when it happens
301 wxToolBarToolBase
*AddRadioTool(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
)
309 return AddTool(toolid
, label
, bitmap
, bmpDisabled
, wxITEM_RADIO
,
310 shortHelp
, longHelp
, data
);
314 // insert the new tool at the given position, if pos == GetToolsCount(), it
315 // is equivalent to AddTool()
316 virtual wxToolBarToolBase
*InsertTool
320 const wxString
& label
,
321 const wxBitmap
& bitmap
,
322 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
323 wxItemKind kind
= wxITEM_NORMAL
,
324 const wxString
& shortHelp
= wxEmptyString
,
325 const wxString
& longHelp
= wxEmptyString
,
326 wxObject
*clientData
= NULL
329 virtual wxToolBarToolBase
*AddTool (wxToolBarToolBase
*tool
);
330 virtual wxToolBarToolBase
*InsertTool (size_t pos
, wxToolBarToolBase
*tool
);
332 // add an arbitrary control to the toolbar (notice that the control will be
333 // deleted by the toolbar and that it will also adjust its position/size)
335 // the label is optional and, if specified, will be shown near the control
336 // NB: the control should have toolbar as its parent
337 virtual wxToolBarToolBase
*
338 AddControl(wxControl
*control
, const wxString
& label
= wxEmptyString
);
340 virtual wxToolBarToolBase
*
341 InsertControl(size_t pos
, wxControl
*control
,
342 const wxString
& label
= wxEmptyString
);
344 // get the control with the given id or return NULL
345 virtual wxControl
*FindControl( int toolid
);
347 // add a separator to the toolbar
348 virtual wxToolBarToolBase
*AddSeparator();
349 virtual wxToolBarToolBase
*InsertSeparator(size_t pos
);
351 // remove the tool from the toolbar: the caller is responsible for actually
352 // deleting the pointer
353 virtual wxToolBarToolBase
*RemoveTool(int toolid
);
355 // delete tool either by index or by position
356 virtual bool DeleteToolByPos(size_t pos
);
357 virtual bool DeleteTool(int toolid
);
360 virtual void ClearTools();
362 // must be called after all buttons have been created to finish toolbar
364 virtual bool Realize();
369 virtual void EnableTool(int toolid
, bool enable
);
370 virtual void ToggleTool(int toolid
, bool toggle
);
372 // Set this to be togglable (or not)
373 virtual void SetToggle(int toolid
, bool toggle
);
375 // set/get tools client data (not for controls)
376 virtual wxObject
*GetToolClientData(int toolid
) const;
377 virtual void SetToolClientData(int toolid
, wxObject
*clientData
);
379 // returns tool pos, or wxNOT_FOUND if tool isn't found
380 virtual int GetToolPos(int id
) const;
382 // return true if the tool is toggled
383 virtual bool GetToolState(int toolid
) const;
385 virtual bool GetToolEnabled(int toolid
) const;
387 virtual void SetToolShortHelp(int toolid
, const wxString
& helpString
);
388 virtual wxString
GetToolShortHelp(int toolid
) const;
389 virtual void SetToolLongHelp(int toolid
, const wxString
& helpString
);
390 virtual wxString
GetToolLongHelp(int toolid
) const;
392 virtual void SetToolNormalBitmap(int WXUNUSED(id
),
393 const wxBitmap
& WXUNUSED(bitmap
)) {}
394 virtual void SetToolDisabledBitmap(int WXUNUSED(id
),
395 const wxBitmap
& WXUNUSED(bitmap
)) {}
398 // margins/packing/separation
399 // --------------------------
401 virtual void SetMargins(int x
, int y
);
402 void SetMargins(const wxSize
& size
)
403 { SetMargins((int) size
.x
, (int) size
.y
); }
404 virtual void SetToolPacking(int packing
)
405 { m_toolPacking
= packing
; }
406 virtual void SetToolSeparation(int separation
)
407 { m_toolSeparation
= separation
; }
409 virtual wxSize
GetToolMargins() const { return wxSize(m_xMargin
, m_yMargin
); }
410 virtual int GetToolPacking() const { return m_toolPacking
; }
411 virtual int GetToolSeparation() const { return m_toolSeparation
; }
416 // set the number of toolbar rows
417 virtual void SetRows(int nRows
);
419 // the toolbar can wrap - limit the number of columns or rows it may take
420 void SetMaxRowsCols(int rows
, int cols
)
421 { m_maxRows
= rows
; m_maxCols
= cols
; }
422 int GetMaxRows() const { return m_maxRows
; }
423 int GetMaxCols() const { return m_maxCols
; }
425 // get/set the size of the bitmaps used by the toolbar: should be called
426 // before adding any tools to the toolbar
427 virtual void SetToolBitmapSize(const wxSize
& size
)
428 { m_defaultWidth
= size
.x
; m_defaultHeight
= size
.y
; }
429 virtual wxSize
GetToolBitmapSize() const
430 { return wxSize(m_defaultWidth
, m_defaultHeight
); }
432 // the button size in some implementations is bigger than the bitmap size:
433 // get the total button size (by default the same as bitmap size)
434 virtual wxSize
GetToolSize() const
435 { return GetToolBitmapSize(); }
437 // returns a (non separator) tool containing the point (x, y) or NULL if
438 // there is no tool at this point (corrdinates are client)
439 virtual wxToolBarToolBase
*FindToolForPosition(wxCoord x
,
440 wxCoord y
) const = 0;
442 // find the tool by id
443 wxToolBarToolBase
*FindById(int toolid
) const;
445 // return true if this is a vertical toolbar, otherwise false
446 bool IsVertical() const { return HasFlag(wxTB_LEFT
| wxTB_RIGHT
); }
449 // the old versions of the various methods kept for compatibility
450 // don't use in the new code!
451 // --------------------------------------------------------------
453 wxToolBarToolBase
*AddTool(int toolid
,
454 const wxBitmap
& bitmap
,
455 const wxBitmap
& bmpDisabled
,
457 wxObject
*clientData
= NULL
,
458 const wxString
& shortHelpString
= wxEmptyString
,
459 const wxString
& longHelpString
= wxEmptyString
)
461 return AddTool(toolid
, wxEmptyString
,
463 toggle
? wxITEM_CHECK
: wxITEM_NORMAL
,
464 shortHelpString
, longHelpString
, clientData
);
467 wxToolBarToolBase
*AddTool(int toolid
,
468 const wxBitmap
& bitmap
,
469 const wxString
& shortHelpString
= wxEmptyString
,
470 const wxString
& longHelpString
= wxEmptyString
)
472 return AddTool(toolid
, wxEmptyString
,
473 bitmap
, wxNullBitmap
, wxITEM_NORMAL
,
474 shortHelpString
, longHelpString
, NULL
);
477 wxToolBarToolBase
*AddTool(int toolid
,
478 const wxBitmap
& bitmap
,
479 const wxBitmap
& bmpDisabled
,
482 wxCoord yPos
= wxDefaultCoord
,
483 wxObject
*clientData
= NULL
,
484 const wxString
& shortHelp
= wxEmptyString
,
485 const wxString
& longHelp
= wxEmptyString
)
487 return DoAddTool(toolid
, wxEmptyString
, bitmap
, bmpDisabled
,
488 toggle
? wxITEM_CHECK
: wxITEM_NORMAL
,
489 shortHelp
, longHelp
, clientData
, xPos
, yPos
);
492 wxToolBarToolBase
*InsertTool(size_t pos
,
494 const wxBitmap
& bitmap
,
495 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
497 wxObject
*clientData
= NULL
,
498 const wxString
& shortHelp
= wxEmptyString
,
499 const wxString
& longHelp
= wxEmptyString
)
501 return InsertTool(pos
, toolid
, wxEmptyString
, bitmap
, bmpDisabled
,
502 toggle
? wxITEM_CHECK
: wxITEM_NORMAL
,
503 shortHelp
, longHelp
, clientData
);
509 // NB: these functions are deprecated, use EVT_TOOL_XXX() instead!
511 // Only allow toggle if returns true. Call when left button up.
512 virtual bool OnLeftClick(int toolid
, bool toggleDown
);
514 // Call when right button down.
515 virtual void OnRightClick(int toolid
, long x
, long y
);
517 // Called when the mouse cursor enters a tool bitmap.
518 // Argument is wxID_ANY if mouse is exiting the toolbar.
519 virtual void OnMouseEnter(int toolid
);
521 // more deprecated functions
522 // -------------------------
524 // use GetToolMargins() instead
525 wxSize
GetMargins() const { return GetToolMargins(); }
527 // implementation only from now on
528 // -------------------------------
530 size_t GetToolsCount() const { return m_tools
.GetCount(); }
532 // Do the toolbar button updates (check for EVT_UPDATE_UI handlers)
533 virtual void UpdateWindowUI(long flags
= wxUPDATE_UI_NONE
) ;
535 // don't want toolbars to accept the focus
536 virtual bool AcceptsFocus() const { return false; }
539 bool SetDropdownMenu(int toolid
, wxMenu
*menu
);
542 // to implement in derived classes
543 // -------------------------------
545 // create a new toolbar tool and add it to the toolbar, this is typically
546 // implemented by just calling InsertTool()
547 virtual wxToolBarToolBase
*DoAddTool
550 const wxString
& label
,
551 const wxBitmap
& bitmap
,
552 const wxBitmap
& bmpDisabled
,
554 const wxString
& shortHelp
= wxEmptyString
,
555 const wxString
& longHelp
= wxEmptyString
,
556 wxObject
*clientData
= NULL
,
557 wxCoord xPos
= wxDefaultCoord
,
558 wxCoord yPos
= wxDefaultCoord
561 // the tool is not yet inserted into m_tools list when this function is
562 // called and will only be added to it if this function succeeds
563 virtual bool DoInsertTool(size_t pos
, wxToolBarToolBase
*tool
) = 0;
565 // the tool is still in m_tools list when this function is called, it will
566 // only be deleted from it if it succeeds
567 virtual bool DoDeleteTool(size_t pos
, wxToolBarToolBase
*tool
) = 0;
569 // called when the tools enabled flag changes
570 virtual void DoEnableTool(wxToolBarToolBase
*tool
, bool enable
) = 0;
572 // called when the tool is toggled
573 virtual void DoToggleTool(wxToolBarToolBase
*tool
, bool toggle
) = 0;
575 // called when the tools "can be toggled" flag changes
576 virtual void DoSetToggle(wxToolBarToolBase
*tool
, bool toggle
) = 0;
578 // the functions to create toolbar tools
579 virtual wxToolBarToolBase
*CreateTool(int toolid
,
580 const wxString
& label
,
581 const wxBitmap
& bmpNormal
,
582 const wxBitmap
& bmpDisabled
,
584 wxObject
*clientData
,
585 const wxString
& shortHelp
,
586 const wxString
& longHelp
) = 0;
588 virtual wxToolBarToolBase
*CreateTool(wxControl
*control
,
589 const wxString
& label
) = 0;
594 // call this from derived class ctor/Create() to ensure that we have either
595 // wxTB_HORIZONTAL or wxTB_VERTICAL style, there is a lot of existing code
596 // which randomly checks either one or the other of them and gets confused
597 // if neither is set (and making one of them 0 is not an option neither as
598 // then the existing tests would break down)
601 // un-toggle all buttons in the same radio group
602 void UnToggleRadioGroup(wxToolBarToolBase
*tool
);
604 // the list of all our tools
605 wxToolBarToolsList m_tools
;
607 // the offset of the first tool
611 // the maximum number of toolbar rows/columns
615 // the tool packing and separation
619 // the size of the toolbar bitmaps
620 wxCoord m_defaultWidth
, m_defaultHeight
;
623 DECLARE_EVENT_TABLE()
624 DECLARE_NO_COPY_CLASS(wxToolBarBase
)
627 // deprecated function for creating the image for disabled buttons, use
628 // wxImage::ConvertToGreyscale() instead
629 #if WXWIN_COMPATIBILITY_2_8
631 wxDEPRECATED( bool wxCreateGreyedImage(const wxImage
& in
, wxImage
& out
) );
633 #endif // WXWIN_COMPATIBILITY_2_8
636 #endif // wxUSE_TOOLBAR