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