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_COMMAND_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_COMMAND_SPLITTER_SASH_POS_CHANGED event.
  76     @event{EVT_SPLITTER_UNSPLIT(id, func)}
  77         The splitter has been just unsplit. Processes a @c wxEVT_COMMAND_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_COMMAND_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 sash size in pixels.
 167
 168         The size of the sash is its width for a vertically split window and its
 169         height for a horizontally split one. Its other direction is the same as
 170         the client size of the window in the corresponding direction.
 171
 172         The sash size is platform-dependent because it conforms to the current
 173         platform look-and-feel and cannot be changed.
 174      */
 175     int GetSashSize() const;
 176
 177     /**
 178         Gets the split mode.
 179
 180         @see SetSplitMode(), SplitVertically(), SplitHorizontally().
 181     */
 182     wxSplitMode GetSplitMode() const;
 183
 184     /**
 185         Returns the left/top or only pane.
 186     */
 187     wxWindow* GetWindow1() const;
 188
 189     /**
 190         Returns the right/bottom pane.
 191     */
 192     wxWindow* GetWindow2() const;
 193
 194     /**
 195         Initializes the splitter window to have one pane.
 196         The child window is shown if it is currently hidden.
 197
 198         @param window
 199             The pane for the unsplit window.
 200
 201         @remarks This should be called if you wish to initially view only a
 202                  single pane in the splitter window.
 203
 204         @see SplitVertically(), SplitHorizontally()
 205     */
 206     void Initialize(wxWindow* window);
 207
 208     /**
 209         Returns @true if the window is split, @false otherwise.
 210     */
 211     bool IsSplit() const;
 212
 213     /**
 214         Application-overridable function called when the sash is double-clicked with
 215         the left mouse button.
 216
 217         @param x
 218             The x position of the mouse cursor.
 219         @param y
 220             The y position of the mouse cursor.
 221
 222         @remarks The default implementation of this function calls Unsplit if the
 223                  minimum pane size is zero.
 224
 225         @see Unsplit()
 226     */
 227     virtual void OnDoubleClickSash(int x, int y);
 228
 229     /**
 230         Application-overridable function called when the sash position is changed by
 231         user. It may return @false to prevent the change or @true to allow it.
 232
 233         @param newSashPosition
 234             The new sash position (always positive or zero)
 235
 236         @remarks The default implementation of this function verifies that the
 237                  sizes of both  panes of the splitter are greater than
 238                  minimum pane size.
 239     */
 240     virtual bool OnSashPositionChange(int newSashPosition);
 241
 242     /**
 243         Application-overridable function called when the window is unsplit, either
 244         programmatically or using the wxSplitterWindow user interface.
 245
 246         @param removed
 247             The window being removed.
 248
 249         @remarks The default implementation of this function simply hides
 250                  removed. You may wish to delete the window.
 251     */
 252     virtual void OnUnsplit(wxWindow* removed);
 253
 254     /**
 255         This function replaces one of the windows managed by the wxSplitterWindow with
 256         another one. It is in general better to use it instead of calling Unsplit()
 257         and then resplitting the window back because it will provoke much less flicker
 258         (if any). It is valid to call this function whether the splitter has two
 259         windows or only one.
 260
 261         Both parameters should be non-@NULL and @a winOld must specify one of the
 262         windows managed by the splitter. If the parameters are incorrect or the window
 263         couldn't be replaced, @false is returned. Otherwise the function will return
 264         @true, but please notice that it will not delete the replaced window and you
 265         may wish to do it yourself.
 266
 267         @see GetMinimumPaneSize()
 268     */
 269     bool ReplaceWindow(wxWindow* winOld, wxWindow* winNew);
 270
 271     /**
 272         Sets the minimum pane size.
 273
 274         @param paneSize
 275             Minimum pane size in pixels.
 276
 277         @remarks The default minimum pane size is zero, which means that either
 278                  pane can be reduced to zero by dragging the sash, thus
 279                  removing one of the panes. To prevent this behaviour
 280                  (and veto out-of-range sash dragging), set a minimum
 281                  size, for example 20 pixels. If the wxSP_PERMIT_UNSPLIT
 282                  style is used when a splitter window is created, the
 283                  window may be unsplit even if minimum size is non-zero.
 284
 285         @see GetMinimumPaneSize()
 286     */
 287     void SetMinimumPaneSize(int paneSize);
 288
 289     /**
 290         Sets the sash gravity.
 291
 292         @param gravity
 293             The sash gravity. Value between 0.0 and 1.0.
 294
 295         @remarks
 296         Gravity is real factor which controls position of sash while resizing
 297         wxSplitterWindow. Gravity tells wxSplitterWindow how much will left/top
 298         window grow while resizing.
 299         Example values:
 300         - 0.0: only the bottom/right window is automatically resized
 301         - 0.5: both windows grow by equal size
 302         - 1.0: only left/top window grows
 303         Gravity should be a real value between 0.0 and 1.0.
 304         Default value of sash gravity is 0.0.
 305         That value is compatible with previous (before gravity was introduced)
 306         behaviour of wxSplitterWindow.
 307
 308         @see GetSashGravity()
 309     */
 310     void SetSashGravity(double gravity);
 311
 312     /**
 313         Sets the sash position.
 314
 315         @param position
 316             The sash position in pixels.
 317         @param redraw
 318             If @true, resizes the panes and redraws the sash and border.
 319
 320         @remarks Does not currently check for an out-of-range value.
 321
 322         @see GetSashPosition()
 323     */
 324     void SetSashPosition(int position, bool redraw = true);
 325
 326     /**
 327         Sets the split mode.
 328
 329         @param mode
 330             Can be wxSPLIT_VERTICAL or wxSPLIT_HORIZONTAL.
 331
 332         @remarks Only sets the internal variable; does not update the display.
 333
 334         @see GetSplitMode(), SplitVertically(), SplitHorizontally().
 335     */
 336     void SetSplitMode(int mode);
 337
 338     /**
 339         Initializes the top and bottom panes of the splitter window.
 340         The child windows are shown if they are currently hidden.
 341
 342         @param window1
 343             The top pane.
 344         @param window2
 345             The bottom pane.
 346         @param sashPosition
 347             The initial position of the sash. If this value is positive,
 348             it specifies the size of the upper pane. If it is negative, its
 349             absolute value gives the size of the lower pane.
 350             Finally, specify 0 (default) to choose the default position
 351             (half of the total window height).
 352
 353         @return @true if successful, @false otherwise (the window was already split).
 354
 355         @remarks This should be called if you wish to initially view two panes.
 356                  It can also be called at any subsequent time, but the application
 357                  should check that the window is not currently split using IsSplit().
 358
 359         @see SplitVertically(), IsSplit(), Unsplit()
 360     */
 361     virtual bool SplitHorizontally(wxWindow* window1, wxWindow* window2,
 362                                    int sashPosition = 0);
 363
 364     /**
 365         Initializes the left and right panes of the splitter window.
 366         The child windows are shown if they are currently hidden.
 367
 368         @param window1
 369             The left pane.
 370         @param window2
 371             The right pane.
 372         @param sashPosition
 373             The initial position of the sash. If this value is positive, it
 374             specifies the size of the left pane. If it is negative, it is
 375             absolute value gives the size of the right pane.
 376             Finally, specify 0 (default) to choose the default position
 377             (half of the total window width).
 378
 379         @return @true if successful, @false otherwise (the window was already split).
 380
 381         @remarks This should be called if you wish to initially view two panes.
 382                  It can also be called at any subsequent time, but the
 383                  application should check that the window is not currently
 384                  split using IsSplit().
 385
 386         @see SplitHorizontally(), IsSplit(), Unsplit().
 387     */
 388     virtual bool SplitVertically(wxWindow* window1, wxWindow* window2,
 389                                  int sashPosition = 0);
 390
 391     /**
 392         Unsplits the window.
 393
 394         @param toRemove
 395             The pane to remove, or @NULL to remove the right or bottom pane.
 396
 397         @return @true if successful, @false otherwise (the window was not split).
 398
 399         @remarks This call will not actually delete the pane being removed; it
 400                  calls OnUnsplit() which can be overridden for the desired
 401                  behaviour. By default, the pane being removed is hidden.
 402
 403         @see SplitHorizontally(), SplitVertically(), IsSplit(), OnUnsplit()
 404     */
 405     bool Unsplit(wxWindow* toRemove = NULL);
 406
 407     /**
 408         Causes any pending sizing of the sash and child panes to take place
 409         immediately.
 410
 411         Such resizing normally takes place in idle time, in order to wait for
 412         layout to be completed. However, this can cause unacceptable flicker as
 413         the panes are resized after the window has been shown.
 414         To work around this, you can perform window layout (for example by
 415         sending a size event to the parent window), and then call this function,
 416         before showing the top-level window.
 417     */
 418     void UpdateSize();
 419 };
 420
 421
 422
 423 /**
 424     @class wxSplitterEvent
 425
 426     This class represents the events generated by a splitter control.
 427
 428     Also there is only one event class, the data associated to the different events
 429     is not the same and so not all accessor functions may be called for each event.
 430     The documentation mentions the kind of event(s) for which the given accessor
 431     function makes sense: calling it for other types of events will result
 432     in assert failure (in debug mode) and will return meaningless results.
 433
 434     @beginEventTable{wxSplitterEvent}
 435     @event{EVT_SPLITTER_SASH_POS_CHANGING(id, func)}
 436         The sash position is in the process of being changed.
 437         May be used to modify the position of the tracking bar to properly
 438         reflect the position that would be set if the drag were to be completed
 439         at this point. Processes a @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING event.
 440     @event{EVT_SPLITTER_SASH_POS_CHANGED(id, func)}
 441         The sash position was changed. May be used to modify the sash position
 442         before it is set, or to prevent the change from taking place.
 443         Processes a @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED event.
 444     @event{EVT_SPLITTER_UNSPLIT(id, func)}
 445         The splitter has been just unsplit. Processes a @c wxEVT_COMMAND_SPLITTER_UNSPLIT event.
 446     @event{EVT_SPLITTER_DCLICK(id, func)}
 447         The sash was double clicked. The default behaviour is to unsplit the
 448         window when this happens (unless the minimum pane size has been set
 449         to a value greater than zero). Processes a @c wxEVT_COMMAND_SPLITTER_DOUBLECLICKED event.
 450     @endEventTable
 451
 452     @library{wxcore}
 453     @category{events}
 454
 455     @see wxSplitterWindow, @ref overview_events
 456 */
 457 class wxSplitterEvent : public wxNotifyEvent
 458 {
 459 public:
 460     /**
 461         Constructor. Used internally by wxWidgets only.
 462     */
 463     wxSplitterEvent(wxEventType eventType = wxEVT_NULL,
 464                     wxSplitterWindow* splitter = NULL);
 465
 466     /**
 467         Returns the new sash position.
 468
 469         May only be called while processing
 470         @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and
 471         @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events.
 472     */
 473     int GetSashPosition() const;
 474
 475     /**
 476         Returns a pointer to the window being removed when a splitter window
 477         is unsplit.
 478
 479         May only be called while processing
 480         @c wxEVT_COMMAND_SPLITTER_UNSPLIT events.
 481     */
 482     wxWindow* GetWindowBeingRemoved() const;
 483
 484     /**
 485         Returns the x coordinate of the double-click point.
 486
 487         May only be called while processing
 488         @c wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events.
 489     */
 490     int GetX() const;
 491
 492     /**
 493         Returns the y coordinate of the double-click point.
 494
 495         May only be called while processing
 496         @c wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events.
 497     */
 498     int GetY() const;
 499
 500     /**
 501         In the case of @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events,
 502         sets the new sash position.
 503         In the case of @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING events,
 504         sets the new tracking bar position so visual feedback during dragging will
 505         represent that change that will actually take place. Set to -1 from
 506         the event handler code to prevent repositioning.
 507
 508         May only be called while processing
 509         @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and
 510         @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events.
 511
 512         @param pos
 513             New sash position.
 514     */
 515     void SetSashPosition(int pos);
 516 };
 517
 518
 519 wxEventType wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED;
 520 wxEventType wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING;
 521 wxEventType wxEVT_COMMAND_SPLITTER_DOUBLECLICKED;
 522 wxEventType wxEVT_COMMAND_SPLITTER_UNSPLIT;