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, it is 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, it is 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.  Currently a NOP.", "");
 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 The default value of sash gravity is 0.0. That value is compatible
 324 with the previous (before gravity was introduced) behaviour of the
 325 `wx.SplitterWindow`.");
 326
 327     DocDeclStr(
 328         double , GetSashGravity() const,
 329         "Gets the sash gravity.
 330
 331 :see: `SetSashGravity`
 332 ", "");
 333
 334
 335     DocDeclStr(
 336         void , SetMinimumPaneSize(int min),
 337         "Sets the minimum pane size in pixels.
 338
 339 The default minimum pane size is zero, which means that either pane
 340 can be reduced to zero by dragging the sash, thus removing one of the
 341 panes. To prevent this behaviour (and veto out-of-range sash
 342 dragging), set a minimum size, for example 20 pixels. If the
 343 wx.SP_PERMIT_UNSPLIT style is used when a splitter window is created,
 344 the window may be unsplit even if minimum size is non-zero.", "");
 345
 346     DocDeclStr(
 347         int , GetMinimumPaneSize() const,
 348         "Gets the minimum pane size in pixels.", "");
 349
 350
 351     DocDeclStr(
 352         virtual bool , SashHitTest(int x, int y, int tolerance = 5),
 353         "Tests for x, y over the sash", "");
 354
 355
 356     DocDeclStr(
 357         virtual void , SizeWindows(),
 358         "Resizes subwindows", "");
 359
 360
 361     void SetNeedUpdating(bool needUpdating);
 362     bool GetNeedUpdating() const;
 363
 364     static wxVisualAttributes
 365     GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
 366 };
 367
 368
 369
 370 DocStr(wxSplitterEvent,
 371        "This class represents the events generated by a splitter control.", "");
 372
 373 class wxSplitterEvent : public wxNotifyEvent
 374 {
 375 public:
 376     wxSplitterEvent(wxEventType type = wxEVT_NULL,
 377                     wxSplitterWindow *splitter = (wxSplitterWindow *)NULL);
 378
 379
 380     DocDeclStr(
 381         void , SetSashPosition(int pos),
 382         "This function is only meaningful during EVT_SPLITTER_SASH_POS_CHANGING
 383 and EVT_SPLITTER_SASH_POS_CHANGED events.  In the case of _CHANGED
 384 events, sets the the new sash position. In the case of _CHANGING
 385 events, sets the new tracking bar position so visual feedback during
 386 dragging will represent that change that will actually take place. Set
 387 to -1 from the event handler code to prevent repositioning.", "");
 388
 389     DocDeclStr(
 390         int , GetSashPosition() const,
 391         "Returns the new sash position while in EVT_SPLITTER_SASH_POS_CHANGING
 392 and EVT_SPLITTER_SASH_POS_CHANGED events.", "");
 393
 394
 395     DocDeclStr(
 396         wxWindow *, GetWindowBeingRemoved() const,
 397         "Returns a pointer to the window being removed when a splitter window
 398 is unsplit.", "");
 399
 400
 401     DocDeclStr(
 402         int , GetX() const,
 403         "Returns the x coordinate of the double-click point in a
 404 EVT_SPLITTER_DCLICK event.", "");
 405
 406     DocDeclStr(
 407         int , GetY() const,
 408         "Returns the y coordinate of the double-click point in a
 409 EVT_SPLITTER_DCLICK event.", "");
 410
 411 };
 412
 413
 414
 415 %constant wxEventType wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED;
 416 %constant wxEventType wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING;
 417 %constant wxEventType wxEVT_COMMAND_SPLITTER_DOUBLECLICKED;
 418 %constant wxEventType wxEVT_COMMAND_SPLITTER_UNSPLIT;
 419
 420
 421 %pythoncode {
 422 EVT_SPLITTER_SASH_POS_CHANGED = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED, 1 )
 423 EVT_SPLITTER_SASH_POS_CHANGING = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING, 1 )
 424 EVT_SPLITTER_DOUBLECLICKED = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_DOUBLECLICKED, 1 )
 425 EVT_SPLITTER_UNSPLIT = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_UNSPLIT, 1 )
 426 EVT_SPLITTER_DCLICK = EVT_SPLITTER_DOUBLECLICKED
 427 }
 428
 429 //---------------------------------------------------------------------------
 430