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