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