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