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