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.", "");
 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.",
 182         "
 183     :param window1:       The left pane.
 184     :param window2:       The right pane.
 185     :param sashPosition:  The initial position of the sash. If this
 186                   value is positive, it specifies the size of the left
 187                   pane. If it is negative, it is absolute value gives
 188                   the size of the right pane. Finally, specify 0
 189                   (default) to choose the default position (half of
 190                   the total window width).
 191
 192 Returns True if successful, False otherwise (the window was already
 193 split).
 194
 195 SplitVertically should be called if you wish to initially view two
 196 panes. It can also be called at any subsequent time, but the
 197 application should check that the window is not currently split using
 198 IsSplit.
 199 ");
 200
 201
 202     DocDeclStr(
 203         virtual bool , SplitHorizontally(wxWindow *window1,
 204                                          wxWindow *window2,
 205                                          int sashPosition = 0),
 206         "Initializes the top and bottom panes of the splitter window.",
 207         "
 208     :param window1:       The top pane.
 209     :param window2:       The bottom pane.
 210     :param sashPosition:  The initial position of the sash. If this
 211                   value is positive, it specifies the size of the
 212                   upper pane. If it is negative, it is absolute value
 213                   gives the size of the lower pane. Finally, specify 0
 214                   (default) to choose the default position (half of
 215                   the total window height).
 216
 217 Returns True if successful, False otherwise (the window was already
 218 split).
 219
 220 SplitHorizontally should be called if you wish to initially view two
 221 panes. It can also be called at any subsequent time, but the
 222 application should check that the window is not currently split using
 223 IsSplit.
 224 ");
 225
 226
 227
 228     DocDeclStr(
 229         bool , Unsplit(wxWindow *toRemove = NULL),
 230         "Unsplits the window.  Pass the pane to remove, or None to remove the
 231 right or bottom pane.  Returns True if successful, False otherwise (the
 232 window was not split).
 233
 234 This function will not actually delete the pane being
 235 removed; it sends EVT_SPLITTER_UNSPLIT which can be handled
 236 for the desired behaviour. By default, the pane being
 237 removed is only hidden.", "");
 238
 239
 240
 241     DocDeclStr(
 242         bool , ReplaceWindow(wxWindow *winOld, wxWindow *winNew),
 243         "This function replaces one of the windows managed by the
 244 SplitterWindow with another one. It is in general better to use it
 245 instead of calling Unsplit() and then resplitting the window back
 246 because it will provoke much less flicker. It is valid to call this
 247 function whether the splitter has two windows or only one.
 248
 249 Both parameters should be non-None and winOld must specify one of the
 250 windows managed by the splitter. If the parameters are incorrect or
 251 the window couldn't be replaced, False is returned. Otherwise the
 252 function will return True, but please notice that it will not Destroy
 253 the replaced window and you may wish to do it yourself.", "");
 254
 255
 256     DocDeclStr(
 257         void , UpdateSize(),
 258         "Causes any pending sizing of the sash and child panes to take place
 259 immediately.
 260
 261 Such resizing normally takes place in idle time, in order to wait for
 262 layout to be completed. However, this can cause unacceptable flicker
 263 as the panes are resized after the window has been shown. To work
 264 around this, you can perform window layout (for example by sending a
 265 size event to the parent window), and then call this function, before
 266 showing the top-level window.", "");
 267
 268
 269
 270     DocDeclStr(
 271         bool , IsSplit() const,
 272         "Is the window split?", "");
 273
 274
 275     DocDeclStr(
 276         void , SetSashSize(int width),
 277         "Sets the sash size.  Currently a NOP.", "");
 278
 279
 280     DocDeclStr(
 281         void , SetBorderSize(int width),
 282         "Sets the border size. Currently a NOP.", "");
 283
 284
 285     DocDeclStr(
 286         int , GetSashSize() const,
 287         "Gets the sash size", "");
 288
 289
 290     DocDeclStr(
 291         int , GetBorderSize() const,
 292         "Gets the border size", "");
 293
 294
 295     DocDeclStr(
 296         void , SetSashPosition(int position, bool redraw = true),
 297         "Sets the sash position, in pixels.  If redraw is Ttrue then the panes
 298 are resized and the sash and border are redrawn.", "");
 299
 300
 301     DocDeclStr(
 302         int , GetSashPosition() const,
 303         "Returns the surrent sash position.", "");
 304
 305
 306     DocDeclStr(
 307         void , SetSashGravity(double gravity),
 308         "Set the sash gravity.  Gravity is a floating-point factor between 0.0
 309 and 1.0 which controls position of sash while resizing the
 310 `wx.SplitterWindow`.  The gravity specifies how much the left/top
 311 window will grow while resizing.","
 312
 313 Example values:
 314
 315     ======= =======================================
 316     0.0      Only the bottom or right window is
 317              automaticaly resized.
 318     0.5      Both windows grow equally.
 319     1.0      Only left/top window grows.
 320
 321 The default value of sash gravity is 0.0. That value is compatible
 322 with the previous (before gravity was introduced) behaviour of the
 323 `wx.SplitterWindow`.");
 324
 325     DocDeclStr(
 326         double , GetSashGravity() const,
 327         "Gets the sash gravity.
 328
 329 :see: `SetSashGravity`
 330 ", "");
 331
 332
 333     DocDeclStr(
 334         void , SetMinimumPaneSize(int min),
 335         "Sets the minimum pane size in pixels.
 336
 337 The default minimum pane size is zero, which means that either pane
 338 can be reduced to zero by dragging the sash, thus removing one of the
 339 panes. To prevent this behaviour (and veto out-of-range sash
 340 dragging), set a minimum size, for example 20 pixels. If the
 341 wx.SP_PERMIT_UNSPLIT style is used when a splitter window is created,
 342 the window may be unsplit even if minimum size is non-zero.", "");
 343
 344     DocDeclStr(
 345         int , GetMinimumPaneSize() const,
 346         "Gets the minimum pane size in pixels.", "");
 347
 348
 349     DocDeclStr(
 350         virtual bool , SashHitTest(int x, int y, int tolerance = 5),
 351         "Tests for x, y over the sash", "");
 352
 353
 354     DocDeclStr(
 355         virtual void , SizeWindows(),
 356         "Resizes subwindows", "");
 357
 358
 359     void SetNeedUpdating(bool needUpdating);
 360     bool GetNeedUpdating() const;
 361
 362     static wxVisualAttributes
 363     GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
 364 };
 365
 366
 367
 368 DocStr(wxSplitterEvent,
 369        "This class represents the events generated by a splitter control.", "");
 370
 371 class wxSplitterEvent : public wxNotifyEvent
 372 {
 373 public:
 374     wxSplitterEvent(wxEventType type = wxEVT_NULL,
 375                     wxSplitterWindow *splitter = (wxSplitterWindow *)NULL);
 376
 377
 378     DocDeclStr(
 379         void , SetSashPosition(int pos),
 380         "This funciton is only meaningful during EVT_SPLITTER_SASH_POS_CHANGING
 381 and EVT_SPLITTER_SASH_POS_CHANGED events.  In the case of _CHANGED
 382 events, sets the the new sash position. In the case of _CHANGING
 383 events, sets the new tracking bar position so visual feedback during
 384 dragging will represent that change that will actually take place. Set
 385 to -1 from the event handler code to prevent repositioning.", "");
 386
 387     DocDeclStr(
 388         int , GetSashPosition() const,
 389         "Returns the new sash position while in EVT_SPLITTER_SASH_POS_CHANGING
 390 and EVT_SPLITTER_SASH_POS_CHANGED events.", "");
 391
 392
 393     DocDeclStr(
 394         wxWindow *, GetWindowBeingRemoved() const,
 395         "Returns a pointer to the window being removed when a splitter window
 396 is unsplit.", "");
 397
 398
 399     DocDeclStr(
 400         int , GetX() const,
 401         "Returns the x coordinate of the double-click point in a
 402 EVT_SPLITTER_DCLICK event.", "");
 403
 404     DocDeclStr(
 405         int , GetY() const,
 406         "Returns the y coordinate of the double-click point in a
 407 EVT_SPLITTER_DCLICK event.", "");
 408
 409 };
 410
 411
 412
 413 %constant wxEventType wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED;
 414 %constant wxEventType wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING;
 415 %constant wxEventType wxEVT_COMMAND_SPLITTER_DOUBLECLICKED;
 416 %constant wxEventType wxEVT_COMMAND_SPLITTER_UNSPLIT;
 417
 418
 419 %pythoncode {
 420 EVT_SPLITTER_SASH_POS_CHANGED = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED, 1 )
 421 EVT_SPLITTER_SASH_POS_CHANGING = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING, 1 )
 422 EVT_SPLITTER_DOUBLECLICKED = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_DOUBLECLICKED, 1 )
 423 EVT_SPLITTER_UNSPLIT = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_UNSPLIT, 1 )
 424 EVT_SPLITTER_DCLICK = EVT_SPLITTER_DOUBLECLICKED
 425 }
 426
 427 //---------------------------------------------------------------------------
 428