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 #ifdef __GNUG__
  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 wxBitmap& bitmap1 = wxNullBitmap,
  70                       const wxBitmap& bitmap2 = wxNullBitmap,
  71                       bool toggle = FALSE,
  72                       wxObject *clientData = (wxObject *) NULL,
  73                       const wxString& shortHelpString = wxEmptyString,
  74                       const wxString& longHelpString = wxEmptyString)
  75         : m_shortHelpString(shortHelpString),
  76           m_longHelpString(longHelpString)
  77     {
  78         m_tbar = tbar;
  79         m_id = id;
  80         m_clientData = clientData;
  81
  82         m_bitmap1 = bitmap1;
  83         m_bitmap2 = bitmap2;
  84
  85         m_isToggle = toggle;
  86         m_enabled = TRUE;
  87         m_toggled = FALSE;
  88
  89         m_toolStyle = id == wxID_SEPARATOR ? wxTOOL_STYLE_SEPARATOR
  90                                            : wxTOOL_STYLE_BUTTON;
  91     }
  92
  93     wxToolBarToolBase(wxToolBarBase *tbar, wxControl *control)
  94     {
  95         m_tbar = tbar;
  96         m_control = control;
  97         m_id = control->GetId();
  98
  99         m_isToggle = FALSE;
 100         m_enabled = TRUE;
 101         m_toggled = FALSE;
 102
 103         m_toolStyle = wxTOOL_STYLE_CONTROL;
 104     }
 105
 106     ~wxToolBarToolBase();
 107
 108     // accessors
 109     // ---------
 110
 111     // general
 112     int GetId() const { return m_id; }
 113
 114     wxControl *GetControl() const
 115     {
 116         wxASSERT_MSG( IsControl(), _T("this toolbar tool is not a control") );
 117
 118         return m_control;
 119     }
 120
 121     wxToolBarBase *GetToolBar() const { return m_tbar; }
 122
 123     // style
 124     bool IsButton() const { return m_toolStyle == wxTOOL_STYLE_BUTTON; }
 125     bool IsControl() const { return m_toolStyle == wxTOOL_STYLE_CONTROL; }
 126     bool IsSeparator() const { return m_toolStyle == wxTOOL_STYLE_SEPARATOR; }
 127     int GetStyle() const { return m_toolStyle; }
 128
 129     // state
 130     bool IsEnabled() const { return m_enabled; }
 131     bool IsToggled() const { return m_toggled; }
 132     bool CanBeToggled() const { return m_isToggle; }
 133
 134     // attributes
 135     const wxBitmap& GetBitmap1() const { return m_bitmap1; }
 136     const wxBitmap& GetBitmap2() const { return m_bitmap2; }
 137
 138     const wxBitmap& GetBitmap() const
 139         { return IsToggled() ? m_bitmap2 : m_bitmap1; }
 140
 141     wxString GetShortHelp() const { return m_shortHelpString; }
 142     wxString GetLongHelp() const { return m_longHelpString; }
 143
 144     wxObject *GetClientData() const
 145     {
 146         if ( m_toolStyle == wxTOOL_STYLE_CONTROL )
 147         {
 148             return (wxObject*)m_control->GetClientData();
 149         }
 150         else
 151         {
 152             return m_clientData;
 153         }
 154     }
 155
 156     // modifiers: return TRUE if the state really changed
 157     bool Enable(bool enable);
 158     bool Toggle(bool toggle);
 159     bool SetToggle(bool toggle);
 160     bool SetShortHelp(const wxString& help);
 161     bool SetLongHelp(const wxString& help);
 162
 163     void Toggle() { Toggle(!IsToggled()); }
 164
 165     void SetBitmap1(const wxBitmap& bmp) { m_bitmap1 = bmp; }
 166     void SetBitmap2(const wxBitmap& bmp) { m_bitmap2 = bmp; }
 167
 168     void SetClientData(wxObject *clientData)
 169     {
 170         if ( m_toolStyle == wxTOOL_STYLE_CONTROL )
 171         {
 172             m_control->SetClientData(clientData);
 173         }
 174         else
 175         {
 176             m_clientData = clientData;
 177         }
 178     }
 179
 180     // add tool to/remove it from a toolbar
 181     virtual void Detach() { m_tbar = (wxToolBarBase *)NULL; }
 182     virtual void Attach(wxToolBarBase *tbar) { m_tbar = tbar; }
 183
 184 protected:
 185     wxToolBarBase *m_tbar;  // the toolbar to which we belong (may be NULL)
 186
 187     int m_toolStyle; // see enum wxToolBarToolStyle
 188     int m_id;        // the tool id, wxID_SEPARATOR for separator
 189
 190     // as controls have their own client data, no need to waste memory
 191     union
 192     {
 193         wxObject         *m_clientData;
 194         wxControl        *m_control;
 195     };
 196
 197     // tool state
 198     bool m_toggled;
 199     bool m_isToggle;
 200     bool m_enabled;
 201
 202     // normal and toggles bitmaps
 203     wxBitmap m_bitmap1;
 204     wxBitmap m_bitmap2;
 205
 206     // short and long help strings
 207     wxString m_shortHelpString;
 208     wxString m_longHelpString;
 209 };
 210
 211 // a list of toolbar tools
 212 WX_DECLARE_EXPORTED_LIST(wxToolBarToolBase, wxToolBarToolsList);
 213
 214 // ----------------------------------------------------------------------------
 215 // the base class for all toolbars
 216 // ----------------------------------------------------------------------------
 217
 218 class WXDLLEXPORT wxToolBarBase : public wxControl
 219 {
 220 public:
 221     wxToolBarBase();
 222     virtual ~wxToolBarBase();
 223
 224     // toolbar construction
 225     // --------------------
 226
 227     // the most commonly used version of AddTool()
 228     wxToolBarToolBase *AddTool(int id,
 229                                const wxBitmap& bitmap,
 230                                const wxString& shortHelpString = wxEmptyString,
 231                                const wxString& longHelpString = wxEmptyString)
 232     {
 233         return AddTool(id, bitmap, wxNullBitmap, FALSE, NULL,
 234                        shortHelpString, longHelpString);
 235     }
 236
 237     // If pushedBitmap is NULL, a reversed version of bitmap is created and
 238     // used as the pushed/toggled image. If toggle is TRUE, the button toggles
 239     // between the two states.
 240     wxToolBarToolBase *AddTool(int id,
 241                                const wxBitmap& bitmap,
 242                                const wxBitmap& pushedBitmap,
 243                                bool toggle = FALSE,
 244                                wxObject *clientData = NULL,
 245                                const wxString& shortHelpString = wxEmptyString,
 246                                const wxString& longHelpString = wxEmptyString)
 247     {
 248         return AddTool(id, bitmap, pushedBitmap, toggle,
 249                        -1, -1, clientData, shortHelpString, longHelpString);
 250     }
 251
 252     // the old version of AddTool() kept for compatibility
 253     virtual wxToolBarToolBase *AddTool
 254                                (
 255                                    int id,
 256                                    const wxBitmap& bitmap,
 257                                    const wxBitmap& pushedBitmap,
 258                                    bool toggle,
 259                                    wxCoord xPos,
 260                                    wxCoord yPos = -1,
 261                                    wxObject *clientData = NULL,
 262                                    const wxString& helpString1 = wxEmptyString,
 263                                    const wxString& helpString2 = wxEmptyString
 264                                );
 265
 266     // insert the new tool at the given position, if pos == GetToolsCount(), it
 267     // is equivalent to AddTool()
 268     virtual wxToolBarToolBase *InsertTool
 269                                (
 270                                     size_t pos,
 271                                     int id,
 272                                     const wxBitmap& bitmap,
 273                                     const wxBitmap& pushedBitmap = wxNullBitmap,
 274                                     bool toggle = FALSE,
 275                                     wxObject *clientData = NULL,
 276                                     const wxString& help1 = wxEmptyString,
 277                                     const wxString& help2 = wxEmptyString
 278                                );
 279
 280     // add an arbitrary control to the toolbar, return TRUE if ok (notice that
 281     // the control will be deleted by the toolbar and that it will also adjust
 282     // its position/size)
 283     //
 284     // NB: the control should have toolbar as its parent
 285     virtual wxToolBarToolBase *AddControl(wxControl *control);
 286     virtual wxToolBarToolBase *InsertControl(size_t pos, wxControl *control);
 287
 288     // add a separator to the toolbar
 289     virtual wxToolBarToolBase *AddSeparator();
 290     virtual wxToolBarToolBase *InsertSeparator(size_t pos);
 291
 292     // remove the tool from the toolbar: the caller is responsible for actually
 293     // deleting the pointer
 294     virtual wxToolBarToolBase *RemoveTool(int id);
 295
 296     // delete tool either by index or by position
 297     virtual bool DeleteToolByPos(size_t pos);
 298     virtual bool DeleteTool(int id);
 299
 300     // delete all tools
 301     virtual void ClearTools();
 302
 303     // must be called after all buttons have been created to finish toolbar
 304     // initialisation
 305     virtual bool Realize();
 306
 307     // tools state
 308     // -----------
 309
 310     virtual void EnableTool(int id, bool enable);
 311     virtual void ToggleTool(int id, bool toggle);
 312
 313     // Set this to be togglable (or not)
 314     virtual void SetToggle(int id, bool toggle);
 315
 316     // set/get tools client data (not for controls)
 317     virtual wxObject *GetToolClientData(int id) const;
 318     virtual void SetToolClientData(int id, wxObject *clientData);
 319
 320     // return TRUE if the tool is toggled
 321     virtual bool GetToolState(int id) const;
 322
 323     virtual bool GetToolEnabled(int id) const;
 324
 325     virtual void SetToolShortHelp(int id, const wxString& helpString);
 326     virtual wxString GetToolShortHelp(int id) const;
 327     virtual void SetToolLongHelp(int id, const wxString& helpString);
 328     virtual wxString GetToolLongHelp(int id) const;
 329
 330     // margins/packing/separation
 331     // --------------------------
 332
 333     virtual void SetMargins(int x, int y);
 334     void SetMargins(const wxSize& size)
 335         { SetMargins((int) size.x, (int) size.y); }
 336     virtual void SetToolPacking(int packing)
 337         { m_toolPacking = packing; }
 338     virtual void SetToolSeparation(int separation)
 339         { m_toolSeparation = separation; }
 340
 341     virtual wxSize GetToolMargins() { return GetMargins(); }
 342     virtual int GetToolPacking() { return m_toolPacking; }
 343     virtual int GetToolSeparation() { return m_toolSeparation; }
 344
 345     // for compatibility
 346     wxSize GetMargins() const { return wxSize(m_xMargin, m_yMargin); }
 347
 348     // toolbar geometry
 349     // ----------------
 350
 351     // set the number of toolbar rows
 352     virtual void SetRows(int nRows);
 353
 354     // the toolbar can wrap - limit the number of columns or rows it may take
 355     void SetMaxRowsCols(int rows, int cols)
 356         { m_maxRows = rows; m_maxCols = cols; }
 357     int GetMaxRows() const { return m_maxRows; }
 358     int GetMaxCols() const { return m_maxCols; }
 359
 360     // get/set the size of the bitmaps used by the toolbar: should be called
 361     // before adding any tools to the toolbar
 362     virtual void SetToolBitmapSize(const wxSize& size)
 363         { m_defaultWidth = size.x; m_defaultHeight = size.y; };
 364     virtual wxSize GetToolBitmapSize() const
 365         { return wxSize(m_defaultWidth, m_defaultHeight); }
 366
 367     // the button size in some implementations is bigger than the bitmap size:
 368     // get the total button size (by default the same as bitmap size)
 369     virtual wxSize GetToolSize() const
 370         { return GetToolBitmapSize(); } ;
 371
 372     // returns a (non separator) tool containing the point (x, y) or NULL if
 373     // there is no tool at this point (corrdinates are client)
 374     virtual wxToolBarToolBase *FindToolForPosition(wxCoord x,
 375                                                    wxCoord y) const = 0;
 376
 377     // event handlers
 378     // --------------
 379
 380     // NB: these functions are deprecated, use EVT_TOOL_XXX() instead!
 381
 382     // Only allow toggle if returns TRUE. Call when left button up.
 383     virtual bool OnLeftClick(int id, bool toggleDown);
 384
 385     // Call when right button down.
 386     virtual void OnRightClick(int id, long x, long y);
 387
 388     // Called when the mouse cursor enters a tool bitmap.
 389     // Argument is -1 if mouse is exiting the toolbar.
 390     virtual void OnMouseEnter(int id);
 391
 392     // more deprecated functions
 393     // -------------------------
 394
 395 #if WXWIN_COMPATIBILITY
 396     void SetDefaultSize(int w, int h) { SetDefaultSize(wxSize(w, h)); }
 397     long GetDefaultWidth() const { return m_defaultWidth; }
 398     long GetDefaultHeight() const { return m_defaultHeight; }
 399     int GetDefaultButtonWidth() const { return (int) GetDefaultButtonSize().x; };
 400     int GetDefaultButtonHeight() const { return (int) GetDefaultButtonSize().y; };
 401     virtual void SetDefaultSize(const wxSize& size) { SetToolBitmapSize(size); }
 402     virtual wxSize GetDefaultSize() const { return GetToolBitmapSize(); }
 403     virtual wxSize GetDefaultButtonSize() const { return GetToolSize(); }
 404 #endif // WXWIN_COMPATIBILITY
 405
 406     // implementation only from now on
 407     // -------------------------------
 408
 409     size_t GetToolsCount() const { return m_tools.GetCount(); }
 410
 411     void OnIdle(wxIdleEvent& event);
 412
 413     // Do the toolbar button updates (check for EVT_UPDATE_UI handlers)
 414     virtual void DoToolbarUpdates();
 415
 416     // don't want toolbars to accept the focus
 417     virtual bool AcceptsFocus() const { return FALSE; }
 418
 419 protected:
 420     // to implement in derived classes
 421     // -------------------------------
 422
 423     // the tool is not yet inserted into m_tools list when this function is
 424     // called and will only be added to it if this function succeeds
 425     virtual bool DoInsertTool(size_t pos, wxToolBarToolBase *tool) = 0;
 426
 427     // the tool is still in m_tools list when this function is called, it will
 428     // only be deleted from it if it succeeds
 429     virtual bool DoDeleteTool(size_t pos, wxToolBarToolBase *tool) = 0;
 430
 431     // called when the tools enabled flag changes
 432     virtual void DoEnableTool(wxToolBarToolBase *tool, bool enable) = 0;
 433
 434     // called when the tool is toggled
 435     virtual void DoToggleTool(wxToolBarToolBase *tool, bool toggle) = 0;
 436
 437     // called when the tools "can be toggled" flag changes
 438     virtual void DoSetToggle(wxToolBarToolBase *tool, bool toggle) = 0;
 439
 440     // the functions to create toolbar tools
 441     virtual wxToolBarToolBase *CreateTool(int id,
 442                                           const wxBitmap& bitmap1,
 443                                           const wxBitmap& bitmap2,
 444                                           bool toggle,
 445                                           wxObject *clientData,
 446                                           const wxString& shortHelpString,
 447                                           const wxString& longHelpString) = 0;
 448     virtual wxToolBarToolBase *CreateTool(wxControl *control) = 0;
 449
 450     // helper functions
 451     // ----------------
 452
 453     // find the tool by id
 454     wxToolBarToolBase *FindById(int id) const;
 455
 456     // the list of all our tools
 457     wxToolBarToolsList m_tools;
 458
 459     // the offset of the first tool
 460     int m_xMargin;
 461     int m_yMargin;
 462
 463     // the maximum number of toolbar rows/columns
 464     int m_maxRows;
 465     int m_maxCols;
 466
 467     // the tool packing and separation
 468     int m_toolPacking,
 469         m_toolSeparation;
 470
 471     // the size of the toolbar bitmaps
 472     wxCoord m_defaultWidth, m_defaultHeight;
 473
 474 private:
 475     DECLARE_EVENT_TABLE()
 476     DECLARE_CLASS(wxToolBarBase)
 477 };
 478
 479 // Helper function for creating the image for disabled buttons
 480 bool wxCreateGreyedImage(const wxImage& in, wxImage& out) ;
 481
 482 #endif // wxUSE_TOOLBAR
 483
 484 #endif
 485     // _WX_TBARBASE_H_
 486