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