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,
  53 with an optional vertical or horizontal split which can be
  54 used with the mouse or programmatically.
  55 ");
  56
  57 RefDoc(wxSplitterWindow, "
  58  Styles
  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  Events
  75
  76     EVT_SPLITTER_SASH_POS_CHANGING
  77                            The sash position is in the
  78                            process of being changed. May be
  79                            used to modify the position of
  80                            the tracking bar to properly
  81                            reflect the position that would
  82                            be set if the drag were to be
  83                            completed at this point.
  84
  85     EVT_SPLITTER_SASH_POS_CHANGED
  86                            The sash position was
  87                            changed. May be used to modify
  88                            the sash position before it is
  89                            set, or to prevent the change
  90                            from taking place.
  91
  92     EVT_SPLITTER_UNSPLIT   The splitter has been just unsplit.
  93
  94     EVT_SPLITTER_DCLICK    The sash was double clicked. The
  95                            default behaviour is to unsplit
  96                            the window when this happens
  97                            (unless the minimum pane size has
  98                            been set to a value greater than
  99                            zero.)
 100
 101 ");
 102
 103
 104 // wxSplitterWindow maintains one or two panes, with an optional vertical or
 105 // horizontal split which can be used with the mouse or programmatically.
 106 class wxSplitterWindow: public wxWindow
 107 {
 108 public:
 109     %pythonPrepend wxSplitterWindow         "if kwargs.has_key('point'): kwargs['pos'] = kwargs['point'];del kwargs['point']"
 110     %pythonPrepend wxSplitterWindow()       ""
 111     %pythonAppend  wxSplitterWindow         "self._setOORInfo(self)"
 112     %pythonAppend  wxSplitterWindow()       ""
 113
 114     RefDoc(wxSplitterWindow, ""); // turn it off for the ctors
 115
 116     DocCtorStr(
 117         wxSplitterWindow(wxWindow* parent, wxWindowID id,
 118                          const wxPoint& pos = wxDefaultPosition,
 119                          const wxSize& size = wxDefaultSize,
 120                          long style=wxSP_3D,
 121                          const wxString& name = wxPySplitterNameStr),
 122         "Constructor.  Creates and shows a SplitterWindow.");
 123
 124     DocCtorStrName(
 125         wxSplitterWindow(),
 126         "Precreate a SplitterWindow for 2-phase creation.",
 127         PreSplitterWindow);
 128
 129
 130     DocDeclStr(
 131         bool , Create(wxWindow* parent, wxWindowID id,
 132                       const wxPoint& pos = wxDefaultPosition,
 133                       const wxSize& size = wxDefaultSize,
 134                       long style=wxSP_3D,
 135                       const wxString& name = wxPySplitterNameStr),
 136         "Create the GUI part of the SplitterWindow for the 2-phase create.");
 137
 138
 139
 140     DocDeclStr(
 141         wxWindow *, GetWindow1() const,
 142         "Gets the only or left/top pane.");
 143
 144
 145     DocDeclStr(
 146         wxWindow *, GetWindow2() const,
 147         "Gets the right/bottom pane.");
 148
 149
 150     DocDeclStr(
 151         void , SetSplitMode(int mode),
 152         "Sets the split mode.  The mode can be wx.SPLIT_VERTICAL or
 153 wx.SPLIT_HORIZONTAL.  This only sets the internal variable;
 154 does not update the display.");
 155
 156
 157     DocDeclStr(
 158         wxSplitMode , GetSplitMode() const,
 159         "Gets the split mode");
 160
 161
 162     DocDeclStr(
 163         void , Initialize(wxWindow *window),
 164         "Initializes the splitter window to have one pane.  This
 165 should be called if you wish to initially view only a single
 166 pane in the splitter window.");
 167
 168
 169     // Associates the given window with window 2, drawing the appropriate sash
 170     // and changing the split mode.
 171     // Does nothing and returns False if the window is already split.
 172     // A sashPosition of 0 means choose a default sash position,
 173     // negative sashPosition specifies the size of right/lower pane as it's
 174     // absolute value rather than the size of left/upper pane.
 175
 176     DocDeclStr(
 177         virtual bool , SplitVertically(wxWindow *window1,
 178                                        wxWindow *window2,
 179                                        int sashPosition = 0),
 180         "Initializes the left and right panes of the splitter window.
 181
 182     window1       The left pane.
 183     window2       The right pane.
 184     sashPosition  The initial position of the sash. If this
 185                   value is positive, it specifies the size
 186                   of the left pane. If it is negative, it is
 187                   absolute value gives the size of the right
 188                   pane. Finally, specify 0 (default) to
 189                   choose the default position (half of the
 190                   total window width).
 191
 192 Returns True if successful, False otherwise (the window was
 193 already split).
 194
 195 SplitVertically should be called if you wish to initially
 196 view two panes. It can also be called at any subsequent
 197 time, but the application should check that the window is
 198 not currently split using IsSplit.");
 199
 200
 201     DocDeclStr(
 202         virtual bool , SplitHorizontally(wxWindow *window1,
 203                                          wxWindow *window2,
 204                                          int sashPosition = 0),
 205         "Initializes the top and bottom panes of the splitter window.
 206
 207     window1       The top pane.
 208     window2       The bottom pane.
 209     sashPosition  The initial position of the sash. If this
 210                   value is positive, it specifies the size
 211                   of the upper pane. If it is negative, it
 212                   is absolute value gives the size of the
 213                   lower pane. Finally, specify 0 (default)
 214                   to choose the default position (half of
 215                   the total window height).
 216
 217 Returns True if successful, False otherwise (the window was
 218 already split).
 219
 220 SplitHorizontally should be called if you wish to initially
 221 view two panes. It can also be called at any subsequent
 222 time, but the application should check that the window is
 223 not currently split using IsSplit.");
 224
 225
 226
 227     DocDeclStr(
 228         bool , Unsplit(wxWindow *toRemove = NULL),
 229         "Unsplits the window.  Pass the pane to remove, or None to
 230 remove the right or bottom pane.  Returns True if
 231 successful, False otherwise (the window was not split).
 232
 233 This function will not actually delete the pane being
 234 removed; it sends EVT_SPLITTER_UNSPLIT which can be handled
 235 for the desired behaviour. By default, the pane being
 236 removed is only hidden.");
 237
 238
 239
 240     DocDeclStr(
 241         bool , ReplaceWindow(wxWindow *winOld, wxWindow *winNew),
 242         "This function replaces one of the windows managed by the
 243 SplitterWindow with another one. It is in general better to
 244 use it instead of calling Unsplit() and then resplitting the
 245 window back because it will provoke much less flicker. It is
 246 valid to call this function whether the splitter has two
 247 windows or only one.
 248
 249 Both parameters should be non-None and winOld must specify
 250 one of the windows managed by the splitter. If the
 251 parameters are incorrect or the window couldn't be replaced,
 252 False is returned. Otherwise the function will return True,
 253 but please notice that it will not Destroy the replaced
 254 window and you may wish to do it yourself.");
 255
 256
 257     DocDeclStr(
 258         void , UpdateSize(),
 259         "Causes any pending sizing of the sash and child panes to
 260 take place immediately.
 261
 262 Such resizing normally takes place in idle time, in order to
 263 wait for layout to be completed. However, this can cause
 264 unacceptable flicker as the panes are resized after the
 265 window has been shown. To work around this, you can perform
 266 window layout (for example by sending a size event to the
 267 parent window), and then call this function, before showing
 268 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");
 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
 300 the panes 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 , SetMinimumPaneSize(int min),
 310         "Sets the minimum pane size in pixels.
 311
 312 The default minimum pane size is zero, which means that
 313 either pane can be reduced to zero by dragging the sash,
 314 thus removing one of the panes. To prevent this behaviour (and
 315 veto out-of-range sash dragging), set a minimum size,
 316 for example 20 pixels. If the wx.SP_PERMIT_UNSPLIT style is
 317 used when a splitter window is created, the window may be
 318 unsplit even if minimum size is non-zero.");
 319
 320     DocDeclStr(
 321         int , GetMinimumPaneSize() const,
 322         "Gets the minimum pane size in pixels.");
 323
 324
 325     DocDeclStr(
 326         virtual bool , SashHitTest(int x, int y, int tolerance = 5),
 327         "Tests for x, y over the sash");
 328
 329
 330     DocDeclStr(
 331         virtual void , SizeWindows(),
 332         "Resizes subwindows");
 333
 334
 335     void SetNeedUpdating(bool needUpdating);
 336     bool GetNeedUpdating() const;
 337 };
 338
 339
 340
 341 DocStr(wxSplitterEvent,
 342        "This class represents the events generated by a splitter control.");
 343
 344 class wxSplitterEvent : public wxNotifyEvent
 345 {
 346 public:
 347     wxSplitterEvent(wxEventType type = wxEVT_NULL,
 348                     wxSplitterWindow *splitter = (wxSplitterWindow *)NULL);
 349
 350
 351     DocDeclStr(
 352         void , SetSashPosition(int pos),
 353         "This funciton is only meaningful during
 354 EVT_SPLITTER_SASH_POS_CHANGING and
 355 EVT_SPLITTER_SASH_POS_CHANGED events.  In the case of
 356 _CHANGED events, sets the the new sash position. In the case
 357 of _CHANGING events, sets the new tracking bar position so
 358 visual feedback during dragging will represent that change
 359 that will actually take place. Set to -1 from the event
 360 handler code to prevent repositioning.");
 361
 362     DocDeclStr(
 363         int , GetSashPosition() const,
 364         "Returns the new sash position while in
 365 EVT_SPLITTER_SASH_POS_CHANGING and
 366 EVT_SPLITTER_SASH_POS_CHANGED events.");
 367
 368
 369     DocDeclStr(
 370         wxWindow *, GetWindowBeingRemoved() const,
 371         "Returns a pointer to the window being removed when a
 372 splitter window is unsplit.");
 373
 374
 375     DocDeclStr(
 376         int , GetX() const,
 377         "Returns the x coordinate of the double-click point in a
 378 EVT_SPLITTER_DCLICK event.");
 379
 380     DocDeclStr(
 381         int , GetY() const,
 382         "Returns the y coordinate of the double-click point in a
 383 EVT_SPLITTER_DCLICK event.");
 384
 385 };
 386
 387
 388
 389 %constant wxEventType wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED;
 390 %constant wxEventType wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING;
 391 %constant wxEventType wxEVT_COMMAND_SPLITTER_DOUBLECLICKED;
 392 %constant wxEventType wxEVT_COMMAND_SPLITTER_UNSPLIT;
 393
 394
 395 %pythoncode {
 396 EVT_SPLITTER_SASH_POS_CHANGED = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED, 1 )
 397 EVT_SPLITTER_SASH_POS_CHANGING = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING, 1 )
 398 EVT_SPLITTER_DOUBLECLICKED = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_DOUBLECLICKED, 1 )
 399 EVT_SPLITTER_UNSPLIT = wx.PyEventBinder( wxEVT_COMMAND_SPLITTER_UNSPLIT, 1 )
 400 EVT_SPLITTER_DCLICK = EVT_SPLITTER_DOUBLECLICKED
 401 }
 402
 403 //---------------------------------------------------------------------------
 404