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, wxControl *control)
  95     {
  96         m_tbar = tbar;
  97         m_control = control;
  98         m_id = control->GetId();
  99
 100         m_kind = wxITEM_MAX;    // invalid value
 101
 102         m_enabled = true;
 103         m_toggled = false;
 104
 105         m_toolStyle = wxTOOL_STYLE_CONTROL;
 106     }
 107
 108     virtual ~wxToolBarToolBase(){}
 109
 110     // accessors
 111     // ---------
 112
 113     // general
 114     int GetId() const { return m_id; }
 115
 116     wxControl *GetControl() const
 117     {
 118         wxASSERT_MSG( IsControl(), _T("this toolbar tool is not a control") );
 119
 120         return m_control;
 121     }
 122
 123     wxToolBarBase *GetToolBar() const { return m_tbar; }
 124
 125     // style
 126     bool IsButton() const { return m_toolStyle == wxTOOL_STYLE_BUTTON; }
 127     bool IsControl() const { return m_toolStyle == wxTOOL_STYLE_CONTROL; }
 128     bool IsSeparator() const { return m_toolStyle == wxTOOL_STYLE_SEPARATOR; }
 129     int GetStyle() const { return m_toolStyle; }
 130     wxItemKind GetKind() const
 131     {
 132         wxASSERT_MSG( IsButton(), _T("only makes sense for buttons") );
 133
 134         return m_kind;
 135     }
 136
 137     // state
 138     bool IsEnabled() const { return m_enabled; }
 139     bool IsToggled() const { return m_toggled; }
 140     bool CanBeToggled() const
 141         { return m_kind == wxITEM_CHECK || m_kind == wxITEM_RADIO; }
 142
 143     // attributes
 144     const wxBitmap& GetNormalBitmap() const { return m_bmpNormal; }
 145     const wxBitmap& GetDisabledBitmap() const { return m_bmpDisabled; }
 146
 147     const wxBitmap& GetBitmap() const
 148         { return IsEnabled() ? GetNormalBitmap() : GetDisabledBitmap(); }
 149
 150     const wxString& GetLabel() const { return m_label; }
 151
 152     const wxString& GetShortHelp() const { return m_shortHelpString; }
 153     const wxString& GetLongHelp() const { return m_longHelpString; }
 154
 155     wxObject *GetClientData() const
 156     {
 157         if ( m_toolStyle == wxTOOL_STYLE_CONTROL )
 158         {
 159             return (wxObject*)m_control->GetClientData();
 160         }
 161         else
 162         {
 163             return m_clientData;
 164         }
 165     }
 166
 167     // modifiers: return true if the state really changed
 168     bool Enable(bool enable);
 169     bool Toggle(bool toggle);
 170     bool SetToggle(bool toggle);
 171     bool SetShortHelp(const wxString& help);
 172     bool SetLongHelp(const wxString& help);
 173
 174     void Toggle() { Toggle(!IsToggled()); }
 175
 176     void SetNormalBitmap(const wxBitmap& bmp) { m_bmpNormal = bmp; }
 177     void SetDisabledBitmap(const wxBitmap& bmp) { m_bmpDisabled = bmp; }
 178
 179     virtual void SetLabel(const wxString& label) { m_label = label; }
 180
 181     void SetClientData(wxObject *clientData)
 182     {
 183         if ( m_toolStyle == wxTOOL_STYLE_CONTROL )
 184         {
 185             m_control->SetClientData(clientData);
 186         }
 187         else
 188         {
 189             m_clientData = clientData;
 190         }
 191     }
 192
 193     // add tool to/remove it from a toolbar
 194     virtual void Detach() { m_tbar = (wxToolBarBase *)NULL; }
 195     virtual void Attach(wxToolBarBase *tbar) { m_tbar = tbar; }
 196
 197 protected:
 198     wxToolBarBase *m_tbar;  // the toolbar to which we belong (may be NULL)
 199
 200     // tool parameters
 201     int m_toolStyle;    // see enum wxToolBarToolStyle
 202     int m_id;           // the tool id, wxID_SEPARATOR for separator
 203     wxItemKind m_kind;  // for normal buttons may be wxITEM_NORMAL/CHECK/RADIO
 204
 205     // as controls have their own client data, no need to waste memory
 206     union
 207     {
 208         wxObject         *m_clientData;
 209         wxControl        *m_control;
 210     };
 211
 212     // tool state
 213     bool m_toggled;
 214     bool m_enabled;
 215
 216     // normal and disabled bitmaps for the tool, both can be invalid
 217     wxBitmap m_bmpNormal;
 218     wxBitmap m_bmpDisabled;
 219
 220     // the button label
 221     wxString m_label;
 222
 223     // short and long help strings
 224     wxString m_shortHelpString;
 225     wxString m_longHelpString;
 226
 227     DECLARE_DYNAMIC_CLASS_NO_COPY(wxToolBarToolBase)
 228 };
 229
 230 // a list of toolbar tools
 231 WX_DECLARE_EXPORTED_LIST(wxToolBarToolBase, wxToolBarToolsList);
 232
 233 // ----------------------------------------------------------------------------
 234 // the base class for all toolbars
 235 // ----------------------------------------------------------------------------
 236
 237 class WXDLLEXPORT wxToolBarBase : public wxControl
 238 {
 239 public:
 240     wxToolBarBase();
 241     virtual ~wxToolBarBase();
 242
 243     // toolbar construction
 244     // --------------------
 245
 246     // the full AddTool() function
 247     //
 248     // If bmpDisabled is wxNullBitmap, a shadowed version of the normal bitmap
 249     // is created and used as the disabled image.
 250     wxToolBarToolBase *AddTool(int toolid,
 251                                const wxString& label,
 252                                const wxBitmap& bitmap,
 253                                const wxBitmap& bmpDisabled,
 254                                wxItemKind kind = wxITEM_NORMAL,
 255                                const wxString& shortHelp = wxEmptyString,
 256                                const wxString& longHelp = wxEmptyString,
 257                                wxObject *data = NULL)
 258     {
 259         return DoAddTool(toolid, label, bitmap, bmpDisabled, kind,
 260                          shortHelp, longHelp, data);
 261     }
 262
 263     // the most common AddTool() version
 264     wxToolBarToolBase *AddTool(int toolid,
 265                                const wxString& label,
 266                                const wxBitmap& bitmap,
 267                                const wxString& shortHelp = wxEmptyString,
 268                                wxItemKind kind = wxITEM_NORMAL)
 269     {
 270         return AddTool(toolid, label, bitmap, wxNullBitmap, kind, shortHelp);
 271     }
 272
 273     // add a check tool, i.e. a tool which can be toggled
 274     wxToolBarToolBase *AddCheckTool(int toolid,
 275                                     const wxString& label,
 276                                     const wxBitmap& bitmap,
 277                                     const wxBitmap& bmpDisabled = wxNullBitmap,
 278                                     const wxString& shortHelp = wxEmptyString,
 279                                     const wxString& longHelp = wxEmptyString,
 280                                     wxObject *data = NULL)
 281     {
 282         return AddTool(toolid, label, bitmap, bmpDisabled, wxITEM_CHECK,
 283                        shortHelp, longHelp, data);
 284     }
 285
 286     // add a radio tool, i.e. a tool which can be toggled and releases any
 287     // other toggled radio tools in the same group when it happens
 288     wxToolBarToolBase *AddRadioTool(int toolid,
 289                                     const wxString& label,
 290                                     const wxBitmap& bitmap,
 291                                     const wxBitmap& bmpDisabled = wxNullBitmap,
 292                                     const wxString& shortHelp = wxEmptyString,
 293                                     const wxString& longHelp = wxEmptyString,
 294                                     wxObject *data = NULL)
 295     {
 296         return AddTool(toolid, label, bitmap, bmpDisabled, wxITEM_RADIO,
 297                        shortHelp, longHelp, data);
 298     }
 299
 300
 301     // insert the new tool at the given position, if pos == GetToolsCount(), it
 302     // is equivalent to AddTool()
 303     virtual wxToolBarToolBase *InsertTool
 304                                (
 305                                     size_t pos,
 306                                     int toolid,
 307                                     const wxString& label,
 308                                     const wxBitmap& bitmap,
 309                                     const wxBitmap& bmpDisabled = wxNullBitmap,
 310                                     wxItemKind kind = wxITEM_NORMAL,
 311                                     const wxString& shortHelp = wxEmptyString,
 312                                     const wxString& longHelp = wxEmptyString,
 313                                     wxObject *clientData = NULL
 314                                );
 315
 316     virtual wxToolBarToolBase *AddTool (wxToolBarToolBase *tool);
 317     virtual wxToolBarToolBase *InsertTool (size_t pos, wxToolBarToolBase *tool);
 318
 319     // add an arbitrary control to the toolbar (notice that
 320     // the control will be deleted by the toolbar and that it will also adjust
 321     // its position/size)
 322     //
 323     // NB: the control should have toolbar as its parent
 324     virtual wxToolBarToolBase *AddControl(wxControl *control);
 325     virtual wxToolBarToolBase *InsertControl(size_t pos, wxControl *control);
 326
 327     // get the control with the given id or return NULL
 328     virtual wxControl *FindControl( int toolid );
 329
 330     // add a separator to the toolbar
 331     virtual wxToolBarToolBase *AddSeparator();
 332     virtual wxToolBarToolBase *InsertSeparator(size_t pos);
 333
 334     // remove the tool from the toolbar: the caller is responsible for actually
 335     // deleting the pointer
 336     virtual wxToolBarToolBase *RemoveTool(int toolid);
 337
 338     // delete tool either by index or by position
 339     virtual bool DeleteToolByPos(size_t pos);
 340     virtual bool DeleteTool(int toolid);
 341
 342     // delete all tools
 343     virtual void ClearTools();
 344
 345     // must be called after all buttons have been created to finish toolbar
 346     // initialisation
 347     virtual bool Realize();
 348
 349     // tools state
 350     // -----------
 351
 352     virtual void EnableTool(int toolid, bool enable);
 353     virtual void ToggleTool(int toolid, bool toggle);
 354
 355     // Set this to be togglable (or not)
 356     virtual void SetToggle(int toolid, bool toggle);
 357
 358     // set/get tools client data (not for controls)
 359     virtual wxObject *GetToolClientData(int toolid) const;
 360     virtual void SetToolClientData(int toolid, wxObject *clientData);
 361
 362     // returns tool pos, or wxNOT_FOUND if tool isn't found
 363     virtual int GetToolPos(int id) const;
 364
 365     // return true if the tool is toggled
 366     virtual bool GetToolState(int toolid) const;
 367
 368     virtual bool GetToolEnabled(int toolid) const;
 369
 370     virtual void SetToolShortHelp(int toolid, const wxString& helpString);
 371     virtual wxString GetToolShortHelp(int toolid) const;
 372     virtual void SetToolLongHelp(int toolid, const wxString& helpString);
 373     virtual wxString GetToolLongHelp(int toolid) const;
 374
 375     virtual void SetToolNormalBitmap(int WXUNUSED(id),
 376                                      const wxBitmap& WXUNUSED(bitmap)) {}
 377     virtual void SetToolDisabledBitmap(int WXUNUSED(id),
 378                                        const wxBitmap& WXUNUSED(bitmap)) {}
 379
 380
 381     // margins/packing/separation
 382     // --------------------------
 383
 384     virtual void SetMargins(int x, int y);
 385     void SetMargins(const wxSize& size)
 386         { SetMargins((int) size.x, (int) size.y); }
 387     virtual void SetToolPacking(int packing)
 388         { m_toolPacking = packing; }
 389     virtual void SetToolSeparation(int separation)
 390         { m_toolSeparation = separation; }
 391
 392     virtual wxSize GetToolMargins() const { return wxSize(m_xMargin, m_yMargin); }
 393     virtual int GetToolPacking() const { return m_toolPacking; }
 394     virtual int GetToolSeparation() const { return m_toolSeparation; }
 395
 396     // toolbar geometry
 397     // ----------------
 398
 399     // set the number of toolbar rows
 400     virtual void SetRows(int nRows);
 401
 402     // the toolbar can wrap - limit the number of columns or rows it may take
 403     void SetMaxRowsCols(int rows, int cols)
 404         { m_maxRows = rows; m_maxCols = cols; }
 405     int GetMaxRows() const { return m_maxRows; }
 406     int GetMaxCols() const { return m_maxCols; }
 407
 408     // get/set the size of the bitmaps used by the toolbar: should be called
 409     // before adding any tools to the toolbar
 410     virtual void SetToolBitmapSize(const wxSize& size)
 411         { m_defaultWidth = size.x; m_defaultHeight = size.y; };
 412     virtual wxSize GetToolBitmapSize() const
 413         { return wxSize(m_defaultWidth, m_defaultHeight); }
 414
 415     // the button size in some implementations is bigger than the bitmap size:
 416     // get the total button size (by default the same as bitmap size)
 417     virtual wxSize GetToolSize() const
 418         { return GetToolBitmapSize(); } ;
 419
 420     // returns a (non separator) tool containing the point (x, y) or NULL if
 421     // there is no tool at this point (corrdinates are client)
 422     virtual wxToolBarToolBase *FindToolForPosition(wxCoord x,
 423                                                    wxCoord y) const = 0;
 424
 425     // find the tool by id
 426     wxToolBarToolBase *FindById(int toolid) const;
 427
 428     // return true if this is a vertical toolbar, otherwise false
 429     bool IsVertical() const { return HasFlag(wxTB_LEFT | wxTB_RIGHT); }
 430
 431
 432     // the old versions of the various methods kept for compatibility
 433     // don't use in the new code!
 434     // --------------------------------------------------------------
 435
 436     wxToolBarToolBase *AddTool(int toolid,
 437                                const wxBitmap& bitmap,
 438                                const wxBitmap& bmpDisabled,
 439                                bool toggle = false,
 440                                wxObject *clientData = NULL,
 441                                const wxString& shortHelpString = wxEmptyString,
 442                                const wxString& longHelpString = wxEmptyString)
 443     {
 444         return AddTool(toolid, wxEmptyString,
 445                        bitmap, bmpDisabled,
 446                        toggle ? wxITEM_CHECK : wxITEM_NORMAL,
 447                        shortHelpString, longHelpString, clientData);
 448     }
 449
 450     wxToolBarToolBase *AddTool(int toolid,
 451                                const wxBitmap& bitmap,
 452                                const wxString& shortHelpString = wxEmptyString,
 453                                const wxString& longHelpString = wxEmptyString)
 454     {
 455         return AddTool(toolid, wxEmptyString,
 456                        bitmap, wxNullBitmap, wxITEM_NORMAL,
 457                        shortHelpString, longHelpString, NULL);
 458     }
 459
 460     wxToolBarToolBase *AddTool(int toolid,
 461                                const wxBitmap& bitmap,
 462                                const wxBitmap& bmpDisabled,
 463                                bool toggle,
 464                                wxCoord xPos,
 465                                wxCoord yPos = wxDefaultCoord,
 466                                wxObject *clientData = NULL,
 467                                const wxString& shortHelp = wxEmptyString,
 468                                const wxString& longHelp = wxEmptyString)
 469     {
 470         return DoAddTool(toolid, wxEmptyString, bitmap, bmpDisabled,
 471                          toggle ? wxITEM_CHECK : wxITEM_NORMAL,
 472                          shortHelp, longHelp, clientData, xPos, yPos);
 473     }
 474
 475     wxToolBarToolBase *InsertTool(size_t pos,
 476                                   int toolid,
 477                                   const wxBitmap& bitmap,
 478                                   const wxBitmap& bmpDisabled = wxNullBitmap,
 479                                   bool toggle = false,
 480                                   wxObject *clientData = NULL,
 481                                   const wxString& shortHelp = wxEmptyString,
 482                                   const wxString& longHelp = wxEmptyString)
 483     {
 484         return InsertTool(pos, toolid, wxEmptyString, bitmap, bmpDisabled,
 485                           toggle ? wxITEM_CHECK : wxITEM_NORMAL,
 486                           shortHelp, longHelp, clientData);
 487     }
 488
 489     // event handlers
 490     // --------------
 491
 492     // NB: these functions are deprecated, use EVT_TOOL_XXX() instead!
 493
 494     // Only allow toggle if returns true. Call when left button up.
 495     virtual bool OnLeftClick(int toolid, bool toggleDown);
 496
 497     // Call when right button down.
 498     virtual void OnRightClick(int toolid, long x, long y);
 499
 500     // Called when the mouse cursor enters a tool bitmap.
 501     // Argument is wxID_ANY if mouse is exiting the toolbar.
 502     virtual void OnMouseEnter(int toolid);
 503
 504     // more deprecated functions
 505     // -------------------------
 506
 507     // use GetToolMargins() instead
 508     wxSize GetMargins() const { return GetToolMargins(); }
 509
 510     // implementation only from now on
 511     // -------------------------------
 512
 513     size_t GetToolsCount() const { return m_tools.GetCount(); }
 514
 515     // Do the toolbar button updates (check for EVT_UPDATE_UI handlers)
 516     virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE) ;
 517
 518     // don't want toolbars to accept the focus
 519     virtual bool AcceptsFocus() const { return false; }
 520
 521 protected:
 522     // to implement in derived classes
 523     // -------------------------------
 524
 525     // create a new toolbar tool and add it to the toolbar, this is typically
 526     // implemented by just calling InsertTool()
 527     virtual wxToolBarToolBase *DoAddTool
 528                                (
 529                                    int toolid,
 530                                    const wxString& label,
 531                                    const wxBitmap& bitmap,
 532                                    const wxBitmap& bmpDisabled,
 533                                    wxItemKind kind,
 534                                    const wxString& shortHelp = wxEmptyString,
 535                                    const wxString& longHelp = wxEmptyString,
 536                                    wxObject *clientData = NULL,
 537                                    wxCoord xPos = wxDefaultCoord,
 538                                    wxCoord yPos = wxDefaultCoord
 539                                );
 540
 541     // the tool is not yet inserted into m_tools list when this function is
 542     // called and will only be added to it if this function succeeds
 543     virtual bool DoInsertTool(size_t pos, wxToolBarToolBase *tool) = 0;
 544
 545     // the tool is still in m_tools list when this function is called, it will
 546     // only be deleted from it if it succeeds
 547     virtual bool DoDeleteTool(size_t pos, wxToolBarToolBase *tool) = 0;
 548
 549     // called when the tools enabled flag changes
 550     virtual void DoEnableTool(wxToolBarToolBase *tool, bool enable) = 0;
 551
 552     // called when the tool is toggled
 553     virtual void DoToggleTool(wxToolBarToolBase *tool, bool toggle) = 0;
 554
 555     // called when the tools "can be toggled" flag changes
 556     virtual void DoSetToggle(wxToolBarToolBase *tool, bool toggle) = 0;
 557
 558     // the functions to create toolbar tools
 559     virtual wxToolBarToolBase *CreateTool(int toolid,
 560                                           const wxString& label,
 561                                           const wxBitmap& bmpNormal,
 562                                           const wxBitmap& bmpDisabled,
 563                                           wxItemKind kind,
 564                                           wxObject *clientData,
 565                                           const wxString& shortHelp,
 566                                           const wxString& longHelp) = 0;
 567
 568     virtual wxToolBarToolBase *CreateTool(wxControl *control) = 0;
 569
 570     // helper functions
 571     // ----------------
 572
 573     // call this from derived class ctor/Create() to ensure that we have either
 574     // wxTB_HORIZONTAL or wxTB_VERTICAL style, there is a lot of existing code
 575     // which randomly checks either one or the other of them and gets confused
 576     // if neither is set (and making one of them 0 is not an option neither as
 577     // then the existing tests would break down)
 578     void FixupStyle();
 579
 580     // un-toggle all buttons in the same radio group
 581     void UnToggleRadioGroup(wxToolBarToolBase *tool);
 582
 583     // the list of all our tools
 584     wxToolBarToolsList m_tools;
 585
 586     // the offset of the first tool
 587     int m_xMargin;
 588     int m_yMargin;
 589
 590     // the maximum number of toolbar rows/columns
 591     int m_maxRows;
 592     int m_maxCols;
 593
 594     // the tool packing and separation
 595     int m_toolPacking,
 596         m_toolSeparation;
 597
 598     // the size of the toolbar bitmaps
 599     wxCoord m_defaultWidth, m_defaultHeight;
 600
 601 private:
 602     DECLARE_EVENT_TABLE()
 603     DECLARE_NO_COPY_CLASS(wxToolBarBase)
 604 };
 605
 606 // deprecated function for creating the image for disabled buttons, use
 607 // wxImage::ConvertToGreyscale() instead
 608 #if WXWIN_COMPATIBILITY_2_8
 609
 610 wxDEPRECATED( bool wxCreateGreyedImage(const wxImage& in, wxImage& out) );
 611
 612 #endif // WXWIN_COMPATIBILITY_2_8
 613
 614
 615 #endif // wxUSE_TOOLBAR
 616
 617 #endif
 618     // _WX_TBARBASE_H_
 619