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