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