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