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 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
  20     #pragma interface "tbarbase.h"
  21 #endif
  22
  23 #include "wx/defs.h"
  24
  25 #if wxUSE_TOOLBAR
  26
  27 #include "wx/bitmap.h"
  28 #include "wx/list.h"
  29 #include "wx/control.h"
  30
  31 class WXDLLEXPORT wxToolBarBase;
  32 class WXDLLEXPORT wxToolBarToolBase;
  33 class WXDLLEXPORT wxImage;
  34
  35 // ----------------------------------------------------------------------------
  36 // constants
  37 // ----------------------------------------------------------------------------
  38
  39 extern WXDLLEXPORT_DATA(const wxChar*) wxToolBarNameStr;
  40 extern WXDLLEXPORT_DATA(const wxSize) wxDefaultSize;
  41 extern WXDLLEXPORT_DATA(const wxPoint) wxDefaultPosition;
  42
  43 enum wxToolBarToolStyle
  44 {
  45     wxTOOL_STYLE_BUTTON    = 1,
  46     wxTOOL_STYLE_SEPARATOR = 2,
  47     wxTOOL_STYLE_CONTROL
  48 };
  49
  50 // ----------------------------------------------------------------------------
  51 // wxToolBarTool is a toolbar element.
  52 //
  53 // It has a unique id (except for the separators which always have id wxID_ANY), the
  54 // style (telling whether it is a normal button, separator or a control), the
  55 // state (toggled or not, enabled or not) and short and long help strings. The
  56 // default implementations use the short help string for the tooltip text which
  57 // is popped up when the mouse pointer enters the tool and the long help string
  58 // for the applications status bar.
  59 // ----------------------------------------------------------------------------
  60
  61 class WXDLLEXPORT wxToolBarToolBase : public wxObject
  62 {
  63 public:
  64     // ctors & dtor
  65     // ------------
  66
  67     wxToolBarToolBase(wxToolBarBase *tbar = (wxToolBarBase *)NULL,
  68                       int toolid = wxID_SEPARATOR,
  69                       const wxString& label = wxEmptyString,
  70                       const wxBitmap& bmpNormal = wxNullBitmap,
  71                       const wxBitmap& bmpDisabled = wxNullBitmap,
  72                       wxItemKind kind = wxITEM_NORMAL,
  73                       wxObject *clientData = (wxObject *) NULL,
  74                       const wxString& shortHelpString = wxEmptyString,
  75                       const wxString& longHelpString = wxEmptyString)
  76         : m_label(label),
  77           m_shortHelpString(shortHelpString),
  78           m_longHelpString(longHelpString)
  79     {
  80         m_tbar = tbar;
  81         m_id = toolid;
  82         if (m_id == wxID_ANY)
  83             m_id = wxNewId();
  84         m_clientData = clientData;
  85
  86         m_bmpNormal = bmpNormal;
  87         m_bmpDisabled = bmpDisabled;
  88
  89         m_kind = kind;
  90
  91         m_enabled = true;
  92         m_toggled = false;
  93
  94         m_toolStyle = toolid == wxID_SEPARATOR ? wxTOOL_STYLE_SEPARATOR
  95                                            : wxTOOL_STYLE_BUTTON;
  96     }
  97
  98     wxToolBarToolBase(wxToolBarBase *tbar, wxControl *control)
  99     {
 100         m_tbar = tbar;
 101         m_control = control;
 102         m_id = control->GetId();
 103
 104         m_kind = wxITEM_MAX;    // invalid value
 105
 106         m_enabled = true;
 107         m_toggled = false;
 108
 109         m_toolStyle = wxTOOL_STYLE_CONTROL;
 110     }
 111
 112     ~wxToolBarToolBase(){}
 113
 114     // accessors
 115     // ---------
 116
 117     // general
 118     int GetId() const { return m_id; }
 119
 120     wxControl *GetControl() const
 121     {
 122         wxASSERT_MSG( IsControl(), _T("this toolbar tool is not a control") );
 123
 124         return m_control;
 125     }
 126
 127     wxToolBarBase *GetToolBar() const { return m_tbar; }
 128
 129     // style
 130     bool IsButton() const { return m_toolStyle == wxTOOL_STYLE_BUTTON; }
 131     bool IsControl() const { return m_toolStyle == wxTOOL_STYLE_CONTROL; }
 132     bool IsSeparator() const { return m_toolStyle == wxTOOL_STYLE_SEPARATOR; }
 133     int GetStyle() const { return m_toolStyle; }
 134     wxItemKind GetKind() const
 135     {
 136         wxASSERT_MSG( IsButton(), _T("only makes sense for buttons") );
 137
 138         return m_kind;
 139     }
 140
 141     // state
 142     bool IsEnabled() const { return m_enabled; }
 143     bool IsToggled() const { return m_toggled; }
 144     bool CanBeToggled() const
 145         { return m_kind == wxITEM_CHECK || m_kind == wxITEM_RADIO; }
 146
 147     // attributes
 148     const wxBitmap& GetNormalBitmap() const { return m_bmpNormal; }
 149     const wxBitmap& GetDisabledBitmap() const { return m_bmpDisabled; }
 150
 151     const wxBitmap& GetBitmap() const
 152         { return IsEnabled() ? GetNormalBitmap() : GetDisabledBitmap(); }
 153
 154     wxString GetLabel() const { return m_label; }
 155
 156     wxString GetShortHelp() const { return m_shortHelpString; }
 157     wxString GetLongHelp() const { return m_longHelpString; }
 158
 159     wxObject *GetClientData() const
 160     {
 161         if ( m_toolStyle == wxTOOL_STYLE_CONTROL )
 162         {
 163             return (wxObject*)m_control->GetClientData();
 164         }
 165         else
 166         {
 167             return m_clientData;
 168         }
 169     }
 170
 171     // modifiers: return true if the state really changed
 172     bool Enable(bool enable);
 173     bool Toggle(bool toggle);
 174     bool SetToggle(bool toggle);
 175     bool SetShortHelp(const wxString& help);
 176     bool SetLongHelp(const wxString& help);
 177
 178     void Toggle() { Toggle(!IsToggled()); }
 179
 180     void SetNormalBitmap(const wxBitmap& bmp) { m_bmpNormal = bmp; }
 181     void SetDisabledBitmap(const wxBitmap& bmp) { m_bmpDisabled = bmp; }
 182
 183     virtual void SetLabel(const wxString& label) { m_label = label; }
 184
 185     void SetClientData(wxObject *clientData)
 186     {
 187         if ( m_toolStyle == wxTOOL_STYLE_CONTROL )
 188         {
 189             m_control->SetClientData(clientData);
 190         }
 191         else
 192         {
 193             m_clientData = clientData;
 194         }
 195     }
 196
 197     // add tool to/remove it from a toolbar
 198     virtual void Detach() { m_tbar = (wxToolBarBase *)NULL; }
 199     virtual void Attach(wxToolBarBase *tbar) { m_tbar = tbar; }
 200
 201     // compatibility only, don't use
 202 #if WXWIN_COMPATIBILITY_2_2
 203     wxDEPRECATED( const wxBitmap& GetBitmap1() const );
 204     wxDEPRECATED( const wxBitmap& GetBitmap2() const );
 205
 206     wxDEPRECATED( void SetBitmap1(const wxBitmap& bmp) );
 207     wxDEPRECATED( void SetBitmap2(const wxBitmap& bmp) );
 208 #endif // WXWIN_COMPATIBILITY_2_2
 209
 210 protected:
 211     wxToolBarBase *m_tbar;  // the toolbar to which we belong (may be NULL)
 212
 213     // tool parameters
 214     int m_toolStyle;    // see enum wxToolBarToolStyle
 215     int m_id;           // the tool id, wxID_SEPARATOR for separator
 216     wxItemKind m_kind;  // for normal buttons may be wxITEM_NORMAL/CHECK/RADIO
 217
 218     // as controls have their own client data, no need to waste memory
 219     union
 220     {
 221         wxObject         *m_clientData;
 222         wxControl        *m_control;
 223     };
 224
 225     // tool state
 226     bool m_toggled;
 227     bool m_enabled;
 228
 229     // normal and disabled bitmaps for the tool, both can be invalid
 230     wxBitmap m_bmpNormal;
 231     wxBitmap m_bmpDisabled;
 232
 233     // the button label
 234     wxString m_label;
 235
 236     // short and long help strings
 237     wxString m_shortHelpString;
 238     wxString m_longHelpString;
 239
 240     DECLARE_DYNAMIC_CLASS_NO_COPY(wxToolBarToolBase)
 241 };
 242
 243 // a list of toolbar tools
 244 WX_DECLARE_EXPORTED_LIST(wxToolBarToolBase, wxToolBarToolsList);
 245
 246 // ----------------------------------------------------------------------------
 247 // the base class for all toolbars
 248 // ----------------------------------------------------------------------------
 249
 250 class WXDLLEXPORT wxToolBarBase : public wxControl
 251 {
 252 public:
 253     wxToolBarBase();
 254     virtual ~wxToolBarBase();
 255
 256     // toolbar construction
 257     // --------------------
 258
 259     // the full AddTool() function
 260     //
 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)
 271     {
 272         return DoAddTool(toolid, label, bitmap, bmpDisabled, kind,
 273                          shortHelp, longHelp, data);
 274     }
 275
 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)
 282     {
 283         return AddTool(toolid, label, bitmap, wxNullBitmap, kind, shortHelp);
 284     }
 285
 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)
 294     {
 295         return AddTool(toolid, label, bitmap, bmpDisabled, wxITEM_CHECK,
 296                        shortHelp, longHelp, data);
 297     }
 298
 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)
 308     {
 309         return AddTool(toolid, label, bitmap, bmpDisabled, wxITEM_RADIO,
 310                        shortHelp, longHelp, data);
 311     }
 312
 313
 314     // insert the new tool at the given position, if pos == GetToolsCount(), it
 315     // is equivalent to AddTool()
 316     virtual wxToolBarToolBase *InsertTool
 317                                (
 318                                     size_t pos,
 319                                     int toolid,
 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
 327                                );
 328
 329     virtual wxToolBarToolBase *AddTool (wxToolBarToolBase *tool);
 330     virtual wxToolBarToolBase *InsertTool (size_t pos, wxToolBarToolBase *tool);
 331
 332     // add an arbitrary control to the toolbar (notice that
 333     // the control will be deleted by the toolbar and that it will also adjust
 334     // its position/size)
 335     //
 336     // NB: the control should have toolbar as its parent
 337     virtual wxToolBarToolBase *AddControl(wxControl *control);
 338     virtual wxToolBarToolBase *InsertControl(size_t pos, wxControl *control);
 339
 340     // get the control with the given id or return NULL
 341     virtual wxControl *FindControl( int toolid );
 342
 343     // add a separator to the toolbar
 344     virtual wxToolBarToolBase *AddSeparator();
 345     virtual wxToolBarToolBase *InsertSeparator(size_t pos);
 346
 347     // remove the tool from the toolbar: the caller is responsible for actually
 348     // deleting the pointer
 349     virtual wxToolBarToolBase *RemoveTool(int toolid);
 350
 351     // delete tool either by index or by position
 352     virtual bool DeleteToolByPos(size_t pos);
 353     virtual bool DeleteTool(int toolid);
 354
 355     // delete all tools
 356     virtual void ClearTools();
 357
 358     // must be called after all buttons have been created to finish toolbar
 359     // initialisation
 360     virtual bool Realize();
 361
 362     // tools state
 363     // -----------
 364
 365     virtual void EnableTool(int toolid, bool enable);
 366     virtual void ToggleTool(int toolid, bool toggle);
 367
 368     // Set this to be togglable (or not)
 369     virtual void SetToggle(int toolid, bool toggle);
 370
 371     // set/get tools client data (not for controls)
 372     virtual wxObject *GetToolClientData(int toolid) const;
 373     virtual void SetToolClientData(int toolid, wxObject *clientData);
 374
 375     // returns tool pos, or wxNOT_FOUND if tool isn't found
 376     virtual int GetToolPos(int id) const;
 377
 378     // return true if the tool is toggled
 379     virtual bool GetToolState(int toolid) const;
 380
 381     virtual bool GetToolEnabled(int toolid) const;
 382
 383     virtual void SetToolShortHelp(int toolid, const wxString& helpString);
 384     virtual wxString GetToolShortHelp(int toolid) const;
 385     virtual void SetToolLongHelp(int toolid, const wxString& helpString);
 386     virtual wxString GetToolLongHelp(int toolid) const;
 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_VERTICAL); }
 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) = 0;
 576
 577     // helper functions
 578     // ----------------
 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 // Helper function for creating the image for disabled buttons
 607 bool wxCreateGreyedImage(const wxImage& in, wxImage& out) ;
 608
 609 #endif // wxUSE_TOOLBAR
 610
 611 #endif
 612     // _WX_TBARBASE_H_
 613