include/wx/generic/splitter.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/generic/splitter.h
   3 // Purpose:     wxSplitterWindow class
   4 // Author:      Julian Smart
   5 // Modified by:
   6 // Created:     01/02/97
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Julian Smart
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_GENERIC_SPLITTER_H_
  13 #define _WX_GENERIC_SPLITTER_H_
  14
  15 #include "wx/window.h"                      // base class declaration
  16 #include "wx/containr.h"                    // wxControlContainer
  17
  18 class WXDLLIMPEXP_FWD_CORE wxSplitterEvent;
  19
  20 // ---------------------------------------------------------------------------
  21 // splitter constants
  22 // ---------------------------------------------------------------------------
  23
  24 enum wxSplitMode
  25 {
  26     wxSPLIT_HORIZONTAL = 1,
  27     wxSPLIT_VERTICAL
  28 };
  29
  30 enum
  31 {
  32     wxSPLIT_DRAG_NONE,
  33     wxSPLIT_DRAG_DRAGGING,
  34     wxSPLIT_DRAG_LEFT_DOWN
  35 };
  36
  37 // ---------------------------------------------------------------------------
  38 // wxSplitterWindow maintains one or two panes, with
  39 // an optional vertical or horizontal split which
  40 // can be used with the mouse or programmatically.
  41 // ---------------------------------------------------------------------------
  42
  43 // TODO:
  44 // 1) Perhaps make the borders sensitive to dragging in order to create a split.
  45 //    The MFC splitter window manages scrollbars as well so is able to
  46 //    put sash buttons on the scrollbars, but we probably don't want to go down
  47 //    this path.
  48 // 2) for wxWidgets 2.0, we must find a way to set the WS_CLIPCHILDREN style
  49 //    to prevent flickering. (WS_CLIPCHILDREN doesn't work in all cases so can't be
  50 //    standard).
  51
  52 class WXDLLIMPEXP_CORE wxSplitterWindow: public wxNavigationEnabled<wxWindow>
  53 {
  54 public:
  55
  56 ////////////////////////////////////////////////////////////////////////////
  57 // Public API
  58
  59     // Default constructor
  60     wxSplitterWindow()
  61     {
  62         Init();
  63     }
  64
  65     // Normal constructor
  66     wxSplitterWindow(wxWindow *parent, wxWindowID id = wxID_ANY,
  67                      const wxPoint& pos = wxDefaultPosition,
  68                      const wxSize& size = wxDefaultSize,
  69                      long style = wxSP_3D,
  70                      const wxString& name = wxT("splitter"))
  71     {
  72         Init();
  73         Create(parent, id, pos, size, style, name);
  74     }
  75
  76     virtual ~wxSplitterWindow();
  77
  78     bool Create(wxWindow *parent, wxWindowID id = wxID_ANY,
  79                      const wxPoint& pos = wxDefaultPosition,
  80                      const wxSize& size = wxDefaultSize,
  81                      long style = wxSP_3D,
  82                      const wxString& name = wxT("splitter"));
  83
  84     // Gets the only or left/top pane
  85     wxWindow *GetWindow1() const { return m_windowOne; }
  86
  87     // Gets the right/bottom pane
  88     wxWindow *GetWindow2() const { return m_windowTwo; }
  89
  90     // Sets the split mode
  91     void SetSplitMode(int mode)
  92     {
  93         wxASSERT_MSG( mode == wxSPLIT_VERTICAL || mode == wxSPLIT_HORIZONTAL,
  94                       wxT("invalid split mode") );
  95
  96         m_splitMode = (wxSplitMode)mode;
  97     }
  98
  99     // Gets the split mode
 100     wxSplitMode GetSplitMode() const { return m_splitMode; }
 101
 102     // Initialize with one window
 103     void Initialize(wxWindow *window);
 104
 105     // Associates the given window with window 2, drawing the appropriate sash
 106     // and changing the split mode.
 107     // Does nothing and returns false if the window is already split.
 108     // A sashPosition of 0 means choose a default sash position,
 109     // negative sashPosition specifies the size of right/lower pane as it's
 110     // absolute value rather than the size of left/upper pane.
 111     virtual bool SplitVertically(wxWindow *window1,
 112                                  wxWindow *window2,
 113                                  int sashPosition = 0)
 114         { return DoSplit(wxSPLIT_VERTICAL, window1, window2, sashPosition); }
 115     virtual bool SplitHorizontally(wxWindow *window1,
 116                                    wxWindow *window2,
 117                                    int sashPosition = 0)
 118         { return DoSplit(wxSPLIT_HORIZONTAL, window1, window2, sashPosition); }
 119
 120     // Removes the specified (or second) window from the view
 121     // Doesn't actually delete the window.
 122     bool Unsplit(wxWindow *toRemove = NULL);
 123
 124     // Replaces one of the windows with another one (neither old nor new
 125     // parameter should be NULL)
 126     bool ReplaceWindow(wxWindow *winOld, wxWindow *winNew);
 127
 128     // Make sure the child window sizes are updated. This is useful
 129     // for reducing flicker by updating the sizes before a
 130     // window is shown, if you know the overall size is correct.
 131     void UpdateSize();
 132
 133     // Is the window split?
 134     bool IsSplit() const { return (m_windowTwo != NULL); }
 135
 136     // Sets the border size
 137     void SetBorderSize(int WXUNUSED(width)) { }
 138
 139     // Hide or show the sash and test whether it's currently hidden.
 140     void SetSashInvisible(bool invisible = true);
 141     bool IsSashInvisible() const { return HasFlag(wxSP_NOSASH); }
 142
 143     // Gets the current sash size which may be 0 if it's hidden and the default
 144     // sash size.
 145     int GetSashSize() const;
 146     int GetDefaultSashSize() const;
 147
 148     // Gets the border size
 149     int GetBorderSize() const;
 150
 151     // Set the sash position
 152     void SetSashPosition(int position, bool redraw = true);
 153
 154     // Gets the sash position
 155     int GetSashPosition() const { return m_sashPosition; }
 156
 157     // Set the sash gravity
 158     void SetSashGravity(double gravity);
 159
 160     // Gets the sash gravity
 161     double GetSashGravity() const { return m_sashGravity; }
 162
 163     // If this is zero, we can remove panes by dragging the sash.
 164     void SetMinimumPaneSize(int min);
 165     int GetMinimumPaneSize() const { return m_minimumPaneSize; }
 166
 167     // NB: the OnXXX() functions below are for backwards compatibility only,
 168     //     don't use them in new code but handle the events instead!
 169
 170     // called when the sash position is about to change, may return a new value
 171     // for the sash or -1 to prevent the change from happening at all
 172     virtual int OnSashPositionChanging(int newSashPosition);
 173
 174     // Called when the sash position is about to be changed, return
 175     // false from here to prevent the change from taking place.
 176     // Repositions sash to minimum position if pane would be too small.
 177     // newSashPosition here is always positive or zero.
 178     virtual bool OnSashPositionChange(int newSashPosition);
 179
 180     // If the sash is moved to an extreme position, a subwindow
 181     // is removed from the splitter window, and the app is
 182     // notified. The app should delete or hide the window.
 183     virtual void OnUnsplit(wxWindow *removed);
 184
 185     // Called when the sash is double-clicked.
 186     // The default behaviour is to remove the sash if the
 187     // minimum pane size is zero.
 188     virtual void OnDoubleClickSash(int x, int y);
 189
 190 ////////////////////////////////////////////////////////////////////////////
 191 // Implementation
 192
 193     // Paints the border and sash
 194     void OnPaint(wxPaintEvent& event);
 195
 196     // Handles mouse events
 197     void OnMouseEvent(wxMouseEvent& ev);
 198
 199     // Aborts dragging mode
 200     void OnMouseCaptureLost(wxMouseCaptureLostEvent& event);
 201
 202     // Adjusts the panes
 203     void OnSize(wxSizeEvent& event);
 204
 205     // In live mode, resize child windows in idle time
 206     void OnInternalIdle();
 207
 208     // Draws the sash
 209     virtual void DrawSash(wxDC& dc);
 210
 211     // Draws the sash tracker (for whilst moving the sash)
 212     virtual void DrawSashTracker(int x, int y);
 213
 214     // Tests for x, y over sash
 215     virtual bool SashHitTest(int x, int y);
 216
 217     // Resizes subwindows
 218     virtual void SizeWindows();
 219
 220 #ifdef __WXMAC__
 221     virtual bool MacClipGrandChildren() const { return true ; }
 222 #endif
 223
 224     // Sets the sash size: this doesn't do anything and shouldn't be used at
 225     // all any more.
 226     wxDEPRECATED_INLINE( void SetSashSize(int WXUNUSED(width)), return; )
 227
 228 protected:
 229     // event handlers
 230 #if defined(__WXMSW__) || defined(__WXMAC__)
 231     void OnSetCursor(wxSetCursorEvent& event);
 232 #endif // wxMSW
 233
 234     // send the given event, return false if the event was processed and vetoed
 235     // by the user code
 236     bool DoSendEvent(wxSplitterEvent& event);
 237
 238     // common part of all ctors
 239     void Init();
 240
 241     // common part of SplitVertically() and SplitHorizontally()
 242     bool DoSplit(wxSplitMode mode,
 243                  wxWindow *window1, wxWindow *window2,
 244                  int sashPosition);
 245
 246     // adjusts sash position with respect to min. pane and window sizes
 247     int AdjustSashPosition(int sashPos) const;
 248
 249     // get either width or height depending on the split mode
 250     int GetWindowSize() const;
 251
 252     // convert the user specified sash position which may be > 0 (as is), < 0
 253     // (specifying the size of the right pane) or 0 (use default) to the real
 254     // position to be passed to DoSetSashPosition()
 255     int ConvertSashPosition(int sashPos) const;
 256
 257     // set the real sash position, sashPos here must be positive
 258     //
 259     // returns true if the sash position has been changed, false otherwise
 260     bool DoSetSashPosition(int sashPos);
 261
 262     // set the sash position and send an event about it having been changed
 263     void SetSashPositionAndNotify(int sashPos);
 264
 265     // callbacks executed when we detect that the mouse has entered or left
 266     // the sash
 267     virtual void OnEnterSash();
 268     virtual void OnLeaveSash();
 269
 270     // set the cursor appropriate for the current split mode
 271     void SetResizeCursor();
 272
 273     // redraw the splitter if its "hotness" changed if necessary
 274     void RedrawIfHotSensitive(bool isHot);
 275
 276     // return the best size of the splitter equal to best sizes of its
 277     // subwindows
 278     virtual wxSize DoGetBestSize() const;
 279
 280
 281     wxSplitMode m_splitMode;
 282     wxWindow*   m_windowOne;
 283     wxWindow*   m_windowTwo;
 284     int         m_dragMode;
 285     int         m_oldX;         // current tracker position if not live mode
 286     int         m_oldY;         // current tracker position if not live mode
 287     int         m_sashPosition; // Number of pixels from left or top
 288     double      m_sashGravity;
 289     wxSize      m_lastSize;
 290     int         m_requestedSashPosition;
 291     int         m_sashPositionCurrent; // while dragging
 292     wxPoint     m_ptStart;      // mouse position when dragging started
 293     int         m_sashStart;    // sash position when dragging started
 294     int         m_minimumPaneSize;
 295     wxCursor    m_sashCursorWE;
 296     wxCursor    m_sashCursorNS;
 297     wxPen      *m_sashTrackerPen;
 298
 299     // when in live mode, set this to true to resize children in idle
 300     bool        m_needUpdating:1;
 301     bool        m_permitUnsplitAlways:1;
 302     bool        m_isHot:1;
 303
 304 private:
 305     DECLARE_DYNAMIC_CLASS(wxSplitterWindow)
 306     DECLARE_EVENT_TABLE()
 307     wxDECLARE_NO_COPY_CLASS(wxSplitterWindow);
 308 };
 309
 310 // ----------------------------------------------------------------------------
 311 // event class and macros
 312 // ----------------------------------------------------------------------------
 313
 314 // we reuse the same class for all splitter event types because this is the
 315 // usual wxWin convention, but the three event types have different kind of
 316 // data associated with them, so the accessors can be only used if the real
 317 // event type matches with the one for which the accessors make sense
 318 class WXDLLIMPEXP_CORE wxSplitterEvent : public wxNotifyEvent
 319 {
 320 public:
 321     wxSplitterEvent(wxEventType type = wxEVT_NULL,
 322                     wxSplitterWindow *splitter = NULL)
 323         : wxNotifyEvent(type)
 324     {
 325         SetEventObject(splitter);
 326         if (splitter) m_id = splitter->GetId();
 327     }
 328     wxSplitterEvent(const wxSplitterEvent& event)
 329         : wxNotifyEvent(event), m_data(event.m_data) { }
 330
 331     // SASH_POS_CHANGED methods
 332
 333     // setting the sash position to -1 prevents the change from taking place at
 334     // all
 335     void SetSashPosition(int pos)
 336     {
 337         wxASSERT( GetEventType() == wxEVT_SPLITTER_SASH_POS_CHANGED
 338                 || GetEventType() == wxEVT_SPLITTER_SASH_POS_CHANGING);
 339
 340         m_data.pos = pos;
 341     }
 342
 343     int GetSashPosition() const
 344     {
 345         wxASSERT( GetEventType() == wxEVT_SPLITTER_SASH_POS_CHANGED
 346                 || GetEventType() == wxEVT_SPLITTER_SASH_POS_CHANGING);
 347
 348         return m_data.pos;
 349     }
 350
 351     // UNSPLIT event methods
 352     wxWindow *GetWindowBeingRemoved() const
 353     {
 354         wxASSERT( GetEventType() == wxEVT_SPLITTER_UNSPLIT );
 355
 356         return m_data.win;
 357     }
 358
 359     // DCLICK event methods
 360     int GetX() const
 361     {
 362         wxASSERT( GetEventType() == wxEVT_SPLITTER_DOUBLECLICKED );
 363
 364         return m_data.pt.x;
 365     }
 366
 367     int GetY() const
 368     {
 369         wxASSERT( GetEventType() == wxEVT_SPLITTER_DOUBLECLICKED );
 370
 371         return m_data.pt.y;
 372     }
 373
 374     virtual wxEvent *Clone() const { return new wxSplitterEvent(*this); }
 375
 376 private:
 377     friend class WXDLLIMPEXP_FWD_CORE wxSplitterWindow;
 378
 379     // data for the different types of event
 380     union
 381     {
 382         int pos;            // position for SASH_POS_CHANGED event
 383         wxWindow *win;      // window being removed for UNSPLIT event
 384         struct
 385         {
 386             int x, y;
 387         } pt;               // position of double click for DCLICK event
 388     } m_data;
 389
 390     DECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxSplitterEvent)
 391 };
 392
 393 typedef void (wxEvtHandler::*wxSplitterEventFunction)(wxSplitterEvent&);
 394
 395 #define wxSplitterEventHandler(func) \
 396     wxEVENT_HANDLER_CAST(wxSplitterEventFunction, func)
 397
 398 #define wx__DECLARE_SPLITTEREVT(evt, id, fn) \
 399     wx__DECLARE_EVT1(wxEVT_SPLITTER_ ## evt, id, wxSplitterEventHandler(fn))
 400
 401 #define EVT_SPLITTER_SASH_POS_CHANGED(id, fn) \
 402     wx__DECLARE_SPLITTEREVT(SASH_POS_CHANGED, id, fn)
 403
 404 #define EVT_SPLITTER_SASH_POS_CHANGING(id, fn) \
 405     wx__DECLARE_SPLITTEREVT(SASH_POS_CHANGING, id, fn)
 406
 407 #define EVT_SPLITTER_DCLICK(id, fn) \
 408     wx__DECLARE_SPLITTEREVT(DOUBLECLICKED, id, fn)
 409
 410 #define EVT_SPLITTER_UNSPLIT(id, fn) \
 411     wx__DECLARE_SPLITTEREVT(UNSPLIT, id, fn)
 412
 413
 414 // old wxEVT_COMMAND_* constants
 415 #define wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED    wxEVT_SPLITTER_SASH_POS_CHANGED
 416 #define wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING   wxEVT_SPLITTER_SASH_POS_CHANGING
 417 #define wxEVT_COMMAND_SPLITTER_DOUBLECLICKED       wxEVT_SPLITTER_DOUBLECLICKED
 418 #define wxEVT_COMMAND_SPLITTER_UNSPLIT             wxEVT_SPLITTER_UNSPLIT
 419
 420 #endif // _WX_GENERIC_SPLITTER_H_