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 WXDLLIMPEXP_DATA_CORE(const char) wxToolBarNameStr
[];
36 extern WXDLLIMPEXP_DATA_CORE(const wxSize
) wxDefaultSize
;
37 extern WXDLLIMPEXP_DATA_CORE(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 WXDLLIMPEXP_CORE wxToolBarToolBase
: public wxObject
63 wxToolBarToolBase(wxToolBarBase
*tbar
= 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
= 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 virtual bool Enable(bool enable
);
175 virtual bool Toggle(bool toggle
);
176 virtual bool SetToggle(bool toggle
);
177 virtual bool SetShortHelp(const wxString
& help
);
178 virtual bool SetLongHelp(const wxString
& help
);
180 void Toggle() { Toggle(!IsToggled()); }
182 virtual void SetNormalBitmap(const wxBitmap
& bmp
) { m_bmpNormal
= bmp
; }
183 virtual 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
= 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 virtual 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 wxWindowIDRef 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 WXDLLIMPEXP_CORE 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
365 // derived class versions should call the base one first, before doing
366 // platform-specific stuff
367 virtual bool Realize();
372 virtual void EnableTool(int toolid
, bool enable
);
373 virtual void ToggleTool(int toolid
, bool toggle
);
375 // Set this to be togglable (or not)
376 virtual void SetToggle(int toolid
, bool toggle
);
378 // set/get tools client data (not for controls)
379 virtual wxObject
*GetToolClientData(int toolid
) const;
380 virtual void SetToolClientData(int toolid
, wxObject
*clientData
);
382 // returns tool pos, or wxNOT_FOUND if tool isn't found
383 virtual int GetToolPos(int id
) const;
385 // return true if the tool is toggled
386 virtual bool GetToolState(int toolid
) const;
388 virtual bool GetToolEnabled(int toolid
) const;
390 virtual void SetToolShortHelp(int toolid
, const wxString
& helpString
);
391 virtual wxString
GetToolShortHelp(int toolid
) const;
392 virtual void SetToolLongHelp(int toolid
, const wxString
& helpString
);
393 virtual wxString
GetToolLongHelp(int toolid
) const;
395 virtual void SetToolNormalBitmap(int WXUNUSED(id
),
396 const wxBitmap
& WXUNUSED(bitmap
)) {}
397 virtual void SetToolDisabledBitmap(int WXUNUSED(id
),
398 const wxBitmap
& WXUNUSED(bitmap
)) {}
401 // margins/packing/separation
402 // --------------------------
404 virtual void SetMargins(int x
, int y
);
405 void SetMargins(const wxSize
& size
)
406 { SetMargins((int) size
.x
, (int) size
.y
); }
407 virtual void SetToolPacking(int packing
)
408 { m_toolPacking
= packing
; }
409 virtual void SetToolSeparation(int separation
)
410 { m_toolSeparation
= separation
; }
412 virtual wxSize
GetToolMargins() const { return wxSize(m_xMargin
, m_yMargin
); }
413 virtual int GetToolPacking() const { return m_toolPacking
; }
414 virtual int GetToolSeparation() const { return m_toolSeparation
; }
419 // set the number of toolbar rows
420 virtual void SetRows(int nRows
);
422 // the toolbar can wrap - limit the number of columns or rows it may take
423 void SetMaxRowsCols(int rows
, int cols
)
424 { m_maxRows
= rows
; m_maxCols
= cols
; }
425 int GetMaxRows() const { return m_maxRows
; }
426 int GetMaxCols() const { return m_maxCols
; }
428 // get/set the size of the bitmaps used by the toolbar: should be called
429 // before adding any tools to the toolbar
430 virtual void SetToolBitmapSize(const wxSize
& size
)
431 { m_defaultWidth
= size
.x
; m_defaultHeight
= size
.y
; }
432 virtual wxSize
GetToolBitmapSize() const
433 { return wxSize(m_defaultWidth
, m_defaultHeight
); }
435 // the button size in some implementations is bigger than the bitmap size:
436 // get the total button size (by default the same as bitmap size)
437 virtual wxSize
GetToolSize() const
438 { return GetToolBitmapSize(); }
440 // returns a (non separator) tool containing the point (x, y) or NULL if
441 // there is no tool at this point (corrdinates are client)
442 virtual wxToolBarToolBase
*FindToolForPosition(wxCoord x
,
443 wxCoord y
) const = 0;
445 // find the tool by id
446 wxToolBarToolBase
*FindById(int toolid
) const;
448 // return true if this is a vertical toolbar, otherwise false
449 bool IsVertical() const;
451 #if WXWIN_COMPATIBILITY_2_8
452 // the old versions of the various methods kept for compatibility
453 // don't use in the new code!
454 // --------------------------------------------------------------
456 wxToolBarToolBase
*AddTool(int toolid
,
457 const wxBitmap
& bitmap
,
458 const wxBitmap
& bmpDisabled
,
460 wxObject
*clientData
= NULL
,
461 const wxString
& shortHelpString
= wxEmptyString
,
462 const wxString
& longHelpString
= wxEmptyString
)
464 return AddTool(toolid
, wxEmptyString
,
466 toggle
? wxITEM_CHECK
: wxITEM_NORMAL
,
467 shortHelpString
, longHelpString
, clientData
);
470 wxToolBarToolBase
*AddTool(int toolid
,
471 const wxBitmap
& bitmap
,
472 const wxString
& shortHelpString
= wxEmptyString
,
473 const wxString
& longHelpString
= wxEmptyString
)
475 return AddTool(toolid
, wxEmptyString
,
476 bitmap
, wxNullBitmap
, wxITEM_NORMAL
,
477 shortHelpString
, longHelpString
, NULL
);
480 wxToolBarToolBase
*AddTool(int toolid
,
481 const wxBitmap
& bitmap
,
482 const wxBitmap
& bmpDisabled
,
485 wxCoord yPos
= wxDefaultCoord
,
486 wxObject
*clientData
= NULL
,
487 const wxString
& shortHelp
= wxEmptyString
,
488 const wxString
& longHelp
= wxEmptyString
)
490 return DoAddTool(toolid
, wxEmptyString
, bitmap
, bmpDisabled
,
491 toggle
? wxITEM_CHECK
: wxITEM_NORMAL
,
492 shortHelp
, longHelp
, clientData
, xPos
, yPos
);
495 wxToolBarToolBase
*InsertTool(size_t pos
,
497 const wxBitmap
& bitmap
,
498 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
500 wxObject
*clientData
= NULL
,
501 const wxString
& shortHelp
= wxEmptyString
,
502 const wxString
& longHelp
= wxEmptyString
)
504 return InsertTool(pos
, toolid
, wxEmptyString
, bitmap
, bmpDisabled
,
505 toggle
? wxITEM_CHECK
: wxITEM_NORMAL
,
506 shortHelp
, longHelp
, clientData
);
508 #endif // WXWIN_COMPATIBILITY_2_8
513 // NB: these functions are deprecated, use EVT_TOOL_XXX() instead!
515 // Only allow toggle if returns true. Call when left button up.
516 virtual bool OnLeftClick(int toolid
, bool toggleDown
);
518 // Call when right button down.
519 virtual void OnRightClick(int toolid
, long x
, long y
);
521 // Called when the mouse cursor enters a tool bitmap.
522 // Argument is wxID_ANY if mouse is exiting the toolbar.
523 virtual void OnMouseEnter(int toolid
);
525 // more deprecated functions
526 // -------------------------
528 // use GetToolMargins() instead
529 wxSize
GetMargins() const { return GetToolMargins(); }
531 // implementation only from now on
532 // -------------------------------
534 size_t GetToolsCount() const { return m_tools
.GetCount(); }
536 // Do the toolbar button updates (check for EVT_UPDATE_UI handlers)
537 virtual void UpdateWindowUI(long flags
= wxUPDATE_UI_NONE
) ;
539 // don't want toolbars to accept the focus
540 virtual bool AcceptsFocus() const { return false; }
543 bool SetDropdownMenu(int toolid
, wxMenu
*menu
);
546 // to implement in derived classes
547 // -------------------------------
549 // create a new toolbar tool and add it to the toolbar, this is typically
550 // implemented by just calling InsertTool()
551 virtual wxToolBarToolBase
*DoAddTool
554 const wxString
& label
,
555 const wxBitmap
& bitmap
,
556 const wxBitmap
& bmpDisabled
,
558 const wxString
& shortHelp
= wxEmptyString
,
559 const wxString
& longHelp
= wxEmptyString
,
560 wxObject
*clientData
= NULL
,
561 wxCoord xPos
= wxDefaultCoord
,
562 wxCoord yPos
= wxDefaultCoord
565 // the tool is not yet inserted into m_tools list when this function is
566 // called and will only be added to it if this function succeeds
567 virtual bool DoInsertTool(size_t pos
, wxToolBarToolBase
*tool
) = 0;
569 // the tool is still in m_tools list when this function is called, it will
570 // only be deleted from it if it succeeds
571 virtual bool DoDeleteTool(size_t pos
, wxToolBarToolBase
*tool
) = 0;
573 // called when the tools enabled flag changes
574 virtual void DoEnableTool(wxToolBarToolBase
*tool
, bool enable
) = 0;
576 // called when the tool is toggled
577 virtual void DoToggleTool(wxToolBarToolBase
*tool
, bool toggle
) = 0;
579 // called when the tools "can be toggled" flag changes
580 virtual void DoSetToggle(wxToolBarToolBase
*tool
, bool toggle
) = 0;
582 // the functions to create toolbar tools
583 virtual wxToolBarToolBase
*CreateTool(int toolid
,
584 const wxString
& label
,
585 const wxBitmap
& bmpNormal
,
586 const wxBitmap
& bmpDisabled
,
588 wxObject
*clientData
,
589 const wxString
& shortHelp
,
590 const wxString
& longHelp
) = 0;
592 virtual wxToolBarToolBase
*CreateTool(wxControl
*control
,
593 const wxString
& label
) = 0;
598 // call this from derived class ctor/Create() to ensure that we have either
599 // wxTB_HORIZONTAL or wxTB_VERTICAL style, there is a lot of existing code
600 // which randomly checks either one or the other of them and gets confused
601 // if neither is set (and making one of them 0 is not an option neither as
602 // then the existing tests would break down)
605 // un-toggle all buttons in the same radio group
606 void UnToggleRadioGroup(wxToolBarToolBase
*tool
);
608 // make the size of the buttons big enough to fit the largest bitmap size
609 void AdjustToolBitmapSize();
612 // the list of all our tools
613 wxToolBarToolsList m_tools
;
615 // the offset of the first tool
619 // the maximum number of toolbar rows/columns
623 // the tool packing and separation
627 // the size of the toolbar bitmaps
628 wxCoord m_defaultWidth
, m_defaultHeight
;
631 DECLARE_EVENT_TABLE()
632 wxDECLARE_NO_COPY_CLASS(wxToolBarBase
);
635 // deprecated function for creating the image for disabled buttons, use
636 // wxImage::ConvertToGreyscale() instead
637 #if WXWIN_COMPATIBILITY_2_8
639 wxDEPRECATED( bool wxCreateGreyedImage(const wxImage
& in
, wxImage
& out
) );
641 #endif // WXWIN_COMPATIBILITY_2_8
644 #endif // wxUSE_TOOLBAR