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 // 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
)
74 m_shortHelpString(shortHelpString
),
75 m_longHelpString(longHelpString
)
80 toolid
== wxID_SEPARATOR
? wxTOOL_STYLE_SEPARATOR
81 : wxTOOL_STYLE_BUTTON
,
82 toolid
== wxID_ANY
? wxWindow::NewControlId()
87 m_clientData
= clientData
;
89 m_bmpNormal
= bmpNormal
;
90 m_bmpDisabled
= bmpDisabled
;
93 // ctor for controls only
94 wxToolBarToolBase(wxToolBarBase
*tbar
,
96 const wxString
& label
)
99 Init(tbar
, wxTOOL_STYLE_CONTROL
, control
->GetId(), wxITEM_MAX
);
104 m_toolStyle
= wxTOOL_STYLE_CONTROL
;
109 virtual ~wxToolBarToolBase();
115 int GetId() const { return m_id
; }
117 wxControl
*GetControl() const
119 wxASSERT_MSG( IsControl(), wxT("this toolbar tool is not a control") );
124 wxToolBarBase
*GetToolBar() const { return m_tbar
; }
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
133 wxASSERT_MSG( IsButton(), wxT("only makes sense for buttons") );
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
; }
145 const wxBitmap
& GetNormalBitmap() const { return m_bmpNormal
; }
146 const wxBitmap
& GetDisabledBitmap() const { return m_bmpDisabled
; }
148 const wxBitmap
& GetBitmap() const
149 { return IsEnabled() ? GetNormalBitmap() : GetDisabledBitmap(); }
151 const wxString
& GetLabel() const { return m_label
; }
153 const wxString
& GetShortHelp() const { return m_shortHelpString
; }
154 const wxString
& GetLongHelp() const { return m_longHelpString
; }
156 wxObject
*GetClientData() const
158 if ( m_toolStyle
== wxTOOL_STYLE_CONTROL
)
160 return (wxObject
*)m_control
->GetClientData();
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
);
175 void Toggle() { Toggle(!IsToggled()); }
177 virtual void SetNormalBitmap(const wxBitmap
& bmp
) { m_bmpNormal
= bmp
; }
178 virtual void SetDisabledBitmap(const wxBitmap
& bmp
) { m_bmpDisabled
= bmp
; }
180 virtual void SetLabel(const wxString
& label
) { m_label
= label
; }
182 void SetClientData(wxObject
*clientData
)
184 if ( m_toolStyle
== wxTOOL_STYLE_CONTROL
)
186 m_control
->SetClientData(clientData
);
190 m_clientData
= clientData
;
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
; }
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
; }
204 // common part of all ctors
205 void Init(wxToolBarBase
*tbar
,
206 wxToolBarToolStyle style
,
220 m_dropdownMenu
= NULL
;
223 wxToolBarBase
*m_tbar
; // the toolbar to which we belong (may be NULL)
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
230 // as controls have their own client data, no need to waste memory
233 wxObject
*m_clientData
;
234 wxControl
*m_control
;
241 // normal and disabled bitmaps for the tool, both can be invalid
242 wxBitmap m_bmpNormal
;
243 wxBitmap m_bmpDisabled
;
248 // short and long help strings
249 wxString m_shortHelpString
;
250 wxString m_longHelpString
;
252 wxMenu
*m_dropdownMenu
;
254 DECLARE_DYNAMIC_CLASS_NO_COPY(wxToolBarToolBase
)
257 // a list of toolbar tools
258 WX_DECLARE_EXPORTED_LIST(wxToolBarToolBase
, wxToolBarToolsList
);
260 // ----------------------------------------------------------------------------
261 // the base class for all toolbars
262 // ----------------------------------------------------------------------------
264 class WXDLLIMPEXP_CORE wxToolBarBase
: public wxControl
268 virtual ~wxToolBarBase();
270 // toolbar construction
271 // --------------------
273 // the full AddTool() function
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
)
286 return DoAddTool(toolid
, label
, bitmap
, bmpDisabled
, kind
,
287 shortHelp
, longHelp
, data
);
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
)
297 return AddTool(toolid
, label
, bitmap
, wxNullBitmap
, kind
, shortHelp
);
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
)
309 return AddTool(toolid
, label
, bitmap
, bmpDisabled
, wxITEM_CHECK
,
310 shortHelp
, longHelp
, data
);
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
)
323 return AddTool(toolid
, label
, bitmap
, bmpDisabled
, wxITEM_RADIO
,
324 shortHelp
, longHelp
, data
);
328 // insert the new tool at the given position, if pos == GetToolsCount(), it
329 // is equivalent to AddTool()
330 virtual wxToolBarToolBase
*InsertTool
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
343 virtual wxToolBarToolBase
*AddTool (wxToolBarToolBase
*tool
);
344 virtual wxToolBarToolBase
*InsertTool (size_t pos
, wxToolBarToolBase
*tool
);
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)
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
);
354 virtual wxToolBarToolBase
*
355 InsertControl(size_t pos
, wxControl
*control
,
356 const wxString
& label
= wxEmptyString
);
358 // get the control with the given id or return NULL
359 virtual wxControl
*FindControl( int toolid
);
361 // add a separator to the toolbar
362 virtual wxToolBarToolBase
*AddSeparator();
363 virtual wxToolBarToolBase
*InsertSeparator(size_t pos
);
365 // remove the tool from the toolbar: the caller is responsible for actually
366 // deleting the pointer
367 virtual wxToolBarToolBase
*RemoveTool(int toolid
);
369 // delete tool either by index or by position
370 virtual bool DeleteToolByPos(size_t pos
);
371 virtual bool DeleteTool(int toolid
);
374 virtual void ClearTools();
376 // must be called after all buttons have been created to finish toolbar
379 // derived class versions should call the base one first, before doing
380 // platform-specific stuff
381 virtual bool Realize();
386 virtual void EnableTool(int toolid
, bool enable
);
387 virtual void ToggleTool(int toolid
, bool toggle
);
389 // Set this to be togglable (or not)
390 virtual void SetToggle(int toolid
, bool toggle
);
392 // set/get tools client data (not for controls)
393 virtual wxObject
*GetToolClientData(int toolid
) const;
394 virtual void SetToolClientData(int toolid
, wxObject
*clientData
);
396 // returns tool pos, or wxNOT_FOUND if tool isn't found
397 virtual int GetToolPos(int id
) const;
399 // return true if the tool is toggled
400 virtual bool GetToolState(int toolid
) const;
402 virtual bool GetToolEnabled(int toolid
) const;
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;
409 virtual void SetToolNormalBitmap(int WXUNUSED(id
),
410 const wxBitmap
& WXUNUSED(bitmap
)) {}
411 virtual void SetToolDisabledBitmap(int WXUNUSED(id
),
412 const wxBitmap
& WXUNUSED(bitmap
)) {}
415 // margins/packing/separation
416 // --------------------------
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
; }
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
; }
433 // set the number of toolbar rows
434 virtual void SetRows(int nRows
);
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
; }
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
); }
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(); }
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;
459 // find the tool by id
460 wxToolBarToolBase
*FindById(int toolid
) const;
462 // return true if this is a vertical toolbar, otherwise false
463 bool IsVertical() const;
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 // --------------------------------------------------------------
470 wxToolBarToolBase
*AddTool(int toolid
,
471 const wxBitmap
& bitmap
,
472 const wxBitmap
& bmpDisabled
,
474 wxObject
*clientData
= NULL
,
475 const wxString
& shortHelpString
= wxEmptyString
,
476 const wxString
& longHelpString
= wxEmptyString
)
478 return AddTool(toolid
, wxEmptyString
,
480 toggle
? wxITEM_CHECK
: wxITEM_NORMAL
,
481 shortHelpString
, longHelpString
, clientData
);
484 wxToolBarToolBase
*AddTool(int toolid
,
485 const wxBitmap
& bitmap
,
486 const wxString
& shortHelpString
= wxEmptyString
,
487 const wxString
& longHelpString
= wxEmptyString
)
489 return AddTool(toolid
, wxEmptyString
,
490 bitmap
, wxNullBitmap
, wxITEM_NORMAL
,
491 shortHelpString
, longHelpString
, NULL
);
494 wxToolBarToolBase
*AddTool(int toolid
,
495 const wxBitmap
& bitmap
,
496 const wxBitmap
& bmpDisabled
,
499 wxCoord yPos
= wxDefaultCoord
,
500 wxObject
*clientData
= NULL
,
501 const wxString
& shortHelp
= wxEmptyString
,
502 const wxString
& longHelp
= wxEmptyString
)
504 return DoAddTool(toolid
, wxEmptyString
, bitmap
, bmpDisabled
,
505 toggle
? wxITEM_CHECK
: wxITEM_NORMAL
,
506 shortHelp
, longHelp
, clientData
, xPos
, yPos
);
509 wxToolBarToolBase
*InsertTool(size_t pos
,
511 const wxBitmap
& bitmap
,
512 const wxBitmap
& bmpDisabled
= wxNullBitmap
,
514 wxObject
*clientData
= NULL
,
515 const wxString
& shortHelp
= wxEmptyString
,
516 const wxString
& longHelp
= wxEmptyString
)
518 return InsertTool(pos
, toolid
, wxEmptyString
, bitmap
, bmpDisabled
,
519 toggle
? wxITEM_CHECK
: wxITEM_NORMAL
,
520 shortHelp
, longHelp
, clientData
);
522 #endif // WXWIN_COMPATIBILITY_2_8
527 // NB: these functions are deprecated, use EVT_TOOL_XXX() instead!
529 // Only allow toggle if returns true. Call when left button up.
530 virtual bool OnLeftClick(int toolid
, bool toggleDown
);
532 // Call when right button down.
533 virtual void OnRightClick(int toolid
, long x
, long y
);
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
);
539 // more deprecated functions
540 // -------------------------
542 // use GetToolMargins() instead
543 wxSize
GetMargins() const { return GetToolMargins(); }
545 // implementation only from now on
546 // -------------------------------
548 size_t GetToolsCount() const { return m_tools
.GetCount(); }
550 // Do the toolbar button updates (check for EVT_UPDATE_UI handlers)
551 virtual void UpdateWindowUI(long flags
= wxUPDATE_UI_NONE
) ;
553 // don't want toolbars to accept the focus
554 virtual bool AcceptsFocus() const { return false; }
557 bool SetDropdownMenu(int toolid
, wxMenu
*menu
);
560 // to implement in derived classes
561 // -------------------------------
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
568 const wxString
& label
,
569 const wxBitmap
& bitmap
,
570 const wxBitmap
& bmpDisabled
,
572 const wxString
& shortHelp
= wxEmptyString
,
573 const wxString
& longHelp
= wxEmptyString
,
574 wxObject
*clientData
= NULL
,
575 wxCoord xPos
= wxDefaultCoord
,
576 wxCoord yPos
= wxDefaultCoord
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;
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;
587 // called when the tools enabled flag changes
588 virtual void DoEnableTool(wxToolBarToolBase
*tool
, bool enable
) = 0;
590 // called when the tool is toggled
591 virtual void DoToggleTool(wxToolBarToolBase
*tool
, bool toggle
) = 0;
593 // called when the tools "can be toggled" flag changes
594 virtual void DoSetToggle(wxToolBarToolBase
*tool
, bool toggle
) = 0;
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
,
602 wxObject
*clientData
,
603 const wxString
& shortHelp
,
604 const wxString
& longHelp
) = 0;
606 virtual wxToolBarToolBase
*CreateTool(wxControl
*control
,
607 const wxString
& label
) = 0;
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)
619 // un-toggle all buttons in the same radio group
620 void UnToggleRadioGroup(wxToolBarToolBase
*tool
);
622 // make the size of the buttons big enough to fit the largest bitmap size
623 void AdjustToolBitmapSize();
625 // calls InsertTool() and deletes the tool if inserting it failed
626 wxToolBarToolBase
*DoInsertNewTool(size_t pos
, wxToolBarToolBase
*tool
)
628 if ( !InsertTool(pos
, tool
) )
637 // the list of all our tools
638 wxToolBarToolsList m_tools
;
640 // the offset of the first tool
644 // the maximum number of toolbar rows/columns
648 // the tool packing and separation
652 // the size of the toolbar bitmaps
653 wxCoord m_defaultWidth
, m_defaultHeight
;
656 DECLARE_EVENT_TABLE()
657 wxDECLARE_NO_COPY_CLASS(wxToolBarBase
);
660 // deprecated function for creating the image for disabled buttons, use
661 // wxImage::ConvertToGreyscale() instead
662 #if WXWIN_COMPATIBILITY_2_8
664 wxDEPRECATED( bool wxCreateGreyedImage(const wxImage
& in
, wxImage
& out
) );
666 #endif // WXWIN_COMPATIBILITY_2_8
669 #endif // wxUSE_TOOLBAR