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