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