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 WXDLLEXPORT wxToolBarBase
;
28 class WXDLLEXPORT wxToolBarToolBase
;
29 class WXDLLEXPORT 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_clientData
= clientData
;
82 m_bmpNormal
= bmpNormal
;
83 m_bmpDisabled
= bmpDisabled
;
90 m_toolStyle
= toolid
== wxID_SEPARATOR
? wxTOOL_STYLE_SEPARATOR
91 : wxTOOL_STYLE_BUTTON
;
94 wxToolBarToolBase(wxToolBarBase
*tbar
,
96 const wxString
& label
)
101 m_id
= control
->GetId();
103 m_kind
= wxITEM_MAX
; // invalid value
108 m_toolStyle
= wxTOOL_STYLE_CONTROL
;
111 virtual ~wxToolBarToolBase(){}
117 int GetId() const { return m_id
; }
119 wxControl
*GetControl() const
121 wxASSERT_MSG( IsControl(), _T("this toolbar tool is not a control") );
126 wxToolBarBase
*GetToolBar() const { return m_tbar
; }
129 bool IsButton() const { return m_toolStyle
== wxTOOL_STYLE_BUTTON
; }
130 bool IsControl() const { return m_toolStyle
== wxTOOL_STYLE_CONTROL
; }
131 bool IsSeparator() const { return m_toolStyle
== wxTOOL_STYLE_SEPARATOR
; }
132 int GetStyle() const { return m_toolStyle
; }
133 wxItemKind
GetKind() const
135 wxASSERT_MSG( IsButton(), _T("only makes sense for buttons") );
141 bool IsEnabled() const { return m_enabled
; }
142 bool IsToggled() const { return m_toggled
; }
143 bool CanBeToggled() const
144 { return m_kind
== wxITEM_CHECK
|| m_kind
== wxITEM_RADIO
; }
147 const wxBitmap
& GetNormalBitmap() const { return m_bmpNormal
; }
148 const wxBitmap
& GetDisabledBitmap() const { return m_bmpDisabled
; }
150 const wxBitmap
& GetBitmap() const
151 { return IsEnabled() ? GetNormalBitmap() : GetDisabledBitmap(); }
153 const wxString
& GetLabel() const { return m_label
; }
155 const wxString
& GetShortHelp() const { return m_shortHelpString
; }
156 const wxString
& GetLongHelp() const { return m_longHelpString
; }
158 wxObject
*GetClientData() const
160 if ( m_toolStyle
== wxTOOL_STYLE_CONTROL
)
162 return (wxObject
*)m_control
->GetClientData();
170 // modifiers: return true if the state really changed
171 bool Enable(bool enable
);
172 bool Toggle(bool toggle
);
173 bool SetToggle(bool toggle
);
174 bool SetShortHelp(const wxString
& help
);
175 bool SetLongHelp(const wxString
& help
);
177 void Toggle() { Toggle(!IsToggled()); }
179 void SetNormalBitmap(const wxBitmap
& bmp
) { m_bmpNormal
= bmp
; }
180 void SetDisabledBitmap(const wxBitmap
& bmp
) { m_bmpDisabled
= bmp
; }
182 virtual void SetLabel(const wxString
& label
) { m_label
= label
; }
184 void SetClientData(wxObject
*clientData
)
186 if ( m_toolStyle
== wxTOOL_STYLE_CONTROL
)
188 m_control
->SetClientData(clientData
);
192 m_clientData
= clientData
;
196 // add tool to/remove it from a toolbar
197 virtual void Detach() { m_tbar
= (wxToolBarBase
*)NULL
; }
198 virtual void Attach(wxToolBarBase
*tbar
) { m_tbar
= tbar
; }
201 wxToolBarBase
*m_tbar
; // the toolbar to which we belong (may be NULL)
204 int m_toolStyle
; // see enum wxToolBarToolStyle
205 int m_id
; // the tool id, wxID_SEPARATOR for separator
206 wxItemKind m_kind
; // for normal buttons may be wxITEM_NORMAL/CHECK/RADIO
208 // as controls have their own client data, no need to waste memory
211 wxObject
*m_clientData
;
212 wxControl
*m_control
;
219 // normal and disabled bitmaps for the tool, both can be invalid
220 wxBitmap m_bmpNormal
;
221 wxBitmap m_bmpDisabled
;
226 // short and long help strings
227 wxString m_shortHelpString
;
228 wxString m_longHelpString
;
230 DECLARE_DYNAMIC_CLASS_NO_COPY(wxToolBarToolBase
)
233 // a list of toolbar tools
234 WX_DECLARE_EXPORTED_LIST(wxToolBarToolBase
, wxToolBarToolsList
);
236 // ----------------------------------------------------------------------------
237 // the base class for all toolbars
238 // ----------------------------------------------------------------------------
240 class WXDLLEXPORT wxToolBarBase
: public wxControl
244 virtual ~wxToolBarBase();
246 // toolbar construction
247 // --------------------
249 // the full AddTool() function
251 // If bmpDisabled is wxNullBitmap, a shadowed version of the normal bitmap
252 // is created and used as the disabled image.
253 wxToolBarToolBase
*AddTool(int toolid
,
254 const wxString
& label
,
255 const wxBitmap
& bitmap
,
256 const wxBitmap
& bmpDisabled
,
257 wxItemKind kind
= wxITEM_NORMAL
,
258 const wxString
& shortHelp
= wxEmptyString
,
259 const wxString
& longHelp
= wxEmptyString
,
260 wxObject
*data
= NULL
)
262 return DoAddTool(toolid
, label
, bitmap
, bmpDisabled
, kind
,
263 shortHelp
, longHelp
, data
);
266 // the most common AddTool() version
267 wxToolBarToolBase
*AddTool(int toolid
,
268 const wxString
& label
,
269 const wxBitmap
& bitmap
,
270 const wxString
& shortHelp
= wxEmptyString
,
271 wxItemKind kind
= wxITEM_NORMAL
)
273 return AddTool(toolid
, label
, bitmap
, wxNullBitmap
, kind
, shortHelp
);
276 // add a check tool, i.e. a tool which can be toggled
277 wxToolBarToolBase
*AddCheckTool(int toolid
,
278 const wxString
& label
,
279 const wxBitmap
& bitmap
,
280 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
281 const wxString
& shortHelp
= wxEmptyString
,
282 const wxString
& longHelp
= wxEmptyString
,
283 wxObject
*data
= NULL
)
285 return AddTool(toolid
, label
, bitmap
, bmpDisabled
, wxITEM_CHECK
,
286 shortHelp
, longHelp
, data
);
289 // add a radio tool, i.e. a tool which can be toggled and releases any
290 // other toggled radio tools in the same group when it happens
291 wxToolBarToolBase
*AddRadioTool(int toolid
,
292 const wxString
& label
,
293 const wxBitmap
& bitmap
,
294 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
295 const wxString
& shortHelp
= wxEmptyString
,
296 const wxString
& longHelp
= wxEmptyString
,
297 wxObject
*data
= NULL
)
299 return AddTool(toolid
, label
, bitmap
, bmpDisabled
, wxITEM_RADIO
,
300 shortHelp
, longHelp
, data
);
304 // insert the new tool at the given position, if pos == GetToolsCount(), it
305 // is equivalent to AddTool()
306 virtual wxToolBarToolBase
*InsertTool
310 const wxString
& label
,
311 const wxBitmap
& bitmap
,
312 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
313 wxItemKind kind
= wxITEM_NORMAL
,
314 const wxString
& shortHelp
= wxEmptyString
,
315 const wxString
& longHelp
= wxEmptyString
,
316 wxObject
*clientData
= NULL
319 virtual wxToolBarToolBase
*AddTool (wxToolBarToolBase
*tool
);
320 virtual wxToolBarToolBase
*InsertTool (size_t pos
, wxToolBarToolBase
*tool
);
322 // add an arbitrary control to the toolbar (notice that the control will be
323 // deleted by the toolbar and that it will also adjust its position/size)
325 // the label is optional and, if specified, will be shown near the control
326 // NB: the control should have toolbar as its parent
327 virtual wxToolBarToolBase
*
328 AddControl(wxControl
*control
, const wxString
& label
= wxEmptyString
);
330 virtual wxToolBarToolBase
*
331 InsertControl(size_t pos
, wxControl
*control
,
332 const wxString
& label
= wxEmptyString
);
334 // get the control with the given id or return NULL
335 virtual wxControl
*FindControl( int toolid
);
337 // add a separator to the toolbar
338 virtual wxToolBarToolBase
*AddSeparator();
339 virtual wxToolBarToolBase
*InsertSeparator(size_t pos
);
341 // remove the tool from the toolbar: the caller is responsible for actually
342 // deleting the pointer
343 virtual wxToolBarToolBase
*RemoveTool(int toolid
);
345 // delete tool either by index or by position
346 virtual bool DeleteToolByPos(size_t pos
);
347 virtual bool DeleteTool(int toolid
);
350 virtual void ClearTools();
352 // must be called after all buttons have been created to finish toolbar
354 virtual bool Realize();
359 virtual void EnableTool(int toolid
, bool enable
);
360 virtual void ToggleTool(int toolid
, bool toggle
);
362 // Set this to be togglable (or not)
363 virtual void SetToggle(int toolid
, bool toggle
);
365 // set/get tools client data (not for controls)
366 virtual wxObject
*GetToolClientData(int toolid
) const;
367 virtual void SetToolClientData(int toolid
, wxObject
*clientData
);
369 // returns tool pos, or wxNOT_FOUND if tool isn't found
370 virtual int GetToolPos(int id
) const;
372 // return true if the tool is toggled
373 virtual bool GetToolState(int toolid
) const;
375 virtual bool GetToolEnabled(int toolid
) const;
377 virtual void SetToolShortHelp(int toolid
, const wxString
& helpString
);
378 virtual wxString
GetToolShortHelp(int toolid
) const;
379 virtual void SetToolLongHelp(int toolid
, const wxString
& helpString
);
380 virtual wxString
GetToolLongHelp(int toolid
) const;
382 virtual void SetToolNormalBitmap(int WXUNUSED(id
),
383 const wxBitmap
& WXUNUSED(bitmap
)) {}
384 virtual void SetToolDisabledBitmap(int WXUNUSED(id
),
385 const wxBitmap
& WXUNUSED(bitmap
)) {}
388 // margins/packing/separation
389 // --------------------------
391 virtual void SetMargins(int x
, int y
);
392 void SetMargins(const wxSize
& size
)
393 { SetMargins((int) size
.x
, (int) size
.y
); }
394 virtual void SetToolPacking(int packing
)
395 { m_toolPacking
= packing
; }
396 virtual void SetToolSeparation(int separation
)
397 { m_toolSeparation
= separation
; }
399 virtual wxSize
GetToolMargins() const { return wxSize(m_xMargin
, m_yMargin
); }
400 virtual int GetToolPacking() const { return m_toolPacking
; }
401 virtual int GetToolSeparation() const { return m_toolSeparation
; }
406 // set the number of toolbar rows
407 virtual void SetRows(int nRows
);
409 // the toolbar can wrap - limit the number of columns or rows it may take
410 void SetMaxRowsCols(int rows
, int cols
)
411 { m_maxRows
= rows
; m_maxCols
= cols
; }
412 int GetMaxRows() const { return m_maxRows
; }
413 int GetMaxCols() const { return m_maxCols
; }
415 // get/set the size of the bitmaps used by the toolbar: should be called
416 // before adding any tools to the toolbar
417 virtual void SetToolBitmapSize(const wxSize
& size
)
418 { m_defaultWidth
= size
.x
; m_defaultHeight
= size
.y
; }
419 virtual wxSize
GetToolBitmapSize() const
420 { return wxSize(m_defaultWidth
, m_defaultHeight
); }
422 // the button size in some implementations is bigger than the bitmap size:
423 // get the total button size (by default the same as bitmap size)
424 virtual wxSize
GetToolSize() const
425 { return GetToolBitmapSize(); }
427 // returns a (non separator) tool containing the point (x, y) or NULL if
428 // there is no tool at this point (corrdinates are client)
429 virtual wxToolBarToolBase
*FindToolForPosition(wxCoord x
,
430 wxCoord y
) const = 0;
432 // find the tool by id
433 wxToolBarToolBase
*FindById(int toolid
) const;
435 // return true if this is a vertical toolbar, otherwise false
436 bool IsVertical() const { return HasFlag(wxTB_LEFT
| wxTB_RIGHT
); }
439 // the old versions of the various methods kept for compatibility
440 // don't use in the new code!
441 // --------------------------------------------------------------
443 wxToolBarToolBase
*AddTool(int toolid
,
444 const wxBitmap
& bitmap
,
445 const wxBitmap
& bmpDisabled
,
447 wxObject
*clientData
= NULL
,
448 const wxString
& shortHelpString
= wxEmptyString
,
449 const wxString
& longHelpString
= wxEmptyString
)
451 return AddTool(toolid
, wxEmptyString
,
453 toggle
? wxITEM_CHECK
: wxITEM_NORMAL
,
454 shortHelpString
, longHelpString
, clientData
);
457 wxToolBarToolBase
*AddTool(int toolid
,
458 const wxBitmap
& bitmap
,
459 const wxString
& shortHelpString
= wxEmptyString
,
460 const wxString
& longHelpString
= wxEmptyString
)
462 return AddTool(toolid
, wxEmptyString
,
463 bitmap
, wxNullBitmap
, wxITEM_NORMAL
,
464 shortHelpString
, longHelpString
, NULL
);
467 wxToolBarToolBase
*AddTool(int toolid
,
468 const wxBitmap
& bitmap
,
469 const wxBitmap
& bmpDisabled
,
472 wxCoord yPos
= wxDefaultCoord
,
473 wxObject
*clientData
= NULL
,
474 const wxString
& shortHelp
= wxEmptyString
,
475 const wxString
& longHelp
= wxEmptyString
)
477 return DoAddTool(toolid
, wxEmptyString
, bitmap
, bmpDisabled
,
478 toggle
? wxITEM_CHECK
: wxITEM_NORMAL
,
479 shortHelp
, longHelp
, clientData
, xPos
, yPos
);
482 wxToolBarToolBase
*InsertTool(size_t pos
,
484 const wxBitmap
& bitmap
,
485 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
487 wxObject
*clientData
= NULL
,
488 const wxString
& shortHelp
= wxEmptyString
,
489 const wxString
& longHelp
= wxEmptyString
)
491 return InsertTool(pos
, toolid
, wxEmptyString
, bitmap
, bmpDisabled
,
492 toggle
? wxITEM_CHECK
: wxITEM_NORMAL
,
493 shortHelp
, longHelp
, clientData
);
499 // NB: these functions are deprecated, use EVT_TOOL_XXX() instead!
501 // Only allow toggle if returns true. Call when left button up.
502 virtual bool OnLeftClick(int toolid
, bool toggleDown
);
504 // Call when right button down.
505 virtual void OnRightClick(int toolid
, long x
, long y
);
507 // Called when the mouse cursor enters a tool bitmap.
508 // Argument is wxID_ANY if mouse is exiting the toolbar.
509 virtual void OnMouseEnter(int toolid
);
511 // more deprecated functions
512 // -------------------------
514 // use GetToolMargins() instead
515 wxSize
GetMargins() const { return GetToolMargins(); }
517 // implementation only from now on
518 // -------------------------------
520 size_t GetToolsCount() const { return m_tools
.GetCount(); }
522 // Do the toolbar button updates (check for EVT_UPDATE_UI handlers)
523 virtual void UpdateWindowUI(long flags
= wxUPDATE_UI_NONE
) ;
525 // don't want toolbars to accept the focus
526 virtual bool AcceptsFocus() const { return false; }
529 // to implement in derived classes
530 // -------------------------------
532 // create a new toolbar tool and add it to the toolbar, this is typically
533 // implemented by just calling InsertTool()
534 virtual wxToolBarToolBase
*DoAddTool
537 const wxString
& label
,
538 const wxBitmap
& bitmap
,
539 const wxBitmap
& bmpDisabled
,
541 const wxString
& shortHelp
= wxEmptyString
,
542 const wxString
& longHelp
= wxEmptyString
,
543 wxObject
*clientData
= NULL
,
544 wxCoord xPos
= wxDefaultCoord
,
545 wxCoord yPos
= wxDefaultCoord
548 // the tool is not yet inserted into m_tools list when this function is
549 // called and will only be added to it if this function succeeds
550 virtual bool DoInsertTool(size_t pos
, wxToolBarToolBase
*tool
) = 0;
552 // the tool is still in m_tools list when this function is called, it will
553 // only be deleted from it if it succeeds
554 virtual bool DoDeleteTool(size_t pos
, wxToolBarToolBase
*tool
) = 0;
556 // called when the tools enabled flag changes
557 virtual void DoEnableTool(wxToolBarToolBase
*tool
, bool enable
) = 0;
559 // called when the tool is toggled
560 virtual void DoToggleTool(wxToolBarToolBase
*tool
, bool toggle
) = 0;
562 // called when the tools "can be toggled" flag changes
563 virtual void DoSetToggle(wxToolBarToolBase
*tool
, bool toggle
) = 0;
565 // the functions to create toolbar tools
566 virtual wxToolBarToolBase
*CreateTool(int toolid
,
567 const wxString
& label
,
568 const wxBitmap
& bmpNormal
,
569 const wxBitmap
& bmpDisabled
,
571 wxObject
*clientData
,
572 const wxString
& shortHelp
,
573 const wxString
& longHelp
) = 0;
575 virtual wxToolBarToolBase
*CreateTool(wxControl
*control
,
576 const wxString
& label
) = 0;
581 // call this from derived class ctor/Create() to ensure that we have either
582 // wxTB_HORIZONTAL or wxTB_VERTICAL style, there is a lot of existing code
583 // which randomly checks either one or the other of them and gets confused
584 // if neither is set (and making one of them 0 is not an option neither as
585 // then the existing tests would break down)
588 // un-toggle all buttons in the same radio group
589 void UnToggleRadioGroup(wxToolBarToolBase
*tool
);
591 // the list of all our tools
592 wxToolBarToolsList m_tools
;
594 // the offset of the first tool
598 // the maximum number of toolbar rows/columns
602 // the tool packing and separation
606 // the size of the toolbar bitmaps
607 wxCoord m_defaultWidth
, m_defaultHeight
;
610 DECLARE_EVENT_TABLE()
611 DECLARE_NO_COPY_CLASS(wxToolBarBase
)
614 // deprecated function for creating the image for disabled buttons, use
615 // wxImage::ConvertToGreyscale() instead
616 #if WXWIN_COMPATIBILITY_2_8
618 wxDEPRECATED( bool wxCreateGreyedImage(const wxImage
& in
, wxImage
& out
) );
620 #endif // WXWIN_COMPATIBILITY_2_8
623 #endif // wxUSE_TOOLBAR