interface/wx/splitter.h

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