interface/splitter.h

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