interface/wx/splitter.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        splitter.h
   3 // Purpose:     interface of wxSplitterWindow
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9 #define wxSP_NOBORDER         0x0000
  10 #define wxSP_THIN_SASH        0x0000    // NB: the default is 3D sash
  11 #define wxSP_NOSASH           0x0010
  12 #define wxSP_PERMIT_UNSPLIT   0x0040
  13 #define wxSP_LIVE_UPDATE      0x0080
  14 #define wxSP_3DSASH           0x0100
  15 #define wxSP_3DBORDER         0x0200
  16 #define wxSP_NO_XP_THEME      0x0400
  17 #define wxSP_BORDER           wxSP_3DBORDER
  18 #define wxSP_3D               (wxSP_3DBORDER | wxSP_3DSASH)
  19
  20
  21 enum wxSplitMode
  22 {
  23     wxSPLIT_HORIZONTAL = 1,
  24     wxSPLIT_VERTICAL
  25 };
  26
  27 enum
  28 {
  29     wxSPLIT_DRAG_NONE,
  30     wxSPLIT_DRAG_DRAGGING,
  31     wxSPLIT_DRAG_LEFT_DOWN
  32 };
  33
  34 /**
  35     @class wxSplitterWindow
  36
  37     This class manages up to two subwindows. The current view can be split
  38     into two programmatically (perhaps from a menu command), and unsplit
  39     either programmatically or via the wxSplitterWindow user interface.
  40
  41     @beginStyleTable
  42     @style{wxSP_3D}
  43            Draws a 3D effect border and sash.
  44     @style{wxSP_THIN_SASH}
  45            Draws a thin sash.
  46     @style{wxSP_3DSASH}
  47            Draws a 3D effect sash (part of default style).
  48     @style{wxSP_3DBORDER}
  49            Synonym for wxSP_BORDER.
  50     @style{wxSP_BORDER}
  51            Draws a standard border.
  52     @style{wxSP_NOBORDER}
  53            No border (default).
  54     @style{wxSP_NO_XP_THEME}
  55            Under Windows XP, switches off the attempt to draw the splitter
  56            using Windows XP theming, so the borders and sash will take on the
  57            pre-XP look.
  58     @style{wxSP_PERMIT_UNSPLIT}
  59            Always allow to unsplit, even with the minimum pane size other than zero.
  60     @style{wxSP_LIVE_UPDATE}
  61            Don't draw XOR line but resize the child windows immediately.
  62     @endStyleTable
  63
  64
  65     @beginEventEmissionTable{wxSplitterEvent}
  66     @event{EVT_SPLITTER_SASH_POS_CHANGING(id, func)}
  67         The sash position is in the process of being changed.
  68         May be used to modify the position of the tracking bar to properly
  69         reflect the position that would be set if the drag were to be completed
  70         at this point. Processes a @c wxEVT_SPLITTER_SASH_POS_CHANGING event.
  71     @event{EVT_SPLITTER_SASH_POS_CHANGED(id, func)}
  72         The sash position was changed. May be used to modify the sash position
  73         before it is set, or to prevent the change from taking place.
  74         Processes a @c wxEVT_SPLITTER_SASH_POS_CHANGED event.
  75     @event{EVT_SPLITTER_UNSPLIT(id, func)}
  76         The splitter has been just unsplit. Processes a @c wxEVT_SPLITTER_UNSPLIT event.
  77     @event{EVT_SPLITTER_DCLICK(id, func)}
  78         The sash was double clicked. The default behaviour is to unsplit the
  79         window when this happens (unless the minimum pane size has been set
  80         to a value greater than zero). Processes a @c wxEVT_SPLITTER_DOUBLECLICKED event.
  81     @endEventTable
  82
  83
  84     @library{wxcore}
  85     @category{miscwnd}
  86
  87     @see wxSplitterEvent, @ref overview_splitterwindow
  88 */
  89 class wxSplitterWindow : public wxWindow
  90 {
  91 public:
  92     /**
  93       Default constructor
  94     */
  95     wxSplitterWindow();
  96
  97     /**
  98         Constructor for creating the window.
  99
 100         @param parent
 101             The parent of the splitter window.
 102         @param id
 103             The window identifier.
 104         @param pos
 105             The window position.
 106         @param size
 107             The window size.
 108         @param style
 109             The window style. See wxSplitterWindow.
 110         @param name
 111             The window name.
 112
 113         @remarks
 114             After using this constructor, you must create either one or two
 115             subwindows with the splitter window as parent, and then call one
 116             of Initialize(), SplitVertically() and SplitHorizontally() in order
 117             to set the pane(s).
 118             You can create two windows, with one hidden when not being shown;
 119             or you can create and delete the second pane on demand.
 120
 121         @see Initialize(), SplitVertically(), SplitHorizontally(), Create()
 122     */
 123     wxSplitterWindow(wxWindow* parent, wxWindowID id = wxID_ANY,
 124                      const wxPoint& pos = wxDefaultPosition,
 125                      const wxSize& size = wxDefaultSize,
 126                      long style = wxSP_3D,
 127                      const wxString& name = "splitterWindow");
 128
 129     /**
 130         Destroys the wxSplitterWindow and its children.
 131     */
 132     virtual ~wxSplitterWindow();
 133
 134     /**
 135         Creation function, for two-step construction.
 136         See wxSplitterWindow() for details.
 137     */
 138     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 139                 const wxPoint& point = wxDefaultPosition,
 140                 const wxSize& size = wxDefaultSize, long style = wxSP_3D,
 141                 const wxString& name = "splitter");
 142
 143     /**
 144         Returns the current minimum pane size (defaults to zero).
 145
 146         @see SetMinimumPaneSize()
 147     */
 148     int GetMinimumPaneSize() const;
 149
 150     /**
 151         Returns the current sash gravity.
 152
 153         @see SetSashGravity()
 154     */
 155     double GetSashGravity() const;
 156
 157     /**
 158         Returns the current sash position.
 159
 160         @see SetSashPosition()
 161     */
 162     int GetSashPosition() const;
 163
 164     /**
 165         Returns the default sash size in pixels or 0 if it is invisible.
 166
 167         @see GetDefaultSashSize(), IsSashInvisible()
 168      */
 169     int GetSashSize() const;
 170
 171     /**
 172         Returns the default sash size in pixels.
 173
 174         The size of the sash is its width for a vertically split window and its
 175         height for a horizontally split one. Its other direction is the same as
 176         the client size of the window in the corresponding direction.
 177
 178         The default sash size is platform-dependent because it conforms to the
 179         current platform look-and-feel and cannot be changed.
 180
 181         @since 2.9.4
 182      */
 183     int GetDefaultSashSize() const;
 184
 185     /**
 186         Gets the split mode.
 187
 188         @see SetSplitMode(), SplitVertically(), SplitHorizontally().
 189     */
 190     wxSplitMode GetSplitMode() const;
 191
 192     /**
 193         Returns the left/top or only pane.
 194     */
 195     wxWindow* GetWindow1() const;
 196
 197     /**
 198         Returns the right/bottom pane.
 199     */
 200     wxWindow* GetWindow2() const;
 201
 202     /**
 203         Initializes the splitter window to have one pane.
 204         The child window is shown if it is currently hidden.
 205
 206         @param window
 207             The pane for the unsplit window.
 208
 209         @remarks This should be called if you wish to initially view only a
 210                  single pane in the splitter window.
 211
 212         @see SplitVertically(), SplitHorizontally()
 213     */
 214     void Initialize(wxWindow* window);
 215
 216     /**
 217         Returns @true if the sash is invisible even when the window is split, @false otherwise.
 218
 219         @remark This is a shortcut for HasFlag(wxSP_NOSASH)
 220
 221         @see SetSashInvisible()
 222
 223         @since 2.9.4
 224     */
 225     bool IsSashInvisible() const;
 226
 227     /**
 228         Returns @true if the window is split, @false otherwise.
 229     */
 230     bool IsSplit() const;
 231
 232     /**
 233         Application-overridable function called when the sash is double-clicked with
 234         the left mouse button.
 235
 236         @param x
 237             The x position of the mouse cursor.
 238         @param y
 239             The y position of the mouse cursor.
 240
 241         @remarks The default implementation of this function calls Unsplit if the
 242                  minimum pane size is zero.
 243
 244         @see Unsplit()
 245     */
 246     virtual void OnDoubleClickSash(int x, int y);
 247
 248     /**
 249         Application-overridable function called when the sash position is changed by
 250         user. It may return @false to prevent the change or @true to allow it.
 251
 252         @param newSashPosition
 253             The new sash position (always positive or zero)
 254
 255         @remarks The default implementation of this function verifies that the
 256                  sizes of both  panes of the splitter are greater than
 257                  minimum pane size.
 258     */
 259     virtual bool OnSashPositionChange(int newSashPosition);
 260
 261     /**
 262         Application-overridable function called when the window is unsplit, either
 263         programmatically or using the wxSplitterWindow user interface.
 264
 265         @param removed
 266             The window being removed.
 267
 268         @remarks The default implementation of this function simply hides
 269                  removed. You may wish to delete the window.
 270     */
 271     virtual void OnUnsplit(wxWindow* removed);
 272
 273     /**
 274         This function replaces one of the windows managed by the wxSplitterWindow with
 275         another one. It is in general better to use it instead of calling Unsplit()
 276         and then resplitting the window back because it will provoke much less flicker
 277         (if any). It is valid to call this function whether the splitter has two
 278         windows or only one.
 279
 280         Both parameters should be non-@NULL and @a winOld must specify one of the
 281         windows managed by the splitter. If the parameters are incorrect or the window
 282         couldn't be replaced, @false is returned. Otherwise the function will return
 283         @true, but please notice that it will not delete the replaced window and you
 284         may wish to do it yourself.
 285
 286         @see GetMinimumPaneSize()
 287     */
 288     bool ReplaceWindow(wxWindow* winOld, wxWindow* winNew);
 289
 290     /**
 291         Sets the minimum pane size.
 292
 293         @param paneSize
 294             Minimum pane size in pixels.
 295
 296         @remarks The default minimum pane size is zero, which means that either
 297                  pane can be reduced to zero by dragging the sash, thus
 298                  removing one of the panes. To prevent this behaviour
 299                  (and veto out-of-range sash dragging), set a minimum
 300                  size, for example 20 pixels. If the wxSP_PERMIT_UNSPLIT
 301                  style is used when a splitter window is created, the
 302                  window may be unsplit even if minimum size is non-zero.
 303
 304         @see GetMinimumPaneSize()
 305     */
 306     void SetMinimumPaneSize(int paneSize);
 307
 308     /**
 309         Sets the sash gravity.
 310
 311         @param gravity
 312             The sash gravity. Value between 0.0 and 1.0.
 313
 314         @remarks
 315         Gravity is real factor which controls position of sash while resizing
 316         wxSplitterWindow. Gravity tells wxSplitterWindow how much will left/top
 317         window grow while resizing.
 318         Example values:
 319         - 0.0: only the bottom/right window is automatically resized
 320         - 0.5: both windows grow by equal size
 321         - 1.0: only left/top window grows
 322         Gravity should be a real value between 0.0 and 1.0.
 323         Default value of sash gravity is 0.0.
 324         That value is compatible with previous (before gravity was introduced)
 325         behaviour of wxSplitterWindow.
 326
 327         @see GetSashGravity()
 328     */
 329     void SetSashGravity(double gravity);
 330
 331     /**
 332         Sets the sash position.
 333
 334         @param position
 335             The sash position in pixels.
 336         @param redraw
 337             If @true, resizes the panes and redraws the sash and border.
 338
 339         @remarks Does not currently check for an out-of-range value.
 340
 341         @see GetSashPosition()
 342     */
 343     void SetSashPosition(int position, bool redraw = true);
 344
 345     /**
 346         Sets the split mode.
 347
 348         @param mode
 349             Can be wxSPLIT_VERTICAL or wxSPLIT_HORIZONTAL.
 350
 351         @remarks Only sets the internal variable; does not update the display.
 352
 353         @see GetSplitMode(), SplitVertically(), SplitHorizontally().
 354     */
 355     void SetSplitMode(int mode);
 356
 357     /**
 358         Sets whether the sash should be invisible, even when the window is
 359         split.
 360
 361         When the sash is invisible, it doesn't appear on the screen at all and,
 362         in particular, doesn't allow the user to resize the windows.
 363
 364         @remarks Only sets the internal variable; does not update the display.
 365
 366         @param invisible
 367             If @true, the sash is always invisible, else it is shown when the
 368             window is split.
 369
 370         @see IsSashInvisible()
 371
 372         @since 2.9.4
 373     */
 374     void SetSashInvisible(bool invisible=true);
 375
 376     /**
 377         Initializes the top and bottom panes of the splitter window.
 378         The child windows are shown if they are currently hidden.
 379
 380         @param window1
 381             The top pane.
 382         @param window2
 383             The bottom pane.
 384         @param sashPosition
 385             The initial position of the sash. If this value is positive,
 386             it specifies the size of the upper pane. If it is negative, its
 387             absolute value gives the size of the lower pane.
 388             Finally, specify 0 (default) to choose the default position
 389             (half of the total window height).
 390
 391         @return @true if successful, @false otherwise (the window was already split).
 392
 393         @remarks This should be called if you wish to initially view two panes.
 394                  It can also be called at any subsequent time, but the application
 395                  should check that the window is not currently split using IsSplit().
 396
 397         @see SplitVertically(), IsSplit(), Unsplit()
 398     */
 399     virtual bool SplitHorizontally(wxWindow* window1, wxWindow* window2,
 400                                    int sashPosition = 0);
 401
 402     /**
 403         Initializes the left and right panes of the splitter window.
 404         The child windows are shown if they are currently hidden.
 405
 406         @param window1
 407             The left pane.
 408         @param window2
 409             The right pane.
 410         @param sashPosition
 411             The initial position of the sash. If this value is positive, it
 412             specifies the size of the left pane. If it is negative, it is
 413             absolute value gives the size of the right pane.
 414             Finally, specify 0 (default) to choose the default position
 415             (half of the total window width).
 416
 417         @return @true if successful, @false otherwise (the window was already split).
 418
 419         @remarks This should be called if you wish to initially view two panes.
 420                  It can also be called at any subsequent time, but the
 421                  application should check that the window is not currently
 422                  split using IsSplit().
 423
 424         @see SplitHorizontally(), IsSplit(), Unsplit().
 425     */
 426     virtual bool SplitVertically(wxWindow* window1, wxWindow* window2,
 427                                  int sashPosition = 0);
 428
 429     /**
 430         Unsplits the window.
 431
 432         @param toRemove
 433             The pane to remove, or @NULL to remove the right or bottom pane.
 434
 435         @return @true if successful, @false otherwise (the window was not split).
 436
 437         @remarks This call will not actually delete the pane being removed; it
 438                  calls OnUnsplit() which can be overridden for the desired
 439                  behaviour. By default, the pane being removed is hidden.
 440
 441         @see SplitHorizontally(), SplitVertically(), IsSplit(), OnUnsplit()
 442     */
 443     bool Unsplit(wxWindow* toRemove = NULL);
 444
 445     /**
 446         Causes any pending sizing of the sash and child panes to take place
 447         immediately.
 448
 449         Such resizing normally takes place in idle time, in order to wait for
 450         layout to be completed. However, this can cause unacceptable flicker as
 451         the panes are resized after the window has been shown.
 452         To work around this, you can perform window layout (for example by
 453         sending a size event to the parent window), and then call this function,
 454         before showing the top-level window.
 455     */
 456     void UpdateSize();
 457 };
 458
 459
 460
 461 /**
 462     @class wxSplitterEvent
 463
 464     This class represents the events generated by a splitter control.
 465
 466     Also there is only one event class, the data associated to the different events
 467     is not the same and so not all accessor functions may be called for each event.
 468     The documentation mentions the kind of event(s) for which the given accessor
 469     function makes sense: calling it for other types of events will result
 470     in assert failure (in debug mode) and will return meaningless results.
 471
 472     @beginEventTable{wxSplitterEvent}
 473     @event{EVT_SPLITTER_SASH_POS_CHANGING(id, func)}
 474         The sash position is in the process of being changed.
 475         May be used to modify the position of the tracking bar to properly
 476         reflect the position that would be set if the drag were to be completed
 477         at this point. Processes a @c wxEVT_SPLITTER_SASH_POS_CHANGING event.
 478     @event{EVT_SPLITTER_SASH_POS_CHANGED(id, func)}
 479         The sash position was changed. May be used to modify the sash position
 480         before it is set, or to prevent the change from taking place.
 481         Processes a @c wxEVT_SPLITTER_SASH_POS_CHANGED event.
 482     @event{EVT_SPLITTER_UNSPLIT(id, func)}
 483         The splitter has been just unsplit. Processes a @c wxEVT_SPLITTER_UNSPLIT event.
 484     @event{EVT_SPLITTER_DCLICK(id, func)}
 485         The sash was double clicked. The default behaviour is to unsplit the
 486         window when this happens (unless the minimum pane size has been set
 487         to a value greater than zero). Processes a @c wxEVT_SPLITTER_DOUBLECLICKED event.
 488     @endEventTable
 489
 490     @library{wxcore}
 491     @category{events}
 492
 493     @see wxSplitterWindow, @ref overview_events
 494 */
 495 class wxSplitterEvent : public wxNotifyEvent
 496 {
 497 public:
 498     /**
 499         Constructor. Used internally by wxWidgets only.
 500     */
 501     wxSplitterEvent(wxEventType eventType = wxEVT_NULL,
 502                     wxSplitterWindow* splitter = NULL);
 503
 504     /**
 505         Returns the new sash position.
 506
 507         May only be called while processing
 508         @c wxEVT_SPLITTER_SASH_POS_CHANGING and
 509         @c wxEVT_SPLITTER_SASH_POS_CHANGED events.
 510     */
 511     int GetSashPosition() const;
 512
 513     /**
 514         Returns a pointer to the window being removed when a splitter window
 515         is unsplit.
 516
 517         May only be called while processing
 518         @c wxEVT_SPLITTER_UNSPLIT events.
 519     */
 520     wxWindow* GetWindowBeingRemoved() const;
 521
 522     /**
 523         Returns the x coordinate of the double-click point.
 524
 525         May only be called while processing
 526         @c wxEVT_SPLITTER_DOUBLECLICKED events.
 527     */
 528     int GetX() const;
 529
 530     /**
 531         Returns the y coordinate of the double-click point.
 532
 533         May only be called while processing
 534         @c wxEVT_SPLITTER_DOUBLECLICKED events.
 535     */
 536     int GetY() const;
 537
 538     /**
 539         In the case of @c wxEVT_SPLITTER_SASH_POS_CHANGED events,
 540         sets the new sash position.
 541         In the case of @c wxEVT_SPLITTER_SASH_POS_CHANGING events,
 542         sets the new tracking bar position so visual feedback during dragging will
 543         represent that change that will actually take place. Set to -1 from
 544         the event handler code to prevent repositioning.
 545
 546         May only be called while processing
 547         @c wxEVT_SPLITTER_SASH_POS_CHANGING and
 548         @c wxEVT_SPLITTER_SASH_POS_CHANGED events.
 549
 550         @param pos
 551             New sash position.
 552     */
 553     void SetSashPosition(int pos);
 554 };
 555
 556
 557 wxEventType wxEVT_SPLITTER_SASH_POS_CHANGED;
 558 wxEventType wxEVT_SPLITTER_SASH_POS_CHANGING;
 559 wxEventType wxEVT_SPLITTER_DOUBLECLICKED;
 560 wxEventType wxEVT_SPLITTER_UNSPLIT;