wxPython/src/_splitter.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _splitter.i
   3 // Purpose:     SWIG interface defs for wxSplitterWindow
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     2-June-1998
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2003 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 // Not a %module
  14
  15
  16 //---------------------------------------------------------------------------
  17
  18 MAKE_CONST_WXSTRING2(SplitterNameStr, wxT("splitter"));
  19
  20 //---------------------------------------------------------------------------
  21 %newgroup
  22
  23 enum {
  24     wxSP_NOBORDER,
  25     wxSP_NOSASH,
  26     wxSP_PERMIT_UNSPLIT,
  27     wxSP_LIVE_UPDATE,
  28     wxSP_3DSASH,
  29     wxSP_3DBORDER,
  30     wxSP_NO_XP_THEME,
  31     wxSP_BORDER,
  32     wxSP_3D,
  33 };
  34
  35
  36 enum wxSplitMode
  37 {
  38     wxSPLIT_HORIZONTAL = 1,
  39     wxSPLIT_VERTICAL
  40 };
  41
  42 enum
  43 {
  44     wxSPLIT_DRAG_NONE,
  45     wxSPLIT_DRAG_DRAGGING,
  46     wxSPLIT_DRAG_LEFT_DOWN
  47 };
  48
  49 //---------------------------------------------------------------------------
  50
  51 DocStr(wxSplitterWindow,
  52 "wx.SplitterWindow manages up to two subwindows or panes, with an
  53 optional vertical or horizontal split which can be used with the mouse
  54 or programmatically.", "
  55
  56 Styles
  57 -------
  58     ====================   ======================================
  59     wx.SP_3D               Draws a 3D effect border and sash.
  60     wx.SP_3DSASH           Draws a 3D effect sash.
  61     wx.SP_3DBORDER         Synonym for wxSP_BORDER.
  62     wx.SP_BORDER           Draws a standard border.
  63     wx.SP_NOBORDER         No border (default).
  64     wx.SP_NO_XP_THEME      Under Windows XP, switches off the
  65                            attempt to draw the splitter
  66                            using Windows XP theming, so the
  67                            borders and sash will take on the
  68                            pre-XP look.
  69     wx.SP_PERMIT_UNSPLIT   Always allow to unsplit, even with
  70                            the minimum pane size other than zero.
  71     wx.SP_LIVE_UPDATE      Don't draw XOR line but resize the
  72                            child windows immediately.
  73     ====================   ======================================
  74
  75 Events
  76 ------
  77     ==============================  =======================================
  78     EVT_SPLITTER_SASH_POS_CHANGING  The sash position is in the
  79                                     process of being changed. May be
  80                                     used to modify the position of
  81                                     the tracking bar to properly
  82                                     reflect the position that would
  83                                     be set if the drag were to be
  84                                     completed at this point.
  85
  86     EVT_SPLITTER_SASH_POS_CHANGED
  87                                     The sash position was
  88                                     changed. May be used to modify
  89                                     the sash position before it is
  90                                     set, or to prevent the change
  91                                     from taking place.
  92
  93     EVT_SPLITTER_UNSPLIT            The splitter has been just unsplit.
  94
  95     EVT_SPLITTER_DCLICK             The sash was double clicked. The
  96                                     default behaviour is to unsplit
  97                                     the window when this happens
  98                                     (unless the minimum pane size has
  99                                     been set to a value greater than
 100                                     zero.)
 101     ==============================  =======================================
 102
 103 ");
 104
 105
 106
 107 MustHaveApp(wxSplitterWindow);
 108
 109 class wxSplitterWindow: public wxWindow
 110 {
 111 public:
 112     %pythonPrepend wxSplitterWindow         "if kwargs.has_key('point'): kwargs['pos'] = kwargs['point'];del kwargs['point']"
 113     %pythonPrepend wxSplitterWindow()       ""
 114     %pythonAppend  wxSplitterWindow         "self._setOORInfo(self)"
 115     %pythonAppend  wxSplitterWindow()       ""
 116
 117     DocCtorStr(
 118         wxSplitterWindow(wxWindow* parent, wxWindowID id=-1,
 119                          const wxPoint& pos = wxDefaultPosition,
 120                          const wxSize& size = wxDefaultSize,
 121                          long style=wxSP_3D,
 122                          const wxString& name = wxPySplitterNameStr),
 123         "Constructor.  Creates and shows a SplitterWindow.", "");
 124
 125     DocCtorStrName(
 126         wxSplitterWindow(),
 127         "Precreate a SplitterWindow for 2-phase creation.", "",
 128         PreSplitterWindow);
 129
 130
 131     DocDeclStr(
 132         bool , Create(wxWindow* parent, wxWindowID id=-1,
 133                       const wxPoint& pos = wxDefaultPosition,
 134                       const wxSize& size = wxDefaultSize,
 135                       long style=wxSP_3D,
 136                       const wxString& name = wxPySplitterNameStr),
 137         "Create the GUI part of the SplitterWindow for the 2-phase create.", "");
 138
 139
 140
 141     DocDeclStr(
 142         wxWindow *, GetWindow1() const,
 143         "Gets the only or left/top pane.", "");
 144
 145
 146     DocDeclStr(
 147         wxWindow *, GetWindow2() const,
 148         "Gets the right/bottom pane.", "");
 149
 150
 151     DocDeclStr(
 152         void , SetSplitMode(int mode),
 153         "Sets the split mode.  The mode can be wx.SPLIT_VERTICAL or
 154 wx.SPLIT_HORIZONTAL.  This only sets the internal variable; does not
 155 update the display.", "");
 156
 157
 158     DocDeclStr(
 159         wxSplitMode , GetSplitMode() const,
 160         "Gets the split mode", "");
 161
 162
 163     DocDeclStr(
 164         void , Initialize(wxWindow *window),
 165         "Initializes the splitter window to have one pane.  This should be
 166 called if you wish to initially view only a single pane in the
 167 splitter window.  The child window is shown if it is currently hidden.", "");
 168
 169
 170     // Associates the given window with window 2, drawing the appropriate sash
 171     // and changing the split mode.
 172     // Does nothing and returns False if the window is already split.
 173     // A sashPosition of 0 means choose a default sash position,
 174     // negative sashPosition specifies the size of right/lower pane as it's
 175     // absolute value rather than the size of left/upper pane.
 176
 177     DocDeclStr(
 178         virtual bool , SplitVertically(wxWindow *window1,
 179                                        wxWindow *window2,
 180                                        int sashPosition = 0),
 181         "Initializes the left and right panes of the splitter window.  The
 182 child windows are shown if they are currently hidden.","
 183
 184     :param window1:       The left pane.
 185     :param window2:       The right pane.
 186     :param sashPosition:  The initial position of the sash. If this
 187                   value is positive, it specifies the size of the left
 188                   pane. If it is negative, its absolute value gives
 189                   the size of the right pane. Finally, specify 0
 190                   (default) to choose the default position (half of
 191                   the total window width).
 192
 193 Returns True if successful, False otherwise (the window was already
 194 split).
 195
 196 SplitVertically should be called if you wish to initially view two
 197 panes. It can also be called at any subsequent time, but the
 198 application should check that the window is not currently split using
 199 `IsSplit`.
 200 ");
 201
 202
 203     DocDeclStr(
 204         virtual bool , SplitHorizontally(wxWindow *window1,
 205                                          wxWindow *window2,
 206                                          int sashPosition = 0),
 207         "Initializes the top and bottom panes of the splitter window.  The
 208 child windows are shown if they are currently hidden.","
 209
 210     :param window1:       The top pane.
 211     :param window2:       The bottom pane.
 212     :param sashPosition:  The initial position of the sash. If this
 213                   value is positive, it specifies the size of the
 214                   upper pane. If it is negative, its absolute value
 215                   gives the size of the lower pane. Finally, specify 0
 216                   (default) to choose the default position (half of
 217                   the total window height).
 218
 219 Returns True if successful, False otherwise (the window was already
 220 split).
 221
 222 SplitHorizontally should be called if you wish to initially view two
 223 panes. It can also be called at any subsequent time, but the
 224 application should check that the window is not currently split using
 225 `IsSplit`.
 226 ");
 227
 228
 229
 230     DocDeclStr(
 231         bool , Unsplit(wxWindow *toRemove = NULL),
 232         "Unsplits the window.  Pass the pane to remove, or None to remove the
 233 right or bottom pane.  Returns True if successful, False otherwise (the
 234 window was not split).
 235
 236 This function will not actually delete the pane being
 237 removed; it sends EVT_SPLITTER_UNSPLIT which can be handled
 238 for the desired behaviour. By default, the pane being
 239 removed is only hidden.", "");
 240
 241
 242
 243     DocDeclStr(
 244         bool , ReplaceWindow(wxWindow *winOld, wxWindow *winNew),
 245         "This function replaces one of the windows managed by the
 246 SplitterWindow with another one. It is in general better to use it
 247 instead of calling Unsplit() and then resplitting the window back
 248 because it will provoke much less flicker. It is valid to call this
 249 function whether the splitter has two windows or only one.
 250
 251 Both parameters should be non-None and winOld must specify one of the
 252 windows managed by the splitter. If the parameters are incorrect or
 253 the window couldn't be replaced, False is returned. Otherwise the
 254 function will return True, but please notice that it will not Destroy
 255 the replaced window and you may wish to do it yourself.", "");
 256
 257
 258     DocDeclStr(
 259         void , UpdateSize(),
 260         "Causes any pending sizing of the sash and child panes to take place
 261 immediately.
 262
 263 Such resizing normally takes place in idle time, in order to wait for
 264 layout to be completed. However, this can cause unacceptable flicker
 265 as the panes are resized after the window has been shown. To work
 266 around this, you can perform window layout (for example by sending a
 267 size event to the parent window), and then call this function, before
 268 showing the top-level window.", "");
 269
 270
 271
 272     DocDeclStr(
 273         bool , IsSplit() const,
 274         "Is the window split?", "");
 275
 276
 277     DocDeclStr(
 278         void , SetSashSize(int width),
 279         "Sets the sash size.", "");
 280
 281
 282     DocDeclStr(
 283         void , SetBorderSize(int width),
 284         "Sets the border size. Currently a NOP.", "");
 285
 286
 287     DocDeclStr(
 288         int , GetSashSize() const,
 289         "Gets the sash size", "");
 290
 291
 292     DocDeclStr(
 293         int , GetBorderSize() const,
 294         "Gets the border size", "");
 295
 296
 297     DocDeclStr(
 298         void , SetSashPosition(int position, bool redraw = true),
 299         "Sets the sash position, in pixels.  If redraw is Ttrue then the panes
 300 are resized and the sash and border are redrawn.", "");
 301
 302
 303     DocDeclStr(
 304         int , GetSashPosition() const,
 305         "Returns the surrent sash position.", "");
 306
 307
 308     DocDeclStr(
 309         void , SetSashGravity(double gravity),
 310         "Set the sash gravity.  Gravity is a floating-point factor between 0.0
 311 and 1.0 which controls position of sash while resizing the
 312 `wx.SplitterWindow`.  The gravity specifies how much the left/top
 313 window will grow while resizing.","
 314
 315 Example values:
 316
 317     ======= =======================================
 318     0.0      Only the bottom or right window is
 319              automaticaly resized.
 320     0.5      Both windows grow equally.
 321     1.0      Only left/top window grows.
 322     ======= =======================================
 323
 324 The default value of sash gravity is 0.0. That value is compatible
 325 with the previous (before gravity was introduced) behaviour of the
 326 `wx.SplitterWindow`.");
 327
 328     DocDeclStr(
 329         double , GetSashGravity() const,
 330         "Gets the sash gravity.
 331
 332 :see: `SetSashGravity`
 333 ", "");
 334
 335
 336     DocDeclStr(
 337         void , SetMinimumPaneSize(int min),
 338         "Sets the minimum pane size in pixels.
 339
 340 The default minimum pane size is zero, which means that either pane
 341 can be reduced to zero by dragging the sash, thus removing one of the
 342 panes. To prevent this behaviour (and veto out-of-range sash
 343 dragging), set a minimum size, for example 20 pixels. If the
 344 wx.SP_PERMIT_UNSPLIT style is used when a splitter window is created,
 345 the window may be unsplit even if minimum size is non-zero.", "");
 346
 347     DocDeclStr(
 348         int , GetMinimumPaneSize() const,
 349         "Gets the minimum pane size in pixels.", "");
 350
 351
 352     DocDeclStr(
 353         virtual bool , SashHitTest(int x, int y, int tolerance = 5),
 354         "Tests for x, y over the sash", "");
 355
 356
 357     DocDeclStr(
 358         virtual void , SizeWindows(),
 359         "Resizes subwindows", "");
 360
 361
 362     void SetNeedUpdating(bool needUpdating);
 363     bool GetNeedUpdating() const;
 364
 365     static wxVisualAttributes
 366     GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
 367
 368     %property(BorderSize, GetBorderSize, SetBorderSize, doc="See `GetBorderSize` and `SetBorderSize`");
 369     %property(MinimumPaneSize, GetMinimumPaneSize, SetMinimumPaneSize, doc="See `GetMinimumPaneSize` and `SetMinimumPaneSize`");
 370     %property(NeedUpdating, GetNeedUpdating, SetNeedUpdating, doc="See `GetNeedUpdating` and `SetNeedUpdating`");
 371     %property(SashGravity, GetSashGravity, SetSashGravity, doc="See `GetSashGravity` and `SetSashGravity`");
 372     %property(SashPosition, GetSashPosition, SetSashPosition, doc="See `GetSashPosition` and `SetSashPosition`");
 373     %property(SashSize, GetSashSize, SetSashSize, doc="See `GetSashSize` and `SetSashSize`");
 374     %property(SplitMode, GetSplitMode, SetSplitMode, doc="See `GetSplitMode` and `SetSplitMode`");
 375     %property(Window1, GetWindow1, doc="See `GetWindow1`");
 376     %property(Window2, GetWindow2, doc="See `GetWindow2`");
 377 };
 378
 379
 380
 381
 382
 383 DocStr(wxSplitterEvent,
 384        "This class represents the events generated by a splitter control.", "");
 385
 386 class wxSplitterEvent : public wxNotifyEvent
 387 {
 388 public:
 389     wxSplitterEvent(wxEventType type = wxEVT_NULL,
 390                     wxSplitterWindow *splitter = (wxSplitterWindow *)NULL);
 391
 392
 393     DocDeclStr(
 394         void , SetSashPosition(int pos),
 395         "This function is only meaningful during EVT_SPLITTER_SASH_POS_CHANGING
 396 and EVT_SPLITTER_SASH_POS_CHANGED events.  In the case of _CHANGED
 397 events, sets the the new sash position. In the case of _CHANGING
 398 events, sets the new tracking bar position so visual feedback during
 399 dragging will represent that change that will actually take place. Set
 400 to -1 from the event handler code to prevent repositioning.", "");
 401
 402     DocDeclStr(
 403         int , GetSashPosition() const,
 404         "Returns the new sash position while in EVT_SPLITTER_SASH_POS_CHANGING
 405 and EVT_SPLITTER_SASH_POS_CHANGED events.", "");
 406
 407
 408     DocDeclStr(
 409         wxWindow *, GetWindowBeingRemoved() const,
 410         "Returns a pointer to the window being removed when a splitter window
 411 is unsplit.", "");
 412
 413
 414     DocDeclStr(
 415         int , GetX() const,
 416         "Returns the x coordinate of the double-click point in a
 417 EVT_SPLITTER_DCLICK event.", "");
 418
 419     DocDeclStr(
 420         int , GetY() const,
 421         "Returns the y coordinate of the double-click point in a
 422 EVT_SPLITTER_DCLICK event.", "");
 423
 424     %property(SashPosition, GetSashPosition, SetSashPosition, doc="See `GetSashPosition` and `SetSashPosition`");
 425     %property(WindowBeingRemoved, GetWindowBeingRemoved, doc="See `GetWindowBeingRemoved`");
 426     %property(X, GetX, doc="See `GetX`");
 427     %property(Y, GetY, doc="See `GetY`");
 428 };
 429
 430
 431
 432 %constant wxEventType wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED;
 433 %constant wxEventType wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING;
 434 %constant wxEventType wxEVT_COMMAND_SPLITTER_DOUBLECLICKED;
 435 %constant wxEventType wxEVT_COMMAND_SPLITTER_UNSPLIT;
 436
 437
 438 %pythoncode {
 439 EVT_SPLITTER_SASH_POS_CHANGED = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED, 1 )
 440 EVT_SPLITTER_SASH_POS_CHANGING = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING, 1 )
 441 EVT_SPLITTER_DOUBLECLICKED = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_DOUBLECLICKED, 1 )
 442 EVT_SPLITTER_UNSPLIT = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_UNSPLIT, 1 )
 443 EVT_SPLITTER_DCLICK = EVT_SPLITTER_DOUBLECLICKED
 444 }
 445
 446 //---------------------------------------------------------------------------
 447