Various wxHtml updates

[wxWidgets.git] / wxPython / src / _splitter.i

diff --git a/wxPython/src/_splitter.i b/wxPython/src/_splitter.i
index ff47fadf5092e342d7e58def25f958037cf5b19d..824ed582054bd260190e25bab2b97bd67a746d80 100644 (file)
--- a/wxPython/src/_splitter.i
+++ b/wxPython/src/_splitter.i
@@ -49,13 +49,13 @@ enum
 //---------------------------------------------------------------------------
 
 DocStr(wxSplitterWindow,
 //---------------------------------------------------------------------------
 
 DocStr(wxSplitterWindow,

-"wx.SplitterWindow manages up to two subwindows or panes,
-with an optional vertical or horizontal split which can be
-used with the mouse or programmatically.
-");
+"wx.SplitterWindow manages up to two subwindows or panes, with an
+optional vertical or horizontal split which can be used with the mouse
+or programmatically.", "

 
 

-RefDoc(wxSplitterWindow, "
- Styles
+Styles
+-------
+    ====================   ======================================

     wx.SP_3D               Draws a 3D effect border and sash.
     wx.SP_3DSASH           Draws a 3D effect sash.
     wx.SP_3DBORDER         Synonym for wxSP_BORDER.
     wx.SP_3D               Draws a 3D effect border and sash.
     wx.SP_3DSASH           Draws a 3D effect sash.
     wx.SP_3DBORDER         Synonym for wxSP_BORDER.


@@ -70,98 +70,101 @@ RefDoc(wxSplitterWindow, "
                            the minimum pane size other than zero.
     wx.SP_LIVE_UPDATE      Don't draw XOR line but resize the
                            child windows immediately.
                            the minimum pane size other than zero.
     wx.SP_LIVE_UPDATE      Don't draw XOR line but resize the
                            child windows immediately.

-
- Events
-
-    EVT_SPLITTER_SASH_POS_CHANGING
-                           The sash position is in the
-                           process of being changed. May be
-                           used to modify the position of
-                           the tracking bar to properly
-                           reflect the position that would
-                           be set if the drag were to be
-                           completed at this point.
+    ====================   ======================================
+
+Events
+------
+    ==============================  =======================================
+    EVT_SPLITTER_SASH_POS_CHANGING  The sash position is in the
+                                    process of being changed. May be
+                                    used to modify the position of
+                                    the tracking bar to properly
+                                    reflect the position that would
+                                    be set if the drag were to be
+                                    completed at this point.

 
     EVT_SPLITTER_SASH_POS_CHANGED
 
     EVT_SPLITTER_SASH_POS_CHANGED

-                           The sash position was
-                           changed. May be used to modify
-                           the sash position before it is
-                           set, or to prevent the change
-                           from taking place. 
+                                    The sash position was
+                                    changed. May be used to modify
+                                    the sash position before it is
+                                    set, or to prevent the change
+                                    from taking place. 
+
+    EVT_SPLITTER_UNSPLIT            The splitter has been just unsplit.
+
+    EVT_SPLITTER_DCLICK             The sash was double clicked. The
+                                    default behaviour is to unsplit
+                                    the window when this happens
+                                    (unless the minimum pane size has
+                                    been set to a value greater than
+                                    zero.)
+    ==============================  =======================================

 
 

-    EVT_SPLITTER_UNSPLIT   The splitter has been just unsplit.
+");

 
 

-    EVT_SPLITTER_DCLICK    The sash was double clicked. The
-                           default behaviour is to unsplit
-                           the window when this happens
-                           (unless the minimum pane size has
-                           been set to a value greater than
-                           zero.)

 
 

-");

 
 

+MustHaveApp(wxSplitterWindow);

 
 

-// wxSplitterWindow maintains one or two panes, with an optional vertical or
-// horizontal split which can be used with the mouse or programmatically.

 class wxSplitterWindow: public wxWindow
 {
 public:
 class wxSplitterWindow: public wxWindow
 {
 public:

-    %pythonPrepend wxSplitterWindow         "if kwargs.has_key('point'): kwargs['pos'] = kwargs['point']"
+    %pythonPrepend wxSplitterWindow         "if kwargs.has_key('point'): kwargs['pos'] = kwargs['point'];del kwargs['point']"

     %pythonPrepend wxSplitterWindow()       ""
     %pythonAppend  wxSplitterWindow         "self._setOORInfo(self)"
     %pythonAppend  wxSplitterWindow()       ""
 
     DocCtorStr(
     %pythonPrepend wxSplitterWindow()       ""
     %pythonAppend  wxSplitterWindow         "self._setOORInfo(self)"
     %pythonAppend  wxSplitterWindow()       ""
 
     DocCtorStr(

-        wxSplitterWindow(wxWindow* parent, wxWindowID id,
+        wxSplitterWindow(wxWindow* parent, wxWindowID id=-1,

                          const wxPoint& pos = wxDefaultPosition,
                          const wxSize& size = wxDefaultSize,
                          long style=wxSP_3D,
                          const wxString& name = wxPySplitterNameStr),
                          const wxPoint& pos = wxDefaultPosition,
                          const wxSize& size = wxDefaultSize,
                          long style=wxSP_3D,
                          const wxString& name = wxPySplitterNameStr),

-        "Constructor.  Creates and shows a SplitterWindow.");
+        "Constructor.  Creates and shows a SplitterWindow.", "");

     
     DocCtorStrName(
         wxSplitterWindow(),
     
     DocCtorStrName(
         wxSplitterWindow(),

-        "Precreate a SplitterWindow for 2-phase creation.",
+        "Precreate a SplitterWindow for 2-phase creation.", "",

         PreSplitterWindow);
 
 
     DocDeclStr(
         PreSplitterWindow);
 
 
     DocDeclStr(

-        bool , Create(wxWindow* parent, wxWindowID id,
+        bool , Create(wxWindow* parent, wxWindowID id=-1,

                       const wxPoint& pos = wxDefaultPosition,
                       const wxSize& size = wxDefaultSize,
                       long style=wxSP_3D,
                       const wxString& name = wxPySplitterNameStr),
                       const wxPoint& pos = wxDefaultPosition,
                       const wxSize& size = wxDefaultSize,
                       long style=wxSP_3D,
                       const wxString& name = wxPySplitterNameStr),

-        "Create the GUI part of the SplitterWindow for the 2-phase create.");
+        "Create the GUI part of the SplitterWindow for the 2-phase create.", "");

     
 
 
     DocDeclStr(
         wxWindow *, GetWindow1() const,
     
 
 
     DocDeclStr(
         wxWindow *, GetWindow1() const,

-        "Gets the only or left/top pane.");
+        "Gets the only or left/top pane.", "");

     
 
     DocDeclStr(
         wxWindow *, GetWindow2() const,
     
 
     DocDeclStr(
         wxWindow *, GetWindow2() const,

-        "Gets the right/bottom pane.");
+        "Gets the right/bottom pane.", "");

 
 
     DocDeclStr(
         void , SetSplitMode(int mode),
         "Sets the split mode.  The mode can be wx.SPLIT_VERTICAL or
 
 
     DocDeclStr(
         void , SetSplitMode(int mode),
         "Sets the split mode.  The mode can be wx.SPLIT_VERTICAL or

-wx.SPLIT_HORIZONTAL.  This only sets the internal variable;
-does not update the display.");
+wx.SPLIT_HORIZONTAL.  This only sets the internal variable; does not
+update the display.", "");

     
 
     DocDeclStr(
         wxSplitMode , GetSplitMode() const,
     
 
     DocDeclStr(
         wxSplitMode , GetSplitMode() const,

-        "Gets the split mode");
+        "Gets the split mode", "");

     
 
     DocDeclStr(
         void , Initialize(wxWindow *window),
     
 
     DocDeclStr(
         void , Initialize(wxWindow *window),

-        "Initializes the splitter window to have one pane.  This
-should be called if you wish to initially view only a single
-pane in the splitter window.");
+        "Initializes the splitter window to have one pane.  This should be
+called if you wish to initially view only a single pane in the
+splitter window.  The child window is shown if it is currently hidden.", "");

     
 
     // Associates the given window with window 2, drawing the appropriate sash
     
 
     // Associates the given window with window 2, drawing the appropriate sash


@@ -175,169 +178,198 @@ pane in the splitter window.");
         virtual bool , SplitVertically(wxWindow *window1,
                                        wxWindow *window2,
                                        int sashPosition = 0),
         virtual bool , SplitVertically(wxWindow *window1,
                                        wxWindow *window2,
                                        int sashPosition = 0),

-        "Initializes the left and right panes of the splitter window.
-
-    window1       The left pane.
-    window2       The right pane.
-    sashPosition  The initial position of the sash. If this
-                  value is positive, it specifies the size
-                  of the left pane. If it is negative, it is
-                  absolute value gives the size of the right
-                  pane. Finally, specify 0 (default) to
-                  choose the default position (half of the
-                  total window width).
-
-Returns True if successful, False otherwise (the window was
-already split).
-
-SplitVertically should be called if you wish to initially
-view two panes. It can also be called at any subsequent
-time, but the application should check that the window is
-not currently split using IsSplit.");
+        "Initializes the left and right panes of the splitter window.  The
+child windows are shown if they are currently hidden.","
+
+    :param window1:       The left pane.
+    :param window2:       The right pane.
+    :param sashPosition:  The initial position of the sash. If this
+                  value is positive, it specifies the size of the left
+                  pane. If it is negative, its absolute value gives
+                  the size of the right pane. Finally, specify 0
+                  (default) to choose the default position (half of
+                  the total window width).
+
+Returns True if successful, False otherwise (the window was already
+split).
+
+SplitVertically should be called if you wish to initially view two
+panes. It can also be called at any subsequent time, but the
+application should check that the window is not currently split using
+`IsSplit`.
+");

     
 
     DocDeclStr(
         virtual bool , SplitHorizontally(wxWindow *window1,
                                          wxWindow *window2,
                                          int sashPosition = 0),
     
 
     DocDeclStr(
         virtual bool , SplitHorizontally(wxWindow *window1,
                                          wxWindow *window2,
                                          int sashPosition = 0),

-        "Initializes the top and bottom panes of the splitter window.
-
-    window1       The top pane.
-    window2       The bottom pane.
-    sashPosition  The initial position of the sash. If this
-                  value is positive, it specifies the size
-                  of the upper pane. If it is negative, it
-                  is absolute value gives the size of the
-                  lower pane. Finally, specify 0 (default)
-                  to choose the default position (half of
+        "Initializes the top and bottom panes of the splitter window.  The
+child windows are shown if they are currently hidden.","
+
+    :param window1:       The top pane.
+    :param window2:       The bottom pane.
+    :param sashPosition:  The initial position of the sash. If this
+                  value is positive, it specifies the size of the
+                  upper pane. If it is negative, its absolute value
+                  gives the size of the lower pane. Finally, specify 0
+                  (default) to choose the default position (half of

                   the total window height).
 
                   the total window height).
 

-Returns True if successful, False otherwise (the window was
-already split).
+Returns True if successful, False otherwise (the window was already
+split).

 
 

-SplitHorizontally should be called if you wish to initially
-view two panes. It can also be called at any subsequent
-time, but the application should check that the window is
-not currently split using IsSplit.");
+SplitHorizontally should be called if you wish to initially view two
+panes. It can also be called at any subsequent time, but the
+application should check that the window is not currently split using
+`IsSplit`.
+");

 
     
 
     DocDeclStr(
         bool , Unsplit(wxWindow *toRemove = NULL),
 
     
 
     DocDeclStr(
         bool , Unsplit(wxWindow *toRemove = NULL),

-        "Unsplits the window.  Pass the pane to remove, or None to
-remove the right or bottom pane.  Returns True if
-successful, False otherwise (the window was not split).
+        "Unsplits the window.  Pass the pane to remove, or None to remove the
+right or bottom pane.  Returns True if successful, False otherwise (the
+window was not split).

 
 This function will not actually delete the pane being
 removed; it sends EVT_SPLITTER_UNSPLIT which can be handled
 for the desired behaviour. By default, the pane being
 
 This function will not actually delete the pane being
 removed; it sends EVT_SPLITTER_UNSPLIT which can be handled
 for the desired behaviour. By default, the pane being

-removed is only hidden.");
+removed is only hidden.", "");

     
 
 
     DocDeclStr(
         bool , ReplaceWindow(wxWindow *winOld, wxWindow *winNew),
         "This function replaces one of the windows managed by the
     
 
 
     DocDeclStr(
         bool , ReplaceWindow(wxWindow *winOld, wxWindow *winNew),
         "This function replaces one of the windows managed by the

-SplitterWindow with another one. It is in general better to
-use it instead of calling Unsplit() and then resplitting the
-window back because it will provoke much less flicker. It is
-valid to call this function whether the splitter has two
-windows or only one.
-
-Both parameters should be non-None and winOld must specify
-one of the windows managed by the splitter. If the
-parameters are incorrect or the window couldn't be replaced,
-False is returned. Otherwise the function will return True,
-but please notice that it will not Destroy the replaced
-window and you may wish to do it yourself.");
+SplitterWindow with another one. It is in general better to use it
+instead of calling Unsplit() and then resplitting the window back
+because it will provoke much less flicker. It is valid to call this
+function whether the splitter has two windows or only one.
+
+Both parameters should be non-None and winOld must specify one of the
+windows managed by the splitter. If the parameters are incorrect or
+the window couldn't be replaced, False is returned. Otherwise the
+function will return True, but please notice that it will not Destroy
+the replaced window and you may wish to do it yourself.", "");

     
 
     DocDeclStr(
         void , UpdateSize(),
     
 
     DocDeclStr(
         void , UpdateSize(),

-        "Causes any pending sizing of the sash and child panes to
-take place immediately.
+        "Causes any pending sizing of the sash and child panes to take place
+immediately.

 
 

-Such resizing normally takes place in idle time, in order to
-wait for layout to be completed. However, this can cause
-unacceptable flicker as the panes are resized after the
-window has been shown. To work around this, you can perform
-window layout (for example by sending a size event to the
-parent window), and then call this function, before showing
-the top-level window.");
+Such resizing normally takes place in idle time, in order to wait for
+layout to be completed. However, this can cause unacceptable flicker
+as the panes are resized after the window has been shown. To work
+around this, you can perform window layout (for example by sending a
+size event to the parent window), and then call this function, before
+showing the top-level window.", "");

 
 
    
     DocDeclStr(
         bool , IsSplit() const,
 
 
    
     DocDeclStr(
         bool , IsSplit() const,

-        "Is the window split?");
+        "Is the window split?", "");

     
 
     DocDeclStr(
         void , SetSashSize(int width),
     
 
     DocDeclStr(
         void , SetSashSize(int width),

-        "Sets the sash size");
+        "Sets the sash size.", "");

     
 
     DocDeclStr(
         void , SetBorderSize(int width),
     
 
     DocDeclStr(
         void , SetBorderSize(int width),

-        "Sets the border size");
+        "Sets the border size. Currently a NOP.", "");

     
 
     DocDeclStr(
         int , GetSashSize() const,
     
 
     DocDeclStr(
         int , GetSashSize() const,

-        "Gets the sash size");
+        "Gets the sash size", "");

     
 
     DocDeclStr(
         int , GetBorderSize() const,
     
 
     DocDeclStr(
         int , GetBorderSize() const,

-        "Gets the border size");
+        "Gets the border size", "");

     
 
     DocDeclStr(
     
 
     DocDeclStr(

-        void , SetSashPosition(int position, bool redraw = True),
-        "Sets the sash position, in pixels.  If redraw is Ttrue then
-the panes are resized and the sash and border are redrawn.");
+        void , SetSashPosition(int position, bool redraw = true),
+        "Sets the sash position, in pixels.  If redraw is Ttrue then the panes
+are resized and the sash and border are redrawn.", "");

     
 
     DocDeclStr(
         int , GetSashPosition() const,
     
 
     DocDeclStr(
         int , GetSashPosition() const,

-        "Returns the surrent sash position.");
+        "Returns the surrent sash position.", "");
+    
+
+    DocDeclStr(
+        void , SetSashGravity(double gravity),
+        "Set the sash gravity.  Gravity is a floating-point factor between 0.0
+and 1.0 which controls position of sash while resizing the
+`wx.SplitterWindow`.  The gravity specifies how much the left/top
+window will grow while resizing.","
+
+Example values:
+
+    ======= =======================================
+    0.0      Only the bottom or right window is
+             automaticaly resized.
+    0.5      Both windows grow equally.
+    1.0      Only left/top window grows.
+    ======= =======================================
+
+The default value of sash gravity is 0.0. That value is compatible
+with the previous (before gravity was introduced) behaviour of the 
+`wx.SplitterWindow`.");
+
+    DocDeclStr(
+        double , GetSashGravity() const,
+        "Gets the sash gravity.
+
+:see: `SetSashGravity`
+", "");

     
 
     DocDeclStr(
         void , SetMinimumPaneSize(int min),
         "Sets the minimum pane size in pixels.
 
     
 
     DocDeclStr(
         void , SetMinimumPaneSize(int min),
         "Sets the minimum pane size in pixels.
 

-The default minimum pane size is zero, which means that
-either pane can be reduced to zero by dragging the sash,
-thus removing one of the panes. To prevent this behaviour (and
-veto out-of-range sash dragging), set a minimum size,
-for example 20 pixels. If the wx.SP_PERMIT_UNSPLIT style is
-used when a splitter window is created, the window may be
-unsplit even if minimum size is non-zero.");
+The default minimum pane size is zero, which means that either pane
+can be reduced to zero by dragging the sash, thus removing one of the
+panes. To prevent this behaviour (and veto out-of-range sash
+dragging), set a minimum size, for example 20 pixels. If the
+wx.SP_PERMIT_UNSPLIT style is used when a splitter window is created,
+the window may be unsplit even if minimum size is non-zero.", "");

     
     DocDeclStr(
         int , GetMinimumPaneSize() const,
     
     DocDeclStr(
         int , GetMinimumPaneSize() const,

-        "Gets the minimum pane size in pixels.");
+        "Gets the minimum pane size in pixels.", "");

     
 
     DocDeclStr(
         virtual bool , SashHitTest(int x, int y, int tolerance = 5),
     
 
     DocDeclStr(
         virtual bool , SashHitTest(int x, int y, int tolerance = 5),

-        "Tests for x, y over the sash");
+        "Tests for x, y over the sash", "");

     
 
     DocDeclStr(
         virtual void , SizeWindows(),
     
 
     DocDeclStr(
         virtual void , SizeWindows(),

-        "Resizes subwindows");
+        "Resizes subwindows", "");

     
 
     void SetNeedUpdating(bool needUpdating);
     bool GetNeedUpdating() const;
     
 
     void SetNeedUpdating(bool needUpdating);
     bool GetNeedUpdating() const;

+
+    static wxVisualAttributes
+    GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);

 };
 
 
 
 DocStr(wxSplitterEvent,
 };
 
 
 
 DocStr(wxSplitterEvent,

-       "This class represents the events generated by a splitter control.");
+       "This class represents the events generated by a splitter control.", "");

 
 class wxSplitterEvent : public wxNotifyEvent
 {
 
 class wxSplitterEvent : public wxNotifyEvent
 {


@@ -348,37 +380,34 @@ public:
 
     DocDeclStr(
         void , SetSashPosition(int pos),
 
     DocDeclStr(
         void , SetSashPosition(int pos),

-        "This funciton is only meaningful during
-EVT_SPLITTER_SASH_POS_CHANGING and
-EVT_SPLITTER_SASH_POS_CHANGED events.  In the case of
-_CHANGED events, sets the the new sash position. In the case
-of _CHANGING events, sets the new tracking bar position so
-visual feedback during dragging will represent that change
-that will actually take place. Set to -1 from the event
-handler code to prevent repositioning.");
+        "This function is only meaningful during EVT_SPLITTER_SASH_POS_CHANGING
+and EVT_SPLITTER_SASH_POS_CHANGED events.  In the case of _CHANGED
+events, sets the the new sash position. In the case of _CHANGING
+events, sets the new tracking bar position so visual feedback during
+dragging will represent that change that will actually take place. Set
+to -1 from the event handler code to prevent repositioning.", "");

     
     DocDeclStr(
         int , GetSashPosition() const,
     
     DocDeclStr(
         int , GetSashPosition() const,

-        "Returns the new sash position while in
-EVT_SPLITTER_SASH_POS_CHANGING and
-EVT_SPLITTER_SASH_POS_CHANGED events.");
+        "Returns the new sash position while in EVT_SPLITTER_SASH_POS_CHANGING
+and EVT_SPLITTER_SASH_POS_CHANGED events.", "");

     
 
     DocDeclStr(
         wxWindow *, GetWindowBeingRemoved() const,
     
 
     DocDeclStr(
         wxWindow *, GetWindowBeingRemoved() const,

-        "Returns a pointer to the window being removed when a
-splitter window is unsplit.");
+        "Returns a pointer to the window being removed when a splitter window
+is unsplit.", "");

     
 
     DocDeclStr(
         int , GetX() const,
         "Returns the x coordinate of the double-click point in a
     
 
     DocDeclStr(
         int , GetX() const,
         "Returns the x coordinate of the double-click point in a

-EVT_SPLITTER_DCLICK event.");
+EVT_SPLITTER_DCLICK event.", "");

     
     DocDeclStr(
         int , GetY() const,
         "Returns the y coordinate of the double-click point in a
     
     DocDeclStr(
         int , GetY() const,
         "Returns the y coordinate of the double-click point in a

-EVT_SPLITTER_DCLICK event.");
+EVT_SPLITTER_DCLICK event.", "");

     
 };
 
     
 };