]> git.saurik.com Git - wxWidgets.git/blob - include/wx/tbarbase.h
fix wxStringOutputStream::Write() in Unicode build when the output overlaps a boundar...
[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 WXDLLEXPORT wxToolBarBase;
28 class WXDLLEXPORT wxToolBarToolBase;
29 class WXDLLEXPORT wxImage;
30
31 // ----------------------------------------------------------------------------
32 // constants
33 // ----------------------------------------------------------------------------
34
35 extern WXDLLEXPORT_DATA(const wxChar) wxToolBarNameStr[];
36 extern WXDLLEXPORT_DATA(const wxSize) wxDefaultSize;
37 extern WXDLLEXPORT_DATA(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 WXDLLEXPORT wxToolBarToolBase : public wxObject
58 {
59 public:
60 // ctors & dtor
61 // ------------
62
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)
72 : m_label(label),
73 m_shortHelpString(shortHelpString),
74 m_longHelpString(longHelpString)
75 {
76 m_tbar = tbar;
77 m_id = toolid;
78 if (m_id == wxID_ANY)
79 m_id = wxNewId();
80 m_clientData = clientData;
81
82 m_bmpNormal = bmpNormal;
83 m_bmpDisabled = bmpDisabled;
84
85 m_kind = kind;
86
87 m_enabled = true;
88 m_toggled = false;
89
90 m_toolStyle = toolid == wxID_SEPARATOR ? wxTOOL_STYLE_SEPARATOR
91 : wxTOOL_STYLE_BUTTON;
92 }
93
94 wxToolBarToolBase(wxToolBarBase *tbar,
95 wxControl *control,
96 const wxString& label)
97 : m_label(label)
98 {
99 m_tbar = tbar;
100 m_control = control;
101 m_id = control->GetId();
102
103 m_kind = wxITEM_MAX; // invalid value
104
105 m_enabled = true;
106 m_toggled = false;
107
108 m_toolStyle = wxTOOL_STYLE_CONTROL;
109 }
110
111 virtual ~wxToolBarToolBase(){}
112
113 // accessors
114 // ---------
115
116 // general
117 int GetId() const { return m_id; }
118
119 wxControl *GetControl() const
120 {
121 wxASSERT_MSG( IsControl(), _T("this toolbar tool is not a control") );
122
123 return m_control;
124 }
125
126 wxToolBarBase *GetToolBar() const { return m_tbar; }
127
128 // style
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
134 {
135 wxASSERT_MSG( IsButton(), _T("only makes sense for buttons") );
136
137 return m_kind;
138 }
139
140 // state
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; }
145
146 // attributes
147 const wxBitmap& GetNormalBitmap() const { return m_bmpNormal; }
148 const wxBitmap& GetDisabledBitmap() const { return m_bmpDisabled; }
149
150 const wxBitmap& GetBitmap() const
151 { return IsEnabled() ? GetNormalBitmap() : GetDisabledBitmap(); }
152
153 const wxString& GetLabel() const { return m_label; }
154
155 const wxString& GetShortHelp() const { return m_shortHelpString; }
156 const wxString& GetLongHelp() const { return m_longHelpString; }
157
158 wxObject *GetClientData() const
159 {
160 if ( m_toolStyle == wxTOOL_STYLE_CONTROL )
161 {
162 return (wxObject*)m_control->GetClientData();
163 }
164 else
165 {
166 return m_clientData;
167 }
168 }
169
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);
176
177 void Toggle() { Toggle(!IsToggled()); }
178
179 void SetNormalBitmap(const wxBitmap& bmp) { m_bmpNormal = bmp; }
180 void SetDisabledBitmap(const wxBitmap& bmp) { m_bmpDisabled = bmp; }
181
182 virtual void SetLabel(const wxString& label) { m_label = label; }
183
184 void SetClientData(wxObject *clientData)
185 {
186 if ( m_toolStyle == wxTOOL_STYLE_CONTROL )
187 {
188 m_control->SetClientData(clientData);
189 }
190 else
191 {
192 m_clientData = clientData;
193 }
194 }
195
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; }
199
200 protected:
201 wxToolBarBase *m_tbar; // the toolbar to which we belong (may be NULL)
202
203 // tool parameters
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
207
208 // as controls have their own client data, no need to waste memory
209 union
210 {
211 wxObject *m_clientData;
212 wxControl *m_control;
213 };
214
215 // tool state
216 bool m_toggled;
217 bool m_enabled;
218
219 // normal and disabled bitmaps for the tool, both can be invalid
220 wxBitmap m_bmpNormal;
221 wxBitmap m_bmpDisabled;
222
223 // the button label
224 wxString m_label;
225
226 // short and long help strings
227 wxString m_shortHelpString;
228 wxString m_longHelpString;
229
230 DECLARE_DYNAMIC_CLASS_NO_COPY(wxToolBarToolBase)
231 };
232
233 // a list of toolbar tools
234 WX_DECLARE_EXPORTED_LIST(wxToolBarToolBase, wxToolBarToolsList);
235
236 // ----------------------------------------------------------------------------
237 // the base class for all toolbars
238 // ----------------------------------------------------------------------------
239
240 class WXDLLEXPORT wxToolBarBase : public wxControl
241 {
242 public:
243 wxToolBarBase();
244 virtual ~wxToolBarBase();
245
246 // toolbar construction
247 // --------------------
248
249 // the full AddTool() function
250 //
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)
261 {
262 return DoAddTool(toolid, label, bitmap, bmpDisabled, kind,
263 shortHelp, longHelp, data);
264 }
265
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)
272 {
273 return AddTool(toolid, label, bitmap, wxNullBitmap, kind, shortHelp);
274 }
275
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)
284 {
285 return AddTool(toolid, label, bitmap, bmpDisabled, wxITEM_CHECK,
286 shortHelp, longHelp, data);
287 }
288
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)
298 {
299 return AddTool(toolid, label, bitmap, bmpDisabled, wxITEM_RADIO,
300 shortHelp, longHelp, data);
301 }
302
303
304 // insert the new tool at the given position, if pos == GetToolsCount(), it
305 // is equivalent to AddTool()
306 virtual wxToolBarToolBase *InsertTool
307 (
308 size_t pos,
309 int toolid,
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
317 );
318
319 virtual wxToolBarToolBase *AddTool (wxToolBarToolBase *tool);
320 virtual wxToolBarToolBase *InsertTool (size_t pos, wxToolBarToolBase *tool);
321
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)
324 //
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);
329
330 virtual wxToolBarToolBase *
331 InsertControl(size_t pos, wxControl *control,
332 const wxString& label = wxEmptyString);
333
334 // get the control with the given id or return NULL
335 virtual wxControl *FindControl( int toolid );
336
337 // add a separator to the toolbar
338 virtual wxToolBarToolBase *AddSeparator();
339 virtual wxToolBarToolBase *InsertSeparator(size_t pos);
340
341 // remove the tool from the toolbar: the caller is responsible for actually
342 // deleting the pointer
343 virtual wxToolBarToolBase *RemoveTool(int toolid);
344
345 // delete tool either by index or by position
346 virtual bool DeleteToolByPos(size_t pos);
347 virtual bool DeleteTool(int toolid);
348
349 // delete all tools
350 virtual void ClearTools();
351
352 // must be called after all buttons have been created to finish toolbar
353 // initialisation
354 virtual bool Realize();
355
356 // tools state
357 // -----------
358
359 virtual void EnableTool(int toolid, bool enable);
360 virtual void ToggleTool(int toolid, bool toggle);
361
362 // Set this to be togglable (or not)
363 virtual void SetToggle(int toolid, bool toggle);
364
365 // set/get tools client data (not for controls)
366 virtual wxObject *GetToolClientData(int toolid) const;
367 virtual void SetToolClientData(int toolid, wxObject *clientData);
368
369 // returns tool pos, or wxNOT_FOUND if tool isn't found
370 virtual int GetToolPos(int id) const;
371
372 // return true if the tool is toggled
373 virtual bool GetToolState(int toolid) const;
374
375 virtual bool GetToolEnabled(int toolid) const;
376
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;
381
382 virtual void SetToolNormalBitmap(int WXUNUSED(id),
383 const wxBitmap& WXUNUSED(bitmap)) {}
384 virtual void SetToolDisabledBitmap(int WXUNUSED(id),
385 const wxBitmap& WXUNUSED(bitmap)) {}
386
387
388 // margins/packing/separation
389 // --------------------------
390
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; }
398
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; }
402
403 // toolbar geometry
404 // ----------------
405
406 // set the number of toolbar rows
407 virtual void SetRows(int nRows);
408
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; }
414
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); }
421
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(); }
426
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;
431
432 // find the tool by id
433 wxToolBarToolBase *FindById(int toolid) const;
434
435 // return true if this is a vertical toolbar, otherwise false
436 bool IsVertical() const { return HasFlag(wxTB_LEFT | wxTB_RIGHT); }
437
438
439 // the old versions of the various methods kept for compatibility
440 // don't use in the new code!
441 // --------------------------------------------------------------
442
443 wxToolBarToolBase *AddTool(int toolid,
444 const wxBitmap& bitmap,
445 const wxBitmap& bmpDisabled,
446 bool toggle = false,
447 wxObject *clientData = NULL,
448 const wxString& shortHelpString = wxEmptyString,
449 const wxString& longHelpString = wxEmptyString)
450 {
451 return AddTool(toolid, wxEmptyString,
452 bitmap, bmpDisabled,
453 toggle ? wxITEM_CHECK : wxITEM_NORMAL,
454 shortHelpString, longHelpString, clientData);
455 }
456
457 wxToolBarToolBase *AddTool(int toolid,
458 const wxBitmap& bitmap,
459 const wxString& shortHelpString = wxEmptyString,
460 const wxString& longHelpString = wxEmptyString)
461 {
462 return AddTool(toolid, wxEmptyString,
463 bitmap, wxNullBitmap, wxITEM_NORMAL,
464 shortHelpString, longHelpString, NULL);
465 }
466
467 wxToolBarToolBase *AddTool(int toolid,
468 const wxBitmap& bitmap,
469 const wxBitmap& bmpDisabled,
470 bool toggle,
471 wxCoord xPos,
472 wxCoord yPos = wxDefaultCoord,
473 wxObject *clientData = NULL,
474 const wxString& shortHelp = wxEmptyString,
475 const wxString& longHelp = wxEmptyString)
476 {
477 return DoAddTool(toolid, wxEmptyString, bitmap, bmpDisabled,
478 toggle ? wxITEM_CHECK : wxITEM_NORMAL,
479 shortHelp, longHelp, clientData, xPos, yPos);
480 }
481
482 wxToolBarToolBase *InsertTool(size_t pos,
483 int toolid,
484 const wxBitmap& bitmap,
485 const wxBitmap& bmpDisabled = wxNullBitmap,
486 bool toggle = false,
487 wxObject *clientData = NULL,
488 const wxString& shortHelp = wxEmptyString,
489 const wxString& longHelp = wxEmptyString)
490 {
491 return InsertTool(pos, toolid, wxEmptyString, bitmap, bmpDisabled,
492 toggle ? wxITEM_CHECK : wxITEM_NORMAL,
493 shortHelp, longHelp, clientData);
494 }
495
496 // event handlers
497 // --------------
498
499 // NB: these functions are deprecated, use EVT_TOOL_XXX() instead!
500
501 // Only allow toggle if returns true. Call when left button up.
502 virtual bool OnLeftClick(int toolid, bool toggleDown);
503
504 // Call when right button down.
505 virtual void OnRightClick(int toolid, long x, long y);
506
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);
510
511 // more deprecated functions
512 // -------------------------
513
514 // use GetToolMargins() instead
515 wxSize GetMargins() const { return GetToolMargins(); }
516
517 // implementation only from now on
518 // -------------------------------
519
520 size_t GetToolsCount() const { return m_tools.GetCount(); }
521
522 // Do the toolbar button updates (check for EVT_UPDATE_UI handlers)
523 virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE) ;
524
525 // don't want toolbars to accept the focus
526 virtual bool AcceptsFocus() const { return false; }
527
528 protected:
529 // to implement in derived classes
530 // -------------------------------
531
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
535 (
536 int toolid,
537 const wxString& label,
538 const wxBitmap& bitmap,
539 const wxBitmap& bmpDisabled,
540 wxItemKind kind,
541 const wxString& shortHelp = wxEmptyString,
542 const wxString& longHelp = wxEmptyString,
543 wxObject *clientData = NULL,
544 wxCoord xPos = wxDefaultCoord,
545 wxCoord yPos = wxDefaultCoord
546 );
547
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;
551
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;
555
556 // called when the tools enabled flag changes
557 virtual void DoEnableTool(wxToolBarToolBase *tool, bool enable) = 0;
558
559 // called when the tool is toggled
560 virtual void DoToggleTool(wxToolBarToolBase *tool, bool toggle) = 0;
561
562 // called when the tools "can be toggled" flag changes
563 virtual void DoSetToggle(wxToolBarToolBase *tool, bool toggle) = 0;
564
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,
570 wxItemKind kind,
571 wxObject *clientData,
572 const wxString& shortHelp,
573 const wxString& longHelp) = 0;
574
575 virtual wxToolBarToolBase *CreateTool(wxControl *control,
576 const wxString& label) = 0;
577
578 // helper functions
579 // ----------------
580
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)
586 void FixupStyle();
587
588 // un-toggle all buttons in the same radio group
589 void UnToggleRadioGroup(wxToolBarToolBase *tool);
590
591 // the list of all our tools
592 wxToolBarToolsList m_tools;
593
594 // the offset of the first tool
595 int m_xMargin;
596 int m_yMargin;
597
598 // the maximum number of toolbar rows/columns
599 int m_maxRows;
600 int m_maxCols;
601
602 // the tool packing and separation
603 int m_toolPacking,
604 m_toolSeparation;
605
606 // the size of the toolbar bitmaps
607 wxCoord m_defaultWidth, m_defaultHeight;
608
609 private:
610 DECLARE_EVENT_TABLE()
611 DECLARE_NO_COPY_CLASS(wxToolBarBase)
612 };
613
614 // deprecated function for creating the image for disabled buttons, use
615 // wxImage::ConvertToGreyscale() instead
616 #if WXWIN_COMPATIBILITY_2_8
617
618 wxDEPRECATED( bool wxCreateGreyedImage(const wxImage& in, wxImage& out) );
619
620 #endif // WXWIN_COMPATIBILITY_2_8
621
622
623 #endif // wxUSE_TOOLBAR
624
625 #endif
626 // _WX_TBARBASE_H_
627