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