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