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 (wxObject*)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_EXPORTED_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     // the most commonly used version of AddTool()
 225     wxToolBarToolBase *AddTool(int id,
 226                                const wxBitmap& bitmap,
 227                                const wxString& shortHelpString = wxEmptyString,
 228                                const wxString& longHelpString = wxEmptyString)
 229     {
 230         return AddTool(id, bitmap, wxNullBitmap, FALSE, NULL,
 231                        shortHelpString, longHelpString);
 232     }
 233
 234     // If pushedBitmap is NULL, a reversed version of bitmap is created and
 235     // used as the pushed/toggled image. If toggle is TRUE, the button toggles
 236     // between the two states.
 237     wxToolBarToolBase *AddTool(int id,
 238                                const wxBitmap& bitmap,
 239                                const wxBitmap& pushedBitmap = wxNullBitmap,
 240                                bool toggle = FALSE,
 241                                wxObject *clientData = NULL,
 242                                const wxString& shortHelpString = wxEmptyString,
 243                                const wxString& longHelpString = wxEmptyString)
 244     {
 245         return AddTool(id, bitmap, pushedBitmap, toggle,
 246                        -1, -1, clientData, shortHelpString, longHelpString);
 247     }
 248
 249     // the old version of AddTool() kept for compatibility
 250     virtual wxToolBarToolBase *AddTool
 251                                (
 252                                    int id,
 253                                    const wxBitmap& bitmap,
 254                                    const wxBitmap& pushedBitmap,
 255                                    bool toggle,
 256                                    wxCoord xPos,
 257                                    wxCoord yPos = -1,
 258                                    wxObject *clientData = NULL,
 259                                    const wxString& helpString1 = wxEmptyString,
 260                                    const wxString& helpString2 = wxEmptyString
 261                                );
 262
 263     // insert the new tool at the given position, if pos == GetToolsCount(), it
 264     // is equivalent to AddTool()
 265     virtual wxToolBarToolBase *InsertTool
 266                                (
 267                                     size_t pos,
 268                                     int id,
 269                                     const wxBitmap& bitmap,
 270                                     const wxBitmap& pushedBitmap = wxNullBitmap,
 271                                     bool toggle = FALSE,
 272                                     wxObject *clientData = NULL,
 273                                     const wxString& help1 = wxEmptyString,
 274                                     const wxString& help2 = wxEmptyString
 275                                );
 276
 277     // add an arbitrary control to the toolbar, return TRUE if ok (notice that
 278     // the control will be deleted by the toolbar and that it will also adjust
 279     // its position/size)
 280     //
 281     // NB: the control should have toolbar as its parent
 282     virtual wxToolBarToolBase *AddControl(wxControl *control);
 283     virtual wxToolBarToolBase *InsertControl(size_t pos, wxControl *control);
 284
 285     // add a separator to the toolbar
 286     virtual wxToolBarToolBase *AddSeparator();
 287     virtual wxToolBarToolBase *InsertSeparator(size_t pos);
 288
 289     // remove the tool from the toolbar: the caller is responsible for actually
 290     // deleting the pointer
 291     virtual wxToolBarToolBase *RemoveTool(int id);
 292
 293     // delete tool either by index or by position
 294     virtual bool DeleteToolByPos(size_t pos);
 295     virtual bool DeleteTool(int id);
 296
 297     // delete all tools
 298     virtual void ClearTools();
 299
 300     // must be called after all buttons have been created to finish toolbar
 301     // initialisation
 302     virtual bool Realize();
 303
 304     // tools state
 305     // -----------
 306
 307     virtual void EnableTool(int id, bool enable);
 308     virtual void ToggleTool(int id, bool toggle);
 309
 310     // Set this to be togglable (or not)
 311     virtual void SetToggle(int id, bool toggle);
 312
 313     // set/get tools client data (not for controls)
 314     virtual wxObject *GetToolClientData(int id) const;
 315     virtual void SetToolClientData(int id, wxObject *clientData);
 316
 317     // return TRUE if the tool is toggled
 318     virtual bool GetToolState(int id) const;
 319
 320     virtual bool GetToolEnabled(int id) const;
 321
 322     virtual void SetToolShortHelp(int id, const wxString& helpString);
 323     virtual wxString GetToolShortHelp(int id) const;
 324     virtual void SetToolLongHelp(int id, const wxString& helpString);
 325     virtual wxString GetToolLongHelp(int id) const;
 326
 327     // margins/packing/separation
 328     // --------------------------
 329
 330     virtual void SetMargins(int x, int y);
 331     void SetMargins(const wxSize& size)
 332         { SetMargins((int) size.x, (int) size.y); }
 333     virtual void SetToolPacking(int packing)
 334         { m_toolPacking = packing; }
 335     virtual void SetToolSeparation(int separation)
 336         { m_toolSeparation = separation; }
 337
 338     virtual wxSize GetToolMargins() { return wxSize(m_xMargin, m_yMargin); }
 339     virtual int GetToolPacking() { return m_toolPacking; }
 340     virtual int GetToolSeparation() { return m_toolSeparation; }
 341
 342     // toolbar geometry
 343     // ----------------
 344
 345     // set the number of toolbar rows
 346     virtual void SetRows(int nRows);
 347
 348     // the toolbar can wrap - limit the number of columns or rows it may take
 349     void SetMaxRowsCols(int rows, int cols)
 350         { m_maxRows = rows; m_maxCols = cols; }
 351     int GetMaxRows() const { return m_maxRows; }
 352     int GetMaxCols() const { return m_maxCols; }
 353
 354     // get/set the size of the bitmaps used by the toolbar: should be called
 355     // before adding any tools to the toolbar
 356     virtual void SetToolBitmapSize(const wxSize& size)
 357         { m_defaultWidth = size.x; m_defaultHeight = size.y; };
 358     virtual wxSize GetToolBitmapSize() const
 359         { return wxSize(m_defaultWidth, m_defaultHeight); }
 360
 361     // the button size in some implementations is bigger than the bitmap size:
 362     // get the total button size (by default the same as bitmap size)
 363     virtual wxSize GetToolSize() const
 364         { return GetToolBitmapSize(); } ;
 365
 366     // returns a (non separator) tool containing the point (x, y) or NULL if
 367     // there is no tool at this point (corrdinates are client)
 368     virtual wxToolBarToolBase *FindToolForPosition(wxCoord x,
 369                                                    wxCoord y) const = 0;
 370
 371     // event handlers
 372     // --------------
 373
 374     // NB: these functions are deprecated, use EVT_TOOL_XXX() instead!
 375
 376     // Only allow toggle if returns TRUE. Call when left button up.
 377     virtual bool OnLeftClick(int id, bool toggleDown);
 378
 379     // Call when right button down.
 380     virtual void OnRightClick(int id, long x, long y);
 381
 382     // Called when the mouse cursor enters a tool bitmap.
 383     // Argument is -1 if mouse is exiting the toolbar.
 384     virtual void OnMouseEnter(int id);
 385
 386     // more deprecated functions
 387     // -------------------------
 388
 389 #if WXWIN_COMPATIBILITY
 390     void SetDefaultSize(int w, int h) { SetDefaultSize(wxSize(w, h)); }
 391     long GetDefaultWidth() const { return m_defaultWidth; }
 392     long GetDefaultHeight() const { return m_defaultHeight; }
 393     int GetDefaultButtonWidth() const { return (int) GetDefaultButtonSize().x; };
 394     int GetDefaultButtonHeight() const { return (int) GetDefaultButtonSize().y; };
 395     virtual void SetDefaultSize(const wxSize& size) { SetToolBitmapSize(size); }
 396     virtual wxSize GetDefaultSize() const { return GetToolBitmapSize(); }
 397     virtual wxSize GetDefaultButtonSize() const { return GetToolSize(); }
 398 #endif // WXWIN_COMPATIBILITY
 399
 400     // implementation only from now on
 401     // -------------------------------
 402
 403     size_t GetToolsCount() const { return m_tools.GetCount(); }
 404
 405     void OnIdle(wxIdleEvent& event);
 406
 407     // Do the toolbar button updates (check for EVT_UPDATE_UI handlers)
 408     virtual void DoToolbarUpdates();
 409
 410 protected:
 411     // to implement in derived classes
 412     // -------------------------------
 413
 414     // the tool is not yet inserted into m_tools list when this function is
 415     // called and will only be added to it if this function succeeds
 416     virtual bool DoInsertTool(size_t pos, wxToolBarToolBase *tool) = 0;
 417
 418     // the tool is still in m_tools list when this function is called, it will
 419     // only be deleted from it if it succeeds
 420     virtual bool DoDeleteTool(size_t pos, wxToolBarToolBase *tool) = 0;
 421
 422     // called when the tools enabled flag changes
 423     virtual void DoEnableTool(wxToolBarToolBase *tool, bool enable) = 0;
 424
 425     // called when the tool is toggled
 426     virtual void DoToggleTool(wxToolBarToolBase *tool, bool toggle) = 0;
 427
 428     // called when the tools "can be toggled" flag changes
 429     virtual void DoSetToggle(wxToolBarToolBase *tool, bool toggle) = 0;
 430
 431     // the functions to create toolbar tools
 432     virtual wxToolBarToolBase *CreateTool(int id,
 433                                           const wxBitmap& bitmap1,
 434                                           const wxBitmap& bitmap2,
 435                                           bool toggle,
 436                                           wxObject *clientData,
 437                                           const wxString& shortHelpString,
 438                                           const wxString& longHelpString) = 0;
 439     virtual wxToolBarToolBase *CreateTool(wxControl *control) = 0;
 440
 441     // helper functions
 442     // ----------------
 443
 444     // find the tool by id
 445     wxToolBarToolBase *FindById(int id) const;
 446
 447     // the list of all our tools
 448     wxToolBarToolsList m_tools;
 449
 450     // the offset of the first tool
 451     int m_xMargin;
 452     int m_yMargin;
 453
 454     // the maximum number of toolbar rows/columns
 455     int m_maxRows;
 456     int m_maxCols;
 457
 458     // the tool packing and separation
 459     int m_toolPacking,
 460         m_toolSeparation;
 461
 462     // the size of the toolbar bitmaps
 463     wxCoord m_defaultWidth, m_defaultHeight;
 464
 465 private:
 466     DECLARE_EVENT_TABLE()
 467 };
 468
 469 #endif
 470     // _WX_TBARBASE_H_
 471