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