use the right number in the tarball filename

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

diff --git a/wxPython/src/_window.i b/wxPython/src/_window.i
index d6d9ad156edbcccdd358f410b2a95c48bd906594..b59bf49633d45b2cf5e8b56fc7a6ff544afd57eb 100644 (file)
--- a/wxPython/src/_window.i
+++ b/wxPython/src/_window.i
@@ -23,123 +23,490 @@ MAKE_CONST_WXSTRING(PanelNameStr);
 //---------------------------------------------------------------------------
 %newgroup
 
 //---------------------------------------------------------------------------
 %newgroup
 

+
+DocStr(wxVisualAttributes,
+    "struct containing all the visual attributes of a control", "");
+
+struct wxVisualAttributes
+{
+    %extend {
+        wxVisualAttributes() { return new wxVisualAttributes; }
+        ~wxVisualAttributes() { delete self; }
+    } 
+    
+    // the font used for control label/text inside it
+    wxFont font;
+
+    // the foreground colour
+    wxColour colFg;
+
+    // the background colour, may be wxNullColour if the controls background
+    // colour is not solid
+    wxColour colBg;
+};
+
+
+
+
+enum wxWindowVariant 
+{
+    wxWINDOW_VARIANT_NORMAL,        // Normal size
+    wxWINDOW_VARIANT_SMALL,         // Smaller size (about 25 % smaller than normal )
+    wxWINDOW_VARIANT_MINI,          // Mini size (about 33 % smaller than normal )
+    wxWINDOW_VARIANT_LARGE,         // Large size (about 25 % larger than normal )
+    wxWINDOW_VARIANT_MAX
+};
+
+
+DocStr(wxWindow,
+"wx.Window is the base class for all windows and represents any visible
+object on the screen. All controls, top level windows and so on are
+wx.Windows. Sizers and device contexts are not however, as they don't
+appear on screen themselves.
+",
+"      
+Styles
+-------
+    =============================  =====================================
+    wx.SIMPLE_BORDER               Displays a thin border around the window.
+                                   
+    wx.DOUBLE_BORDER               Displays a double border. Windows and Mac only.
+                                   
+    wx.SUNKEN_BORDER               Displays a sunken border.
+                                   
+    wx.RAISED_BORDER               Displays a raised border.
+                                   
+    wx.STATIC_BORDER               Displays a border suitable for a static
+                                   control. Windows only.
+                                   
+    wx.NO_BORDER                   Displays no border, overriding the default
+                                   border style for the window.
+                                   
+    wx.TRANSPARENT_WINDOW          The window is transparent, that is, it
+                                   will not receive paint events. Windows only.
+                                   
+    wx.TAB_TRAVERSAL               Use this to enable tab traversal for
+                                   non-dialog windows.
+                                   
+    wx.WANTS_CHARS                 Use this to indicate that the window
+                                   wants to get all char/key events for
+                                   all keys - even for keys like TAB or
+                                   ENTER which are usually used for
+                                   dialog navigation and which wouldn't
+                                   be generated without this style. If
+                                   you need to use this style in order to
+                                   get the arrows or etc., but would
+                                   still like to have normal keyboard
+                                   navigation take place, you should
+                                   create and send a wxNavigationKeyEvent
+                                   in response to the key events for Tab
+                                   and Shift-Tab.
+                                   
+    wx.NO_FULL_REPAINT_ON_RESIZE   Disables repainting the window
+                                   completely when its size is changed.
+                                   You will have to repaint the new
+                                   window area manually if you use this
+                                   style. As of version 2.5.1 this
+                                   style is on by default.  Use
+                                   wx.FULL_REPAINT_ON_RESIZE to
+                                   deactivate it.
+                                   
+    wx.VSCROLL                     Use this style to enable a vertical scrollbar.
+                                   
+    wx.HSCROLL                     Use this style to enable a horizontal scrollbar.
+                                   
+    wx.ALWAYS_SHOW_SB              If a window has scrollbars, disable them
+                                   instead of hiding them when they are
+                                   not needed (i.e. when the size of the
+                                   window is big enough to not require
+                                   the scrollbars to navigate it). This
+                                   style is currently only implemented
+                                   for wxMSW and wxUniversal and does
+                                   nothing on the other platforms.
+                                   
+    wx.CLIP_CHILDREN               Use this style to eliminate flicker caused by
+                                   the background being repainted, then
+                                   children being painted over
+                                   them. Windows only.
+                                   
+    wx.FULL_REPAINT_ON_RESIZE      Use this style to force a complete
+                                   redraw of the window whenever it is
+                                   resized instead of redrawing just the
+                                   part of the window affected by
+                                   resizing. Note that this was the
+                                   behaviour by default before 2.5.1
+                                   release and that if you experience
+                                   redraw problems with the code which
+                                   previously used to work you may want
+                                   to try this.
+    =============================  =====================================
+
+
+Extra Styles
+------------
+    =============================   =====================================
+    wx.WS_EX_VALIDATE_RECURSIVELY   By default,
+                                    Validate/TransferDataTo/FromWindow()
+                                    only work on direct children of
+                                    the window (compatible
+                                    behaviour). Set this flag to make
+                                    them recursively descend into all
+                                    subwindows.
+
+    wx.WS_EX_BLOCK_EVENTS           wx.CommandEvents and the objects of the
+                                    derived classes are forwarded to
+                                    the parent window and so on
+                                    recursively by default. Using this
+                                    flag for the given window allows
+                                    to block this propagation at this
+                                    window, i.e. prevent the events
+                                    from being propagated further
+                                    upwards. Dialogs have this flag on
+                                    by default.
+
+    wx.WS_EX_TRANSIENT              Don't use this window as an implicit parent for
+                                    the other windows: this must be
+                                    used with transient windows as
+                                    otherwise there is the risk of
+                                    creating a dialog/frame with this
+                                    window as a parent which would
+                                    lead to a crash if the parent is
+                                    destroyed before the child.
+
+    wx.WS_EX_PROCESS_IDLE           This window should always process idle
+                                    events, even if the mode set by
+                                    `wx.IdleEvent.SetMode` is
+                                    wx.IDLE_PROCESS_SPECIFIED.
+
+    wx.WS_EX_PROCESS_UI_UPDATES     This window should always process UI
+                                    update events, even if the mode
+                                    set by `wx.UpdateUIEvent.SetMode` is
+                                    wxUPDATE_UI_PROCESS_SPECIFIED.
+    =============================   =====================================
+
+");
+
+
+MustHaveApp(wxWindow);
+MustHaveApp(wxWindow::FindFocus);
+MustHaveApp(wxWindow::GetCapture);
+
+// This one is not restricted to wxWindow
+MustHaveApp(GetClassDefaultAttributes);
+

 class wxWindow : public wxEvtHandler
 {
 public:
     %pythonAppend wxWindow         "self._setOORInfo(self)"
     %pythonAppend wxWindow()       ""
 class wxWindow : public wxEvtHandler
 {
 public:
     %pythonAppend wxWindow         "self._setOORInfo(self)"
     %pythonAppend wxWindow()       ""

+    %typemap(out) wxWindow*;    // turn off this typemap
+
+    DocCtorStr(
+        wxWindow(wxWindow* parent, const wxWindowID id=-1,
+                 const wxPoint& pos = wxDefaultPosition,
+                 const wxSize& size = wxDefaultSize,
+                 long style = 0,
+                 const wxString& name = wxPyPanelNameStr),
+        "Construct and show a generic Window.", "");
+
+    DocCtorStrName(
+        wxWindow(),
+        "Precreate a Window for 2-phase creation.", "",
+        PreWindow);
+    
+    // Turn it back on again
+    %typemap(out) wxWindow* { $result = wxPyMake_wxObject($1, $owner); }

 
 

-    wxWindow(wxWindow* parent, const wxWindowID id,
-             const wxPoint& pos = wxDefaultPosition,
-             const wxSize& size = wxDefaultSize,
-             long style = 0,
-             const wxString& name = wxPyPanelNameStr);
-    %name(PreWindow)wxWindow();
-
-    bool Create(wxWindow* parent, const wxWindowID id,
+    
+    DocDeclStr(
+        bool , Create(wxWindow* parent, const wxWindowID id=-1,

                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = 0,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = 0,

-                const wxString& name = wxPyPanelNameStr);
-
-
+                      const wxString& name = wxPyPanelNameStr),
+        "Create the GUI part of the Window for 2-phase creation mode.", "");
+    

 
     // deleting the window
     // -------------------
 
 
     // deleting the window
     // -------------------
 

-    // ask the window to close itself, return True if the event handler
-    // honoured our request
-    bool Close( bool force = False );

 
 

-    // delete window unconditionally (dangerous!), returns True if ok
-    virtual bool Destroy();
+    DocDeclStr(
+        bool , Close( bool force = false ),
+        "This function simply generates a EVT_CLOSE event whose handler usually
+tries to close the window. It doesn't close the window itself,
+however.  If force is False (the default) then the window's close
+handler will be allowed to veto the destruction of the window.",
+"
+Usually Close is only used with the top level windows (wx.Frame and
+wx.Dialog classes) as the others are not supposed to have any special
+EVT_CLOSE logic.
+
+The close handler should check whether the window is being deleted
+forcibly, using wx.CloseEvent.GetForce, in which case it should
+destroy the window using wx.Window.Destroy.
+
+Note that calling Close does not guarantee that the window will be
+destroyed; but it provides a way to simulate a manual close of a
+window, which may or may not be implemented by destroying the
+window. The default EVT_CLOSE handler for wx.Dialog does not
+necessarily delete the dialog, since it will simply simulate an
+wxID_CANCEL event which is handled by the appropriate button event
+handler and may do anything at all.
+
+To guarantee that the window will be destroyed, call wx.Window.Destroy
+instead.");
+    
+
+
+    %pythonPrepend Destroy "args[0].this.own(False)"
+    DocDeclStr(
+        virtual bool , Destroy(),
+        "Destroys the window safely.  Frames and dialogs are not destroyed
+immediately when this function is called -- they are added to a list
+of windows to be deleted on idle time, when all the window's events
+have been processed. This prevents problems with events being sent to
+non-existent windows.

 
 

-    // delete all children of this window, returns True if ok
-    bool DestroyChildren();
+Returns True if the window has either been successfully deleted, or it
+has been added to the list of windows pending real deletion.", "");
+    

 
 

-    // is the window being deleted?
-    bool IsBeingDeleted() const;
+    DocDeclStr(
+        bool , DestroyChildren(),
+        "Destroys all children of a window. Called automatically by the
+destructor.", "");
+    

 
 

+    DocDeclStr(
+        bool , IsBeingDeleted() const,
+        "Is the window in the process of being deleted?", "");
+    

 
 

+    

     // window attributes
     // -----------------
 
     // window attributes
     // -----------------
 

-    // the text which the window shows in the title if applicable
-    virtual void SetTitle( const wxString& WXUNUSED(title) );
-    virtual wxString GetTitle() const;
+    //DocDeclStr(
+    //    virtual void , SetTitle( const wxString& title),
+    //    "Sets the window's title. Applicable only to frames and dialogs.", "");
+    
+    //DocDeclStr(
+    //    virtual wxString , GetTitle() const,
+    //    "Gets the window's title. Applicable only to frames and dialogs.", "");    
+
+    DocDeclStr(
+        virtual void , SetLabel(const wxString& label),
+        "Set the text which the window shows in its label if applicable.", "");
+    
+    DocDeclStr(
+        virtual wxString , GetLabel() const,
+        "Generic way of getting a label from any window, for identification
+purposes.  The interpretation of this function differs from class to
+class. For frames and dialogs, the value returned is the title. For
+buttons or static text controls, it is the button text. This function
+can be useful for meta-programs such as testing tools or special-needs
+access programs)which need to identify windows by name.", "");
+    
+
+    DocDeclStr(
+        virtual void , SetName( const wxString &name ),
+        "Sets the window's name.  The window name is used for ressource setting
+in X, it is not the same as the window title/label", "");
+    
+    DocDeclStr(
+        virtual wxString , GetName() const,
+        "Returns the windows name.  This name is not guaranteed to be unique;
+it is up to the programmer to supply an appropriate name in the window
+constructor or via wx.Window.SetName.", "");
+    
+    
+    DocDeclStr(
+        void , SetWindowVariant( wxWindowVariant variant ),
+        "Sets the variant of the window/font size to use for this window, if
+the platform supports variants, for example, wxMac.",
+        "
+Variant values are:
+
+    ========================    =======================================
+    wx.WINDOW_VARIANT_NORMAL    Normal size
+    wx.WINDOW_VARIANT_SMALL     Smaller size (about 25 % smaller than normal)
+    wx.WINDOW_VARIANT_MINI      Mini size (about 33 % smaller than normal)
+    wx.WINDOW_VARIANT_LARGE     Large size (about 25 % larger than normal)
+    ========================    =======================================
+");
+    
+    DocDeclStr(
+        wxWindowVariant , GetWindowVariant() const,
+        "", "");
+    

 
 

-    // the text which the window shows in its label if applicable
-    virtual void SetLabel(const wxString& label);
-    virtual wxString GetLabel() const;
+    DocDeclStr(
+        void , SetId( wxWindowID winid ),
+        "Sets the identifier of the window.  Each window has an integer
+identifier. If the application has not provided one, an identifier
+will be generated. Normally, the identifier should be provided on
+creation and should not be modified subsequently.", "");
+    
+    DocDeclStr(
+        wxWindowID , GetId() const,
+        "Returns the identifier of the window.  Each window has an integer
+identifier. If the application has not provided one (or the default Id
+-1 is used) then an unique identifier with a negative value will be
+generated.", "");
+    

 
 

-    // the window name is used for ressource setting in X, it is not the
-    // same as the window title/label
-    virtual void SetName( const wxString &name );
-    virtual wxString GetName() const;
+    DocDeclStr(
+        static int , NewControlId(),
+        "Generate a control id for the controls which were not given one.", "");
+    

 
 

-    // window id uniquely identifies the window among its siblings unless
-    // it is -1 which means "don't care"
-    void SetId( wxWindowID winid );
-    wxWindowID GetId() const;
+    DocDeclStr(
+        static int , NextControlId(int winid),
+        "Get the id of the control following the one with the given
+autogenerated) id", "");
+    

 
 

-    // generate a control id for the controls which were not given one by
-    // user
-    static int NewControlId();
+    DocDeclStr(
+        static int , PrevControlId(int winid),
+        "Get the id of the control preceding the one with the given
+autogenerated) id", "");
+    

 
 

-    // get the id of the control following the one with the given
-    // (autogenerated) id
-    static int NextControlId(int winid);
+    DocDeclStr(
+        virtual wxLayoutDirection , GetLayoutDirection() const,
+        "Get the layout direction (LTR or RTL) for this window.  Returns
+``wx.Layout_Default`` if layout direction is not supported.", "");
+    
+    DocDeclStr(
+        virtual void , SetLayoutDirection(wxLayoutDirection dir),
+        "Set the layout direction (LTR or RTL) for this window.", "");
+    

 
 

-    // get the id of the control preceding the one with the given
-    // (autogenerated) id
-    static int PrevControlId(int winid);
+    DocDeclStr(
+        virtual wxCoord , AdjustForLayoutDirection(wxCoord x,
+                                             wxCoord width,
+                                                   wxCoord widthTotal) const,
+        "Mirror coordinates for RTL layout if this window uses it and if the
+mirroring is not done automatically like Win32.", "");
+    

 
 

+    

 
 
     // moving/resizing
     // ---------------
 
 
 
     // moving/resizing
     // ---------------
 

-    // set the window size
-    void SetSize( const wxSize& size );

 
 

-    // set the window size and position
-    %name(SetDimensions) void SetSize( int x, int y, int width, int height,
-                                       int sizeFlags = wxSIZE_AUTO );
+    DocDeclStr(
+        void , SetSize( const wxSize& size ),
+        "Sets the size of the window in pixels.", "");
+
+
+    DocDeclStrName(
+        void , SetSize( int x, int y, int width, int height,
+                        int sizeFlags = wxSIZE_AUTO ),
+        "Sets the position and size of the window in pixels.  The sizeFlags
+parameter indicates the interpretation of the other params if they are
+equal to -1.
+
+    ========================  ======================================
+    wx.SIZE_AUTO              A -1 indicates that a class-specific
+                              default should be used.
+    wx.SIZE_USE_EXISTING      Axisting dimensions should be used if
+                              -1 values are supplied.
+    wxSIZE_ALLOW_MINUS_ONE    Allow dimensions of -1 and less to be
+                              interpreted as real dimensions, not
+                              default values.
+    ========================  ======================================
+", "",
+        SetDimensions);
+    

 
 

-    // set the window size and position with a wxRect
-    %name(SetRect) void SetSize(const wxRect& rect, int sizeFlags = wxSIZE_AUTO);
+    DocDeclStrName(
+        void , SetSize(const wxRect& rect, int sizeFlags = wxSIZE_AUTO),
+        "Sets the position and size of the window in pixels using a wx.Rect.", "",
+        SetRect);
+    

 
 

-    // set window size
-    %name(SetSizeWH)void SetSize( int width, int height );
+    DocDeclStrName(
+        void , SetSize( int width, int height ),
+        "Sets the size of the window in pixels.", "",
+        SetSizeWH);
+    

 
 

-    // set window position
-    void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING);
+    DocDeclStr(
+        void , Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING),
+        "Moves the window to the given position.", "");
+    

     %pythoncode { SetPosition = Move }
 
     %pythoncode { SetPosition = Move }
 

-    // set window position
-    %name(MoveXY) void Move(int x, int y, int flags = wxSIZE_USE_EXISTING);

 
 

-    // Z-order
-    virtual void Raise();
-    virtual void Lower();
+    DocDeclStrName(
+        void , Move(int x, int y, int flags = wxSIZE_USE_EXISTING),
+        "Moves the window to the given position.", "",
+        MoveXY);
+    
+    DocDeclStr(
+        void , SetBestFittingSize(const wxSize& size=wxDefaultSize),
+        "A 'Smart' SetSize that will fill in default size components with the
+window's *best size* values.  Also set's the minsize for use with sizers.", "");
+    
+
+    
+    DocDeclStr(
+        virtual void , Raise(),
+        "Raises the window to the top of the window hierarchy.  In current
+version of wxWidgets this works both for manage and child windows.", "");
+    
+    DocDeclStr(
+        virtual void , Lower(),
+        "Lowers the window to the bottom of the window hierarchy.  In current
+version of wxWidgets this works both for manage and child windows.", "");
+    

 
 

+    

     // client size is the size of the area available for subwindows
     // client size is the size of the area available for subwindows

+    DocStr(SetClientSize,
+           "This sets the size of the window client area in pixels. Using this
+function to size a window tends to be more device-independent than
+wx.Window.SetSize, since the application need not worry about what
+dimensions the border or title bar have when trying to fit the window
+around panel items, for example.", "");

     void SetClientSize( const wxSize& size );
     void SetClientSize( const wxSize& size );

-    %name(SetClientSizeWH) void SetClientSize( int width, int height );
-    %name(SetClientRect) void SetClientSize(const wxRect& rect);
+    %Rename(SetClientSizeWH, void,  SetClientSize( int width, int height ));
+    %Rename(SetClientRect,  void,  SetClientSize(const wxRect& rect));

 
 
     DocStr(GetPosition,   // sets the docstring for both
 
 
     DocStr(GetPosition,   // sets the docstring for both

-           "Get the window's position.");
-    wxPoint GetPosition();
+           "Get the window's position.  Notice that the position is in client
+coordinates for child windows and screen coordinates for the top level
+ones, use `GetScreenPosition` if you need screen coordinates for all
+kinds of windows.", "");
+    wxPoint GetPosition() const;

 
     DocDeclAName(
 
     DocDeclAName(

-        void, GetPosition(int *OUTPUT, int *OUTPUT),
+        void, GetPosition(int *OUTPUT, int *OUTPUT) const,

         "GetPositionTuple() -> (x,y)",
         GetPositionTuple);
 
         "GetPositionTuple() -> (x,y)",
         GetPositionTuple);
 

+    
+    DocStr(GetScreenPosition,   // sets the docstring for both
+           "Get the position of the window in screen coordinantes.", "");
+    wxPoint GetScreenPosition() const;
+    DocDeclAName(
+        void, GetScreenPosition(int *OUTPUT, int *OUTPUT) const,
+        "GetScreenPositionTuple() -> (x,y)",
+        GetScreenPositionTuple);
+
+    DocDeclStr(
+        wxRect , GetScreenRect() const,
+        "Returns the size and position of the window in screen coordinantes as
+a `wx.Rect` object.", "
+:see: `GetRect`, `GetScreenPosition`");
+    

    
    

-    DocStr(GetSize, "Get the window size.");
+    DocStr(GetSize, "Get the window size.", "");

     wxSize GetSize() const;
     DocDeclAName(
         void, GetSize( int *OUTPUT, int *OUTPUT ) const,
     wxSize GetSize() const;
     DocDeclAName(
         void, GetSize( int *OUTPUT, int *OUTPUT ) const,


@@ -147,28 +514,44 @@ public:
         GetSizeTuple);
     
     
         GetSizeTuple);
     
     

-    // get the window position and size
-    wxRect GetRect() const;

 
 

-    DocStr(GetClientSize, "Get the window's client size.");
+    DocDeclStr(
+        wxRect , GetRect() const,
+        "Returns the size and position of the window as a `wx.Rect` object.", "");
+    
+
+    DocStr(GetClientSize,
+           "This gets the size of the window's 'client area' in pixels. The client
+area is the area which may be drawn on by the programmer, excluding
+title bar, border, scrollbars, etc.", "");

     wxSize GetClientSize() const;
     DocDeclAName(
         void, GetClientSize( int *OUTPUT, int *OUTPUT ) const,
         "GetClientSizeTuple() -> (width, height)",
         GetClientSizeTuple);
 
     wxSize GetClientSize() const;
     DocDeclAName(
         void, GetClientSize( int *OUTPUT, int *OUTPUT ) const,
         "GetClientSizeTuple() -> (width, height)",
         GetClientSizeTuple);
 

+    

 
 

-    // get the origin of the client area of the window relative to the
-    // window top left corner (the client area may be shifted because of
-    // the borders, scrollbars, other decorations...)
-    virtual wxPoint GetClientAreaOrigin() const;
+    DocDeclStr(
+        virtual wxPoint , GetClientAreaOrigin() const,
+        "Get the origin of the client area of the window relative to the
+window's top left corner (the client area may be shifted because of
+the borders, scrollbars, other decorations...)", "");
+    

 
 

-    // get the client rectangle in window (i.e. client) coordinates
-    wxRect GetClientRect() const;
+    DocDeclStr(
+        wxRect , GetClientRect() const,
+        "Get the client area position and size as a `wx.Rect` object.", "");
+    

 
 

+    

     DocStr(GetBestSize,
     DocStr(GetBestSize,

-           "Get the size best suited for the window (in fact, minimal acceptable size\n"
-           "using which it will still look \"nice\")");
+           "This function returns the best acceptable minimal size for the
+window, if applicable. For example, for a static text control, it will
+be the minimal size such that the control label is not truncated. For
+windows containing subwindows (suzh aswx.Panel), the size returned by
+this function will be the same as the size the window would have had
+after calling Fit.", "");

     wxSize GetBestSize() const;
     DocDeclAName(
         void, GetBestSize(int *OUTPUT, int *OUTPUT) const,
     wxSize GetBestSize() const;
     DocDeclAName(
         void, GetBestSize(int *OUTPUT, int *OUTPUT) const,


@@ -176,65 +559,158 @@ public:
         GetBestSizeTuple);
     
 
         GetBestSizeTuple);
     
 

-    // There are times (and windows) where 'Best' size and 'Min' size
-    // are vastly out of sync.  This should be remedied somehow, but in
-    // the meantime, this method will return the larger of BestSize
-    // (the window's smallest legible size), and any user specified
-    // MinSize hint.
-    wxSize GetAdjustedBestSize() const;
+    DocDeclStr(
+        void , InvalidateBestSize(),
+        "Reset the cached best size value so it will be recalculated the next
+time it is needed.", "");

 
 

+    DocDeclStr(
+        void , CacheBestSize(const wxSize& size) const,
+        "Cache the best size so it doesn't need to be calculated again, (at least until
+some properties of the window change.)", "");

 
 

-    // the generic center function - centers the window on parent by
-    // default or on screen if it doesn't have parent or
-    // wxCENTER_ON_SCREEN flag is given
-    void Center( int direction = wxBOTH );
-    %pythoncode { Centre = Center }
+    
+    DocDeclStr(
+        wxSize , GetBestFittingSize() const,
+        "This function will merge the window's best size into the window's
+minimum size, giving priority to the min size components, and returns
+the results.
+", "");
+    

 
 

-    // center on screen (only works for top level windows)
-    void CenterOnScreen(int dir = wxBOTH);
-    %pythoncode { CentreOnScreen = CenterOnScreen }
+    DocDeclStr(
+        wxSize , GetAdjustedBestSize() const,
+        "This method is similar to GetBestSize, except in one
+thing. GetBestSize should return the minimum untruncated size of the
+window, while this method will return the largest of BestSize and any
+user specified minimum size. ie. it is the minimum size the window
+should currently be drawn at, not the minimal size it can possibly
+tolerate.", "");
+    
+
+
+
+    DocDeclStr(
+        void , Center( int direction = wxBOTH ),
+        "Centers the window.  The parameter specifies the direction for
+cetering, and may be wx.HORIZONTAL, wx.VERTICAL or wx.BOTH. It may
+also include wx.CENTER_ON_SCREEN flag if you want to center the window
+on the entire screen and not on its parent window.  If it is a
+top-level window and has no parent then it will always be centered
+relative to the screen.", "");    
+    %pythoncode { Centre = Center }

 
 

-    // center with respect to the the parent window
-    void CenterOnParent(int dir = wxBOTH);
+    
+    DocDeclStr(
+        void , CenterOnParent(int dir = wxBOTH),
+        "Center with respect to the the parent window", "");

     %pythoncode { CentreOnParent = CenterOnParent }
 
     %pythoncode { CentreOnParent = CenterOnParent }
 

+    

 
 

-    // set window size to wrap around its children
-    virtual void Fit();
+    DocDeclStr(
+        virtual void , Fit(),
+        "Sizes the window so that it fits around its subwindows. This function
+won't do anything if there are no subwindows and will only really work
+correctly if sizers are used for the subwindows layout. Also, if the
+window has exactly one subwindow it is better (faster and the result
+is more precise as Fit adds some margin to account for fuzziness of
+its calculations) to call window.SetClientSize(child.GetSize())
+instead of calling Fit.", "");
+    

 
 

-    // set virtual size to satisfy children
-    virtual void FitInside();
+    DocDeclStr(
+        virtual void , FitInside(),
+        "Similar to Fit, but sizes the interior (virtual) size of a
+window. Mainly useful with scrolled windows to reset scrollbars after
+sizing changes that do not trigger a size event, and/or scrolled
+windows without an interior sizer. This function similarly won't do
+anything if there are no subwindows.", "");
+    

 
 

-    // set min/max size of the window
+    
+    DocStr(SetSizeHints,
+        "Allows specification of minimum and maximum window sizes, and window
+size increments. If a pair of values is not set (or set to -1), the
+default values will be used.  If this function is called, the user
+will not be able to size the window outside the given bounds (if it is
+a top-level window.)  Sizers will also inspect the minimum window size
+and will use that value if set when calculating layout.
+
+The resizing increments are only significant under Motif or Xt.", "
+
+:see: `GetMinSize`, `GetMaxSize`, `SetMinSize`, `SetMaxSize`
+");

     virtual void SetSizeHints( int minW, int minH,
                                int maxW = -1, int maxH = -1,
                                int incW = -1, int incH = -1 );
     virtual void SetSizeHints( int minW, int minH,
                                int maxW = -1, int maxH = -1,
                                int incW = -1, int incH = -1 );

+    %Rename(SetSizeHintsSz, void,  SetSizeHints( const wxSize& minSize,
+                                                 const wxSize& maxSize=wxDefaultSize,
+                                                 const wxSize& incSize=wxDefaultSize));

 
 

+    
+    DocStr(SetVirtualSizeHints,
+        "Allows specification of minimum and maximum virtual window sizes. If a
+pair of values is not set (or set to -1), the default values will be
+used.  If this function is called, the user will not be able to size
+the virtual area of the window outside the given bounds.", "");

     virtual void SetVirtualSizeHints( int minW, int minH,
                                       int maxW = -1, int maxH = -1 );
     virtual void SetVirtualSizeHints( int minW, int minH,
                                       int maxW = -1, int maxH = -1 );

+    %Rename(SetVirtualSizeHintsSz, void,  SetVirtualSizeHints(
+                const wxSize& minSize, const wxSize& maxSize=wxDefaultSize));

 
 

-    virtual int GetMinWidth() const;
-    virtual int GetMinHeight() const;
-    int GetMaxWidth() const;
-    int GetMaxHeight() const;

 
 

+    
+    DocDeclStr(
+        virtual wxSize , GetMaxSize() const,
+        "", "");
+    
+    DocDeclStr(
+        virtual wxSize , GetMinSize() const,
+        "", "");
+    
+    DocDeclStr(
+        void , SetMinSize(const wxSize& minSize),
+        "A more convenient method than `SetSizeHints` for setting just the
+min size.", "");
+    
+    DocDeclStr(
+        void , SetMaxSize(const wxSize& maxSize),
+        "A more convenient method than `SetSizeHints` for setting just the
+max size.", "");
+    

 
 

-    // Override this method to control the values given to Sizers etc.
-    virtual wxSize GetMaxSize() const;

 
 

+    DocDeclStr(
+        virtual int , GetMinWidth() const,
+        "", "");
+    
+    DocDeclStr(
+        virtual int , GetMinHeight() const,
+        "", "");
+    
+    DocDeclStr(
+        int , GetMaxWidth() const,
+        "", "");
+    
+    DocDeclStr(
+        int , GetMaxHeight() const,
+        "", "");
+    
+    

     
     DocStr(SetVirtualSize,
     
     DocStr(SetVirtualSize,

-           "Set the the virtual size of a window.  For most windows this is just the\n"
-           "client area of the window, but for some like scrolled windows it is more or\n"
-           "less independent of the screen window size.");
+           "Set the the virtual size of a window in pixels.  For most windows this
+is just the client area of the window, but for some like scrolled
+windows it is more or less independent of the screen window size.", "");

     void SetVirtualSize(const wxSize& size );
     void SetVirtualSize(const wxSize& size );

-    %name(SetVirtualSizeWH) void SetVirtualSize( int w, int h );
+    %Rename(SetVirtualSizeWH, void,  SetVirtualSize( int w, int h ));

 
     
     DocStr(GetVirtualSize,
 
     
     DocStr(GetVirtualSize,

-           "Get the the virtual size of the window.  For most windows this is just\n" 
-           "the client area of the window, but for some like scrolled windows it is\n"
-           "more or less independent of the screen window size.");           
+           "Get the the virtual size of the window in pixels.  For most windows
+this is just the client area of the window, but for some like scrolled
+windows it is more or less independent of the screen window size.", "");           

     wxSize GetVirtualSize() const;
     DocDeclAName(
         void, GetVirtualSize( int *OUTPUT, int *OUTPUT ) const,
     wxSize GetVirtualSize() const;
     DocDeclAName(
         void, GetVirtualSize( int *OUTPUT, int *OUTPUT ) const,


@@ -250,148 +726,361 @@ public:
 //     virtual wxSize DoGetVirtualSize() const; // { return m_virtualSize; }
 
 
 //     virtual wxSize DoGetVirtualSize() const; // { return m_virtualSize; }
 
 

-    // Return the largest of ClientSize and BestSize (as determined
-    // by a sizer, interior children, or other means)
-    virtual wxSize GetBestVirtualSize() const;
+    DocDeclStr(
+        virtual wxSize , GetBestVirtualSize() const,
+        "Return the largest of ClientSize and BestSize (as determined by a
+sizer, interior children, or other means)", "");
+    

 
 
 
 

+//     void SetScrollHelper( wxScrollHelper *sh );
+//     wxScrollHelper *GetScrollHelper();
+    

 
     // window state
     // ------------
 
 
     // window state
     // ------------
 

-    // returns True if window was shown/hidden, False if the nothing was
-    // done (window was already shown/hidden)
-    virtual bool Show( bool show = True );
-    bool Hide();
+    DocDeclStr(
+        virtual bool , Show( bool show = true ),
+        "Shows or hides the window. You may need to call Raise for a top level
+window if you want to bring it to top, although this is not needed if
+Show is called immediately after the frame creation.  Returns True if
+the window has been shown or hidden or False if nothing was done
+because it already was in the requested state.", "");
+    
+    DocDeclStr(
+        bool , Hide(),
+        "Equivalent to calling Show(False).", "");
+    

 
 

-    // returns True if window was enabled/disabled, False if nothing done
-    virtual bool Enable( bool enable = True );
-    bool Disable();
+    DocDeclStr(
+        virtual bool , Enable( bool enable = true ),
+        "Enable or disable the window for user input. Note that when a parent
+window is disabled, all of its children are disabled as well and they
+are reenabled again when the parent is.  Returns true if the window
+has been enabled or disabled, false if nothing was done, i.e. if the
+window had already been in the specified state.", "");
+    
+    DocDeclStr(
+        bool , Disable(),
+        "Disables the window, same as Enable(false).", "");
+    

 
 

-    bool IsShown() const;
-    bool IsEnabled() const;
+    DocDeclStr(
+        bool , IsShown() const,
+        "Returns true if the window is shown, false if it has been hidden.", "");
+    
+    DocDeclStr(
+        bool , IsEnabled() const,
+        "Returns true if the window is enabled for input, false otherwise.", "");
+
+    DocDeclStr(
+        virtual bool , IsShownOnScreen() const,
+        "Returns ``True`` if the window is physically visible on the screen,
+i.e. it is shown and all its parents up to the toplevel window are
+shown as well.", "");
+    
+    

 
 

-    // get/set window style (setting style won't update the window and so
-    // is only useful for internal usage)
-    virtual void SetWindowStyleFlag( long style );
-    virtual long GetWindowStyleFlag() const;

 
 

-    // get/set window style (setting style won't update the window and so
-    // is only useful for internal usage)
-    void SetWindowStyle( long style );
-    long GetWindowStyle() const;
+    DocDeclStr(
+        virtual void , SetWindowStyleFlag( long style ),
+        "Sets the style of the window. Please note that some styles cannot be
+changed after the window creation and that Refresh() might need to be
+called after changing the others for the change to take place
+immediately.", "");
+    
+    DocDeclStr(
+        virtual long , GetWindowStyleFlag() const,
+        "Gets the window style that was passed to the constructor or Create
+method.", "");    

 
 

-    bool HasFlag(int flag) const;
-    virtual bool IsRetained() const;
+    %pythoncode { SetWindowStyle = SetWindowStyleFlag; GetWindowStyle = GetWindowStyleFlag }
+    
+  
+    DocDeclStr(
+        bool , HasFlag(int flag) const,
+        "Test if the given style is set for this window.", "");
+    
+
+    DocDeclStr(
+        virtual bool , IsRetained() const,
+        "Returns true if the window is retained, false otherwise.  Retained
+windows are only available on X platforms.", "");
+    
+
+
+    DocDeclStr(
+        virtual void , SetExtraStyle(long exStyle),
+        "Sets the extra style bits for the window.  Extra styles are the less
+often used style bits which can't be set with the constructor or with
+SetWindowStyleFlag()", "");
+    
+    DocDeclStr(
+        long , GetExtraStyle() const,
+        "Returns the extra style bits for the window.", "");
+    
+
+    
+    DocDeclStr(
+        virtual void , MakeModal(bool modal = true),
+        "Disables all other windows in the application so that the user can
+only interact with this window.  Passing False will reverse this
+effect.", "");
+    

 
 

-    // extra style: the less often used style bits which can't be set with
-    // SetWindowStyleFlag()
-    virtual void SetExtraStyle(long exStyle);
-    long GetExtraStyle() const;
+    
+    DocDeclStr(
+        virtual void , SetThemeEnabled(bool enableTheme),
+        "This function tells a window if it should use the system's \"theme\"
+ code to draw the windows' background instead if its own background
+ drawing code. This will only have an effect on platforms that support
+ the notion of themes in user defined windows. One such platform is
+ GTK+ where windows can have (very colourful) backgrounds defined by a
+ user's selected theme.
+
+Dialogs, notebook pages and the status bar have this flag set to true
+by default so that the default look and feel is simulated best.", "");
+    
+    DocDeclStr(
+        virtual bool , GetThemeEnabled() const,
+        "Return the themeEnabled flag.", "");
+    

 
 

-    // make the window modal (all other windows unresponsive)
-    virtual void MakeModal(bool modal = True);
+// TODO with directors    
+//     // controls by default inherit the colours of their parents, if a
+//     // particular control class doesn't want to do it, it can override
+//     // ShouldInheritColours() to return False
+//     virtual bool ShouldInheritColours() const;

 
 

-    virtual void SetThemeEnabled(bool enableTheme);
-    virtual bool GetThemeEnabled() const;

 
 

-    // controls by default inherit the colours of their parents, if a
-    // particular control class doesn't want to do it, it can override
-    // ShouldInheritColours() to return False
-    virtual bool ShouldInheritColours() const;

 
 

+    

 
     // focus and keyboard handling
     // ---------------------------
 
 
     // focus and keyboard handling
     // ---------------------------
 

-    // set focus to this window
-    virtual void SetFocus();
+    
+    DocDeclStr(
+        virtual void , SetFocus(),
+        "Set's the focus to this window, allowing it to receive keyboard input.", "");
+    
+    DocDeclStr(
+        virtual void , SetFocusFromKbd(),
+        "Set focus to this window as the result of a keyboard action.  Normally
+only called internally.", "");
+    
+
+    
+    DocDeclStr(
+        static wxWindow *, FindFocus(),
+        "Returns the window or control that currently has the keyboard focus,
+or None.", "");
+    
+
+    DocDeclStr(
+        virtual bool , AcceptsFocus() const,
+        "Can this window have focus?", "");
+    

 
 

-    // set focus to this window as the result of a keyboard action
-    virtual void SetFocusFromKbd();
+    DocDeclStr(
+        virtual bool , AcceptsFocusFromKeyboard() const,
+        "Can this window be given focus by keyboard navigation? if not, the
+only way to give it focus (provided it accepts it at all) is to click
+it.", "");
+    

 
 

-    // return the window which currently has the focus or NULL
-    static wxWindow *FindFocus();

 
 

-    // can this window have focus?
-    virtual bool AcceptsFocus() const;

 
 

-    // can this window be given focus by keyboard navigation? if not, the
-    // only way to give it focus (provided it accepts it at all) is to
-    // click it
-    virtual bool AcceptsFocusFromKeyboard() const;
+    DocDeclAStr(
+        virtual bool , Navigate(int flags = wxNavigationKeyEvent::IsForward),
+        "Navigate(self, int flags=NavigationKeyEvent.IsForward) -> bool",
+        "Does keyboard navigation from this window to another, by sending a
+`wx.NavigationKeyEvent`.", "
+ 
+    :param flags: A combination of the ``IsForward`` or ``IsBackward``
+        and the ``WinChange`` values in the `wx.NavigationKeyEvent`
+        class, which determine if the navigation should be in forward
+        or reverse order, and if it should be able to cross parent
+        window boundaries, such as between notebook pages or MDI child
+        frames.  Typically the status of the Shift key (for forward or
+        backward) or the Control key (for WinChange) would be used to
+        determine how to set the flags.
+
+One situation in which you may wish to call this method is from a text
+control custom keypress handler to do the default navigation behaviour
+for the tab key, since the standard default behaviour for a multiline
+text control with the wx.TE_PROCESS_TAB style is to insert a tab and
+not navigate to the next control.");

 
 

-    // get the default child of this parent, i.e. the one which is
-    // activated by pressing <Enter>
-    virtual wxWindow *GetDefaultItem() const;
+    
+
+    DocDeclStr(
+        void , MoveAfterInTabOrder(wxWindow *win),
+        "Moves this window in the tab navigation order after the specified
+sibling window.  This means that when the user presses the TAB key on
+that other window, the focus switches to this window.
+
+The default tab order is the same as creation order.  This function
+and `MoveBeforeInTabOrder` allow to change it after creating all the
+windows.
+", "");
+
+    
+    DocDeclStr(
+        void , MoveBeforeInTabOrder(wxWindow *win),
+        "Same as `MoveAfterInTabOrder` except that it inserts this window just
+before win instead of putting it right after it.", "");
+    
+
+    

 
 

-    // set this child as default, return the old default
-    virtual wxWindow *SetDefaultItem(wxWindow * WXUNUSED(child));

 
 

-    // set this child as temporary default
-    virtual void SetTmpDefaultItem(wxWindow * WXUNUSED(win));

 
 
 
     // parent/children relations
     // -------------------------
 
 
 
 
     // parent/children relations
     // -------------------------
 

-    // get the list of children
+

     //wxWindowList& GetChildren();  // TODO: Do a typemap or a wrapper for wxWindowList
     %extend {
     //wxWindowList& GetChildren();  // TODO: Do a typemap or a wrapper for wxWindowList
     %extend {

+        DocStr(GetChildren,
+               "Returns a list of the window's children.  NOTE: Currently this is a
+copy of the child window list maintained by the window, so the return
+value of this function is only valid as long as the window's children
+do not change.", "");

         PyObject* GetChildren() {
             wxWindowList& list = self->GetChildren();
             return wxPy_ConvertList(&list);
         }
     }
 
         PyObject* GetChildren() {
             wxWindowList& list = self->GetChildren();
             return wxPy_ConvertList(&list);
         }
     }
 

-    // get the parent or the parent of the parent
-    wxWindow *GetParent() const;
-    wxWindow *GetGrandParent() const;
+    DocDeclStr(
+        wxWindow *, GetParent() const,
+        "Returns the parent window of this window, or None if there isn't one.", "");
+    
+    DocDeclStr(
+        wxWindow *, GetGrandParent() const,
+        "Returns the parent of the parent of this window, or None if there
+isn't one.", "");
+    
+

 
 

-    // is this window a top level one?
-    virtual bool IsTopLevel() const;
+    DocDeclStr(
+        virtual bool , IsTopLevel() const,
+        "Returns true if the given window is a top-level one. Currently all
+frames and dialogs are always considered to be top-level windows (even
+if they have a parent window).", "");
+    

 
     // change the real parent of this window, return True if the parent
     // was changed, False otherwise (error or newParent == oldParent)
 
     // change the real parent of this window, return True if the parent
     // was changed, False otherwise (error or newParent == oldParent)

-    virtual bool Reparent( wxWindow *newParent );
+    DocDeclStr(
+        virtual bool , Reparent( wxWindow *newParent ),
+        "Reparents the window, i.e the window will be removed from its current
+parent window (e.g. a non-standard toolbar in a wxFrame) and then
+re-inserted into another. Available on Windows and GTK.  Returns True
+if the parent was changed, False otherwise (error or newParent ==
+oldParent)", "");
+    

 
 

-    // implementation mostly
-    virtual void AddChild( wxWindow *child );
-    virtual void RemoveChild( wxWindow *child );
+    DocDeclStr(
+        virtual void , AddChild( wxWindow *child ),
+        "Adds a child window. This is called automatically by window creation
+functions so should not be required by the application programmer.", "");
+    
+    DocDeclStr(
+        virtual void , RemoveChild( wxWindow *child ),
+        "Removes a child window. This is called automatically by window
+deletion functions so should not be required by the application
+programmer.", "");

 
 
 
 

+    DocStr(SetDoubleBuffered,
+           "Currently wxGTK2 only.", "");
+#ifdef __WXGTK__
+    void SetDoubleBuffered(bool on);
+#else
+    %extend {
+        void SetDoubleBuffered(bool on) {}
+    }
+#endif
+

 
     // looking for windows
     // -------------------
 
 
     // looking for windows
     // -------------------
 

-    // find window among the descendants of this one either by id or by
-    // name (return NULL if not found)
-    %name(FindWindowById) wxWindow *FindWindow( long winid );
-    %name(FindWindowByName) wxWindow *FindWindow( const wxString& name );
+    DocDeclStrName(
+        wxWindow *, FindWindow( long winid ),
+        "Find a chld of this window by window ID", "",
+        FindWindowById);
+    
+    DocDeclStrName(
+        wxWindow *, FindWindow( const wxString& name ),
+        "Find a child of this window by name", "",
+        FindWindowByName);
+    

 
 
     // event handler stuff
     // -------------------
 
 
 
     // event handler stuff
     // -------------------
 

-    // get the current event handler
-    wxEvtHandler *GetEventHandler() const;
+    DocDeclStr(
+        wxEvtHandler *, GetEventHandler() const,
+        "Returns the event handler for this window. By default, the window is
+its own event handler.", "");
+    

 
 

-    // replace the event handler (allows to completely subclass the
-    // window)
-    void SetEventHandler( wxEvtHandler *handler );
+    DocDeclStr(
+        void , SetEventHandler( wxEvtHandler *handler ),
+        "Sets the event handler for this window.  An event handler is an object
+that is capable of processing the events sent to a window.  (In other
+words, is able to dispatch the events to handler function.)  By
+default, the window is its own event handler, but an application may
+wish to substitute another, for example to allow central
+implementation of event-handling for a variety of different window
+classes.
+
+It is usually better to use `wx.Window.PushEventHandler` since this sets
+up a chain of event handlers, where an event not handled by one event
+handler is handed off to the next one in the chain.", "");
+    

 
 

-    // push/pop event handler: allows to chain a custom event handler to
-    // alreasy existing ones
-    void PushEventHandler( wxEvtHandler *handler );
-    wxEvtHandler *PopEventHandler( bool deleteHandler = False );
+    DocDeclStr(
+        void , PushEventHandler( wxEvtHandler *handler ),
+        "Pushes this event handler onto the event handler stack for the window.
+An event handler is an object that is capable of processing the events
+sent to a window.  (In other words, is able to dispatch the events to
+handler function.)  By default, the window is its own event handler,
+but an application may wish to substitute another, for example to
+allow central implementation of event-handling for a variety of
+different window classes.
+
+wx.Window.PushEventHandler allows an application to set up a chain of
+event handlers, where an event not handled by one event handler is
+handed to the next one in the chain.  Use `wx.Window.PopEventHandler`
+to remove the event handler.  Ownership of the handler is *not* given
+to the window, so you should be sure to pop the handler before the
+window is destroyed and either let PopEventHandler destroy it, or call
+its Destroy method yourself.", "");
+
+    
+    DocDeclStr(
+        wxEvtHandler *, PopEventHandler( bool deleteHandler = false ),
+        "Removes and returns the top-most event handler on the event handler
+stack.  If deleteHandler is True then the wx.EvtHandler object will be
+destroyed after it is popped, and ``None`` will be returned instead.", "");
+    

 
 

-    // find the given handler in the event handler chain and remove (but
-    // not delete) it from the event handler chain, return True if it was
-    // found and False otherwise (this also results in an assert failure so
-    // this function should only be called when the handler is supposed to
-    // be there)
-    bool RemoveEventHandler(wxEvtHandler *handler);
+    DocDeclStr(
+        bool , RemoveEventHandler(wxEvtHandler *handler),
+        "Find the given handler in the event handler chain and remove (but not
+delete) it from the event handler chain, returns True if it was found
+and False otherwise (this also results in an assert failure so this
+function should only be called when the handler is supposed to be
+there.)", "");
+    

 
 
 
 
 
 


@@ -400,15 +1089,60 @@ public:
 
     // a window may have an associated validator which is used to control
     // user input
 
     // a window may have an associated validator which is used to control
     // user input

-    virtual void SetValidator( const wxValidator &validator );
-    virtual wxValidator *GetValidator();
+    DocDeclStr(
+        virtual void , SetValidator( const wxValidator &validator ),
+        "Deletes the current validator (if any) and sets the window validator,
+having called wx.Validator.Clone to create a new validator of this
+type.", "");
+    
+    DocDeclStr(
+        virtual wxValidator *, GetValidator(),
+        "Returns a pointer to the current validator for the window, or None if
+there is none.", "");
+
+
+    DocDeclStr(
+        virtual bool , Validate(),
+        "Validates the current values of the child controls using their
+validators.  If the window has wx.WS_EX_VALIDATE_RECURSIVELY extra
+style flag set, the method will also call Validate() of all child
+windows.  Returns false if any of the validations failed.", "");
+    
+
+    DocDeclStr(
+        virtual bool , TransferDataToWindow(),
+        "Transfers values to child controls from data areas specified by their
+validators.  If the window has wx.WS_EX_VALIDATE_RECURSIVELY extra
+style flag set, the method will also call TransferDataToWindow() of
+all child windows.", "");
+    
+    DocDeclStr(
+        virtual bool , TransferDataFromWindow(),
+        "Transfers values from child controls to data areas specified by their
+validators. Returns false if a transfer failed.  If the window has
+wx.WS_EX_VALIDATE_RECURSIVELY extra style flag set, the method will
+also call TransferDataFromWindow() of all child windows.", "");
+    
+
+    DocDeclStr(
+        virtual void , InitDialog(),
+        "Sends an EVT_INIT_DIALOG event, whose handler usually transfers data
+to the dialog via validators.", "");
+    
+    

 
 
     // accelerators
     // ------------
 
 
 
     // accelerators
     // ------------
 

-    virtual void SetAcceleratorTable( const wxAcceleratorTable& accel );
-    wxAcceleratorTable *GetAcceleratorTable();
+    DocDeclStr(
+        virtual void , SetAcceleratorTable( const wxAcceleratorTable& accel ),
+        "Sets the accelerator table for this window.", "");
+    
+    DocDeclStr(
+        wxAcceleratorTable *, GetAcceleratorTable(),
+        "Gets the accelerator table for this window.", "");
+    

 
 
 
 
 
 


@@ -416,20 +1150,30 @@ public:
     // hot keys (system wide accelerators)
     // -----------------------------------
     %extend {
     // hot keys (system wide accelerators)
     // -----------------------------------
     %extend {

-        // hot keys (system wide accelerators)
+        DocStr(RegisterHotKey,
+               "Registers a system wide hotkey. Every time the user presses the hotkey
+registered here, this window will receive a hotkey event. It will
+receive the event even if the application is in the background and
+does not have the input focus because the user is working with some
+other application.  To bind an event handler function to this hotkey
+use EVT_HOTKEY with an id equal to hotkeyId.  Returns True if the
+hotkey was registered successfully.", "");

         bool RegisterHotKey(int hotkeyId, int modifiers, int keycode) {
         bool RegisterHotKey(int hotkeyId, int modifiers, int keycode) {

-        #if wxUSE_HOTKEY
+        %#if wxUSE_HOTKEY

             return self->RegisterHotKey(hotkeyId, modifiers, keycode);
             return self->RegisterHotKey(hotkeyId, modifiers, keycode);

-        #else
-            return False;
-        #endif
+        %#else
+            return false;
+        %#endif

         }
 
         }
 

+        
+        DocStr(UnregisterHotKey,
+               "Unregisters a system wide hotkey.", "");

         bool UnregisterHotKey(int hotkeyId) {
         #if wxUSE_HOTKEY
             return self->UnregisterHotKey(hotkeyId);
         #else
         bool UnregisterHotKey(int hotkeyId) {
         #if wxUSE_HOTKEY
             return self->UnregisterHotKey(hotkeyId);
         #else

-            return False;
+            return false;

         #endif
         }
     }
         #endif
         }
     }


@@ -439,121 +1183,373 @@ public:
     // "dialog units" translations
     // ---------------------------
 
     // "dialog units" translations
     // ---------------------------
 

-    %name(ConvertDialogPointToPixels) wxPoint ConvertDialogToPixels(const wxPoint& pt);
-    %name(ConvertDialogSizeToPixels)  wxSize  ConvertDialogToPixels(const wxSize& sz);
+    DocStr(ConvertDialogToPixels,
+           "Converts a point or size from dialog units to pixels.  Dialog units
+are used for maintaining a dialog's proportions even if the font
+changes. For the x dimension, the dialog units are multiplied by the
+average character width and then divided by 4. For the y dimension,
+the dialog units are multiplied by the average character height and
+then divided by 8.", "");
+    %Rename(ConvertDialogPointToPixels, wxPoint, ConvertDialogToPixels(const wxPoint& pt));
+    %Rename(ConvertDialogSizeToPixels,  wxSize,  ConvertDialogToPixels(const wxSize& sz));
+    %Rename(DLG_PNT, wxPoint, ConvertDialogToPixels(const wxPoint& pt));
+    %Rename(DLG_SZE, wxSize,  ConvertDialogToPixels(const wxSize& sz));

 
 

-    %name(DLG_PNT) wxPoint ConvertDialogToPixels(const wxPoint& pt);
-    %name(DLG_SZE) wxSize  ConvertDialogToPixels(const wxSize& sz);

 
 

-    %name(ConvertPixelPointToDialog) wxPoint ConvertPixelsToDialog(const wxPoint& pt);
-    %name(ConvertPixelSizeToDialog)  wxSize  ConvertPixelsToDialog(const wxSize& sz);
+    DocStr(ConvertPixelPointToDialog,
+           "Converts a point or size from pixels to dialog units.  Dialog units
+are used for maintaining a dialog's proportions even if the font
+changes. For the x dimension, the dialog units are multiplied by the
+average character width and then divided by 4. For the y dimension,
+the dialog units are multiplied by the average character height and
+then divided by 8.", "");
+    %Rename(ConvertPixelPointToDialog, wxPoint, ConvertPixelsToDialog(const wxPoint& pt));
+    %Rename(ConvertPixelSizeToDialog,  wxSize,  ConvertPixelsToDialog(const wxSize& sz));

 
 
 
     // mouse functions
     // ---------------
 
 
 
 
     // mouse functions
     // ---------------
 

-    // move the mouse to the specified position
-    virtual void WarpPointer(int x, int y);
+    DocDeclStr(
+        virtual void , WarpPointer(int x, int y),
+        "Moves the pointer to the given position on the window.

 
 

-    // start or end mouse capture, these functions maintain the stack of
-    // windows having captured the mouse and after calling ReleaseMouse()
-    // the mouse is not released but returns to the window which had had
-    // captured it previously (if any)
-    void CaptureMouse();
-    void ReleaseMouse();
+NOTE: This function is not supported under Mac because Apple Human
+Interface Guidelines forbid moving the mouse cursor programmatically.", "");
+    

 
 

-    // get the window which currently captures the mouse or NULL
-    static wxWindow *GetCapture();
+    DocDeclStr(
+        void , CaptureMouse(),
+        "Directs all mouse input to this window. Call wx.Window.ReleaseMouse to
+release the capture.
+
+Note that wxWindows maintains the stack of windows having captured the
+mouse and when the mouse is released the capture returns to the window
+which had had captured it previously and it is only really released if
+there were no previous window. In particular, this means that you must
+release the mouse as many times as you capture it, unless the window
+receives the `wx.MouseCaptureLostEvent` event.
+ 
+Any application which captures the mouse in the beginning of some
+operation *must* handle `wx.MouseCaptureLostEvent` and cancel this
+operation when it receives the event. The event handler must not
+recapture mouse.", "");
+    
+    DocDeclStr(
+        void , ReleaseMouse(),
+        "Releases mouse input captured with wx.Window.CaptureMouse.", "");
+    

 
 

-    // does this window have the capture?
-    virtual bool HasCapture() const;
+    DocDeclStr(
+        static wxWindow *, GetCapture(),
+        "Returns the window which currently captures the mouse or None", "");
+    

 
 

+    DocDeclStr(
+        virtual bool , HasCapture() const,
+        "Returns true if this window has the current mouse capture.", "");
+    

 
 
 
 

+    
+

     // painting the window
     // -------------------
 
     // painting the window
     // -------------------
 

-    // mark the specified rectangle (or the whole window) as "dirty" so it
-    // will be repainted
-    virtual void Refresh( bool eraseBackground = True,
-                          const wxRect *rect = NULL );
+    DocDeclStr(
+        virtual void , Refresh( bool eraseBackground = true,
+                                const wxRect *rect = NULL ),
+        "Mark the specified rectangle (or the whole window) as \"dirty\" so it
+will be repainted.  Causes an EVT_PAINT event to be generated and sent
+to the window.", "");
+    

 
 

-    // a less awkward wrapper for Refresh
-    void RefreshRect(const wxRect& rect);
+    DocDeclStr(
+        void , RefreshRect(const wxRect& rect, bool eraseBackground = true),
+        "Redraws the contents of the given rectangle: the area inside it will
+be repainted.  This is the same as Refresh but has a nicer syntax.", "");
+    
+
+    DocDeclStr(
+        virtual void , Update(),
+        "Calling this method immediately repaints the invalidated area of the
+window instead of waiting for the EVT_PAINT event to happen, (normally
+this would usually only happen when the flow of control returns to the
+event loop.)  Notice that this function doesn't refresh the window and
+does nothing if the window has been already repainted.  Use Refresh
+first if you want to immediately redraw the window (or some portion of
+it) unconditionally.", "");
+    

 
 

-    // repaint all invalid areas of the window immediately
-    virtual void Update();
+    DocDeclStr(
+        virtual void , ClearBackground(),
+        "Clears the window by filling it with the current background
+colour. Does not cause an erase background event to be generated.", "");
+    

 
 

-    // clear the window background
-    virtual void ClearBackground();

 
 

-    // freeze the window: don't redraw it until it is thawed
-    virtual void Freeze();
+    DocDeclStr(
+        virtual void , Freeze(),
+        "Freezes the window or, in other words, prevents any updates from
+taking place on screen, the window is not redrawn at all. Thaw must be
+called to reenable window redrawing.  Calls to Freeze/Thaw may be
+nested, with the actual Thaw being delayed until all the nesting has
+been undone.

 
 

-    // thaw the window: redraw it after it had been frozen
-    virtual void Thaw();
+This method is useful for visual appearance optimization (for example,
+it is a good idea to use it before inserting large amount of text into
+a wxTextCtrl under wxGTK) but is not implemented on all platforms nor
+for all controls so it is mostly just a hint to wxWindows and not a
+mandatory directive.", "");

 
 

-    // adjust DC for drawing on this window
-    virtual void PrepareDC( wxDC & WXUNUSED(dc) );
+    
+    DocDeclStr(
+        virtual bool , IsFrozen() const,
+        "Returns ``True`` if the window has been frozen and not thawed yet.

 
 

-    // the update region of the window contains the areas which must be
-    // repainted by the program
-    wxRegion& GetUpdateRegion();
+:see: `Freeze` and `Thaw`", "");
+    

 
 

-    // get the update rectangle region bounding box in client coords
-    wxRect GetUpdateClientRect() const;
+    
+    DocDeclStr(
+        virtual void , Thaw(),
+        "Reenables window updating after a previous call to Freeze.  Calls to
+Freeze/Thaw may be nested, so Thaw must be called the same number of
+times that Freeze was before the window will be updated.", "");
+    

 
 

-    // these functions verify whether the given point/rectangle belongs to
-    // (or at least intersects with) the update region
+    DocDeclStr(
+        virtual void , PrepareDC( wxDC & dc ),
+        "Call this function to prepare the device context for drawing a
+scrolled image. It sets the device origin according to the current
+scroll position.", "");
+
+    DocDeclStr(
+        virtual bool , IsDoubleBuffered() const,
+        "Returns ``True`` if the window contents is double-buffered by the
+system, i.e. if any drawing done on the window is really done on a
+temporary backing surface and transferred to the screen all at once
+later.", "");
+    
+
+    DocDeclStr(
+        wxRegion& , GetUpdateRegion(),
+        "Returns the region specifying which parts of the window have been
+damaged. Should only be called within an EVT_PAINT handler.", "");
+    
+
+    DocDeclStr(
+        wxRect , GetUpdateClientRect() const,
+        "Get the update rectangle region bounding box in client coords.", "");
+    
+
+    DocStr(IsExposed,
+           "Returns true if the given point or rectangle area has been exposed
+since the last repaint. Call this in an paint event handler to
+optimize redrawing by only redrawing those areas, which have been
+exposed.", "");

     bool IsExposed( int x, int y, int w=1, int h=1 ) const;
     bool IsExposed( int x, int y, int w=1, int h=1 ) const;

-    %name(IsExposedPoint) bool IsExposed( const wxPoint& pt ) const;
-    %name(isExposedRect)  bool IsExposed( const wxRect& rect ) const;
+    %Rename(IsExposedPoint, bool, IsExposed( const wxPoint& pt ) const);
+    %Rename(IsExposedRect,  bool, IsExposed( const wxRect& rect ) const);

 
 
 
     // colours, fonts and cursors
     // --------------------------
 
 
 
 
     // colours, fonts and cursors
     // --------------------------
 

-    // set/retrieve the window colours (system defaults are used by
-    // default): Set functions return True if colour was changed
-    virtual bool SetBackgroundColour( const wxColour &colour );
-    virtual bool SetForegroundColour( const wxColour &colour );

 
 

-    wxColour GetBackgroundColour() const;
-    wxColour GetForegroundColour() const;
+    DocDeclStr(
+        virtual wxVisualAttributes , GetDefaultAttributes() const,
+        "Get the default attributes for an instance of this class.  This is
+useful if you want to use the same font or colour in your own control
+as in a standard control -- which is a much better idea than hard
+coding specific colours or fonts which might look completely out of
+place on the user's system, especially if it uses themes.", "");
+    
+
+    DocDeclStr(
+        static wxVisualAttributes ,
+        GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL),
+        "Get the default attributes for this class.  This is useful if you want
+to use the same font or colour in your own control as in a standard
+control -- which is a much better idea than hard coding specific
+colours or fonts which might look completely out of place on the
+user's system, especially if it uses themes.
+
+The variant parameter is only relevant under Mac currently and is
+ignore under other platforms. Under Mac, it will change the size of
+the returned font. See `wx.Window.SetWindowVariant` for more about
+this.", "");
+    
+    
+    DocDeclStr(
+        virtual bool , SetBackgroundColour( const wxColour &colour ),
+        "Sets the background colour of the window.  Returns True if the colour
+was changed.  The background colour is usually painted by the default
+EVT_ERASE_BACKGROUND event handler function under Windows and
+automatically under GTK.  Using `wx.NullColour` will reset the window
+to the default background colour.
+
+Note that setting the background colour may not cause an immediate
+refresh, so you may wish to call `ClearBackground` or `Refresh` after
+calling this function.
+
+Using this function will disable attempts to use themes for this
+window, if the system supports them.  Use with care since usually the
+themes represent the appearance chosen by the user to be used for all
+applications on the system.", "");
+
+    DocDeclStr(
+        void , SetOwnBackgroundColour(const wxColour& colour),
+        "", "");
+    
+
+    
+    DocDeclStr(
+        virtual bool , SetForegroundColour( const wxColour &colour ),
+        "Sets the foreground colour of the window.  Returns True is the colour
+was changed.  The interpretation of foreground colour is dependent on
+the window class; it may be the text colour or other colour, or it may
+not be used at all.", "");
+
+    DocDeclStr(
+        void , SetOwnForegroundColour(const wxColour& colour),
+        "", "");
+    
+
+    
+    DocDeclStr(
+        wxColour , GetBackgroundColour() const,
+        "Returns the background colour of the window.", "");
+    
+    DocDeclStr(
+        wxColour , GetForegroundColour() const,
+        "Returns the foreground colour of the window.  The interpretation of
+foreground colour is dependent on the window class; it may be the text
+colour or other colour, or it may not be used at all.", "");
+
+    DocDeclStr(
+        bool , InheritsBackgroundColour() const,
+        "", "");
+    
+    DocDeclStr(
+        bool , UseBgCol() const,
+        "", "");
+    
+    
+// TODO:
+//     // if the window shouldn't inherit its colour from the parent, override
+//     // this function to return true
+//     //
+//     // this is currently only used by wxMSW and wxUniv but should be useful for
+//     // the other ports too
+//     virtual bool ProvidesBackground() const;
+
+
+    // Set/get the background style.
+    // Pass one of wxBG_STYLE_SYSTEM, wxBG_STYLE_COLOUR, wxBG_STYLE_CUSTOM
+    DocDeclStr(
+        virtual bool , SetBackgroundStyle(wxBackgroundStyle style),
+        "Returns the background style of the window. The background style
+indicates how the background of the window is drawn.
+
+    ======================  ========================================
+    wx.BG_STYLE_SYSTEM      The background colour or pattern should
+                            be determined by the system
+    wx.BG_STYLE_COLOUR      The background should be a solid colour
+    wx.BG_STYLE_CUSTOM      The background will be implemented by the
+                            application.
+    ======================  ========================================
+
+On GTK+, use of wx.BG_STYLE_CUSTOM allows the flicker-free drawing of
+a custom background, such as a tiled bitmap. Currently the style has
+no effect on other platforms.
+
+:see: `GetBackgroundStyle`, `SetBackgroundColour`", "");
+    
+    DocDeclStr(
+        virtual wxBackgroundStyle , GetBackgroundStyle() const,
+        "Returns the background style of the window.
+
+:see: `SetBackgroundStyle`", "");
+
+    
+    DocDeclStr(
+        bool , HasTransparentBackground(),
+        "Returns True if this window's background is transparent (as, for
+example, for `wx.StaticText`) and should show the parent window's
+background.
+
+This method is mostly used internally by the library itself and you
+normally shouldn't have to call it. You may, however, have to override
+it in your custom control classes to ensure that background is painted
+correctly.", "");
+    
+    
+    DocDeclStr(
+        virtual bool , SetCursor( const wxCursor &cursor ),
+        "Sets the window's cursor. Notice that the window cursor also sets it
+for the children of the window implicitly.

 
 

-    // set/retrieve the cursor for this window (SetCursor() returns True
-    // if the cursor was really changed)
-    virtual bool SetCursor( const wxCursor &cursor );
-    wxCursor& GetCursor();
+The cursor may be wx.NullCursor in which case the window cursor will
+be reset back to default.", "");
+    
+    DocDeclStr(
+        wxCursor , GetCursor(),
+        "Return the cursor associated with this window.", "");
+    

 
 

-    // set/retrieve the font for the window (SetFont() returns True if the
-    // font really changed)
-    virtual bool SetFont( const wxFont &font );
-    wxFont& GetFont();

 
 

-    // associate a caret with the window
-    void SetCaret(wxCaret *caret);
+    DocDeclStr(
+        virtual bool , SetFont( const wxFont &font ),
+        "Sets the font for this window.", "");
+    
+    DocDeclStr(
+        void , SetOwnFont(const wxFont& font),
+        "", "");
+    

 
 

-    // get the current caret (may be NULL)
-    wxCaret *GetCaret() const;
+    
+    DocDeclStr(
+        wxFont , GetFont(),
+        "Returns the default font used for this window.", "");
+
+    
+
+    %disownarg( wxCaret *caret );
+    DocDeclStr(
+        void , SetCaret(wxCaret *caret),
+        "Sets the caret associated with the window.", "");
+    %cleardisown( wxCaret *caret );
+    
+    DocDeclStr(
+        wxCaret *, GetCaret() const,
+        "Returns the caret associated with the window.", "");
+    

 
 

-    // get the (average) character size for the current font
-    virtual int GetCharHeight() const;
-    virtual int GetCharWidth() const;
+
+    DocDeclStr(
+        virtual int , GetCharHeight() const,
+        "Get the (average) character size for the current font.", "");
+    
+    DocDeclStr(
+        virtual int , GetCharWidth() const,
+        "Get the (average) character size for the current font.", "");
+    

 
 
     DocDeclAStr(
         void, GetTextExtent(const wxString& string, int *OUTPUT, int *OUTPUT),
         "GetTextExtent(String string) -> (width, height)",
 
 
     DocDeclAStr(
         void, GetTextExtent(const wxString& string, int *OUTPUT, int *OUTPUT),
         "GetTextExtent(String string) -> (width, height)",

-        "Get the width and height of the text using the current font.");
+        "Get the width and height of the text using the current font.", "");

     DocDeclAStrName(
         void, GetTextExtent(const wxString& string,
                             int *OUTPUT, int *OUTPUT, int *OUTPUT, int* OUTPUT, 
                             const wxFont* font = NULL),
         "GetFullTextExtent(String string, Font font=None) ->\n   (width, height, descent, externalLeading)",
     DocDeclAStrName(
         void, GetTextExtent(const wxString& string,
                             int *OUTPUT, int *OUTPUT, int *OUTPUT, int* OUTPUT, 
                             const wxFont* font = NULL),
         "GetFullTextExtent(String string, Font font=None) ->\n   (width, height, descent, externalLeading)",

-        "Get the width, height, decent and leading of the text using the current or specified font.",
+        "Get the width, height, decent and leading of the text using the
+current or specified font.", "",

         GetFullTextExtent);
 
 
         GetFullTextExtent);
 
 


@@ -564,46 +1560,140 @@ public:
     %apply int * INOUT { int* x, int* y };
 
     // translate to/from screen/client coordinates
     %apply int * INOUT { int* x, int* y };
 
     // translate to/from screen/client coordinates

-    %name(ClientToScreenXY) void ClientToScreen( int *x, int *y ) const;
-    %name(ScreenToClientXY) void ScreenToClient( int *x, int *y ) const;
+    DocDeclAStrName(
+        void , ClientToScreen( int *x, int *y ) const,
+        "ClientToScreenXY(int x, int y) -> (x,y)",
+        "Converts to screen coordinates from coordinates relative to this window.", "",
+        ClientToScreenXY);
+    
+    DocDeclAStrName(
+        void , ScreenToClient( int *x, int *y ) const,
+        "ScreenToClientXY(int x, int y) -> (x,y)",
+        "Converts from screen to client window coordinates.", "",
+        ScreenToClientXY);
+    
+
+    DocDeclStr(
+        wxPoint , ClientToScreen(const wxPoint& pt) const,
+        "Converts to screen coordinates from coordinates relative to this window.", "");
+    
+    DocDeclStr(
+        wxPoint , ScreenToClient(const wxPoint& pt) const,
+        "Converts from screen to client window coordinates.", "");
+    

 
 

-    wxPoint ClientToScreen(const wxPoint& pt) const;
-    wxPoint ScreenToClient(const wxPoint& pt) const;

 
 

-    // test where the given (in client coords) point lies
-    %name(HitTestXY) wxHitTest HitTest(wxCoord x, wxCoord y) const;
-    wxHitTest HitTest(const wxPoint& pt) const;
+    DocDeclStrName(
+        wxHitTest , HitTest(wxCoord x, wxCoord y) const,
+        "Test where the given (in client coords) point lies", "",
+        HitTestXY);
+    
+    DocDeclStr(
+        wxHitTest , HitTest(const wxPoint& pt) const,
+        "Test where the given (in client coords) point lies", "");
+    

 
 
 
     // misc
     // ----
 
 
 
 
     // misc
     // ----
 

-    // get the window border style from the given flags: this is different from
-    // simply doing flags & wxBORDER_MASK because it uses GetDefaultBorder() to
-    // translate wxBORDER_DEFAULT to something reasonable
-     %name(GetBorderFlags) wxBorder GetBorder(long flags) const;
+    %nokwargs GetBorder;
+    DocDeclStr(
+        wxBorder , GetBorder(long flags) const,
+        "Get the window border style from the given flags: this is different
+from simply doing flags & wxBORDER_MASK because it uses
+GetDefaultBorder() to translate wxBORDER_DEFAULT to something
+reasonable.
+", "");
+    
+    DocDeclStr(
+        wxBorder , GetBorder() const,
+        "Get border for the flags of this window", "");
+    

 
 

-    // get border for the flags of this window
-    wxBorder GetBorder() const { return GetBorder(GetWindowStyleFlag()); }
+    

 
 

-    // send wxUpdateUIEvents to this window, and children if recurse is True
-    virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE);
+    DocDeclStr(
+        virtual void , UpdateWindowUI(long flags = wxUPDATE_UI_NONE),
+        "This function sends EVT_UPDATE_UI events to the window. The particular
+implementation depends on the window; for example a wx.ToolBar will
+send an update UI event for each toolbar button, and a wx.Frame will
+send an update UI event for each menubar menu item. You can call this
+function from your application to ensure that your UI is up-to-date at
+a particular point in time (as far as your EVT_UPDATE_UI handlers are
+concerned). This may be necessary if you have called
+`wx.UpdateUIEvent.SetMode` or `wx.UpdateUIEvent.SetUpdateInterval` to
+limit the overhead that wxWindows incurs by sending update UI events
+in idle time.",
+"
+The flags should be a bitlist of one or more of the following values:
+
+    =====================      ==============================
+    wx.UPDATE_UI_NONE          No particular value
+    wx.UPDATE_UI_RECURSE       Call the function for descendants
+    wx.UPDATE_UI_FROMIDLE      Invoked from OnIdle
+    =====================      ==============================
+
+If you are calling this function from an OnIdle function, make sure
+you pass the wx.UPDATE_UI_FROMIDLE flag, since this tells the window
+to only update the UI elements that need to be updated in idle
+time. Some windows update their elements only when necessary, for
+example when a menu is about to be shown. The following is an example
+of how to call UpdateWindowUI from an idle function::
+
+    def OnIdle(self, evt):
+        if wx.UpdateUIEvent.CanUpdate(self):
+            self.UpdateWindowUI(wx.UPDATE_UI_FROMIDLE);
+");
+    

 
 // TODO: using directors?
 //     // do the window-specific processing after processing the update event
 //     virtual void DoUpdateWindowUI(wxUpdateUIEvent& event) ;
 
 
 // TODO: using directors?
 //     // do the window-specific processing after processing the update event
 //     virtual void DoUpdateWindowUI(wxUpdateUIEvent& event) ;
 

-    %name(PopupMenuXY) bool PopupMenu(wxMenu *menu, int x, int y);
-    bool PopupMenu(wxMenu *menu, const wxPoint& pos);

 
 

+    DocStr(PopupMenu,
+           "Pops up the given menu at the specified coordinates, relative to this window,
+and returns control when the user has dismissed the menu. If a menu item is
+selected, the corresponding menu event is generated and will be processed as
+usual.  If the default position is given then the current position of the
+mouse cursor will be used.", "");
+    %Rename(PopupMenuXY,  bool, PopupMenu(wxMenu *menu, int x=-1, int y=-1));
+    bool PopupMenu(wxMenu *menu, const wxPoint& pos=wxDefaultPosition);
+
+
+    DocDeclStr(
+        virtual bool , HasMultiplePages() const,
+        "", "");
+    
+    

     %extend {
     %extend {

+        DocStr(GetHandle,
+               "Returns the platform-specific handle (as a long integer) of the
+physical window.  Currently on wxMac it returns the handle of the
+toplevel parent of the window.", "");

         long GetHandle() {
             return wxPyGetWinHandle(self);
         }
     }
 
         long GetHandle() {
             return wxPyGetWinHandle(self);
         }
     }
 

+    DocStr(
+        AssociateHandle,
+        "Associate the window with a new native handle", "");
+    %extend {
+        void  AssociateHandle(long handle) {
+            self->AssociateHandle((WXWidget)handle);
+        }
+    }
+        
+           
+    DocDeclStr(
+        virtual void , DissociateHandle(),
+        "Dissociate the current native handle from the window", "");
+    

 
 

+    

 #ifdef __WXMSW__
     // A way to do the native draw first...  Too bad it isn't in wxGTK too.
     void OnPaint(wxPaintEvent& event);
 #ifdef __WXMSW__
     // A way to do the native draw first...  Too bad it isn't in wxGTK too.
     void OnPaint(wxPaintEvent& event);


@@ -614,64 +1704,156 @@ public:
     // scrollbars
     // ----------
 
     // scrollbars
     // ----------
 

-    // does the window have the scrollbar for this orientation?
-    bool HasScrollbar(int orient) const;
+    
+    DocDeclStr(
+        bool , HasScrollbar(int orient) const,
+        "Does the window have the scrollbar for this orientation?", "");
+    

 
     // configure the window scrollbars
 
     // configure the window scrollbars

-    virtual void SetScrollbar( int orient,
-                               int pos,
-                               int thumbvisible,
-                               int range,
-                               bool refresh = True );
-    virtual void SetScrollPos( int orient, int pos, bool refresh = True );
-    virtual int GetScrollPos( int orient ) const;
-    virtual int GetScrollThumb( int orient ) const;
-    virtual int GetScrollRange( int orient ) const;
-
-    // scroll window to the specified position
-    virtual void ScrollWindow( int dx, int dy,
-                               const wxRect* rect = NULL );
-
-    // scrolls window by line/page: note that not all controls support this
-    //
-    // return True if the position changed, False otherwise
-    virtual bool ScrollLines(int WXUNUSED(lines));
-    virtual bool ScrollPages(int WXUNUSED(pages));
-
-    // convenient wrappers for ScrollLines/Pages
-    bool LineUp();
-    bool LineDown();
-    bool PageUp();
-    bool PageDown();
+    DocDeclStr(
+        virtual void , SetScrollbar( int orientation,
+                                     int position,
+                                     int thumbSize,
+                                     int range,
+                                     bool refresh = true ),
+        "Sets the scrollbar properties of a built-in scrollbar.",
+        "
+    :param orientation: Determines the scrollbar whose page size is to
+                 be set. May be wx.HORIZONTAL or wx.VERTICAL.
+
+    :param position: The position of the scrollbar in scroll units.
+
+    :param thumbSize: The size of the thumb, or visible portion of the
+                 scrollbar, in scroll units.
+
+    :param range: The maximum position of the scrollbar.
+
+    :param refresh: True to redraw the scrollbar, false otherwise.
+");
+    
+    DocDeclStr(
+        virtual void , SetScrollPos( int orientation, int pos, bool refresh = true ),
+        "Sets the position of one of the built-in scrollbars.", "");
+    
+    DocDeclStr(
+        virtual int , GetScrollPos( int orientation ) const,
+        "Returns the built-in scrollbar position.", "");
+    
+    DocDeclStr(
+        virtual int , GetScrollThumb( int orientation ) const,
+        "Returns the built-in scrollbar thumb size.", "");
+    
+    DocDeclStr(
+        virtual int , GetScrollRange( int orientation ) const,
+        "Returns the built-in scrollbar range.", "");
+    
+
+    
+
+    DocDeclStr(
+        virtual void , ScrollWindow( int dx, int dy,
+                                     const wxRect* rect = NULL ),
+        "Physically scrolls the pixels in the window and move child windows
+accordingly.  Use this function to optimise your scrolling
+implementations, to minimise the area that must be redrawn. Note that
+it is rarely required to call this function from a user program.","
+
+    :param dx:   Amount to scroll horizontally.
+
+    :param dy:   Amount to scroll vertically.
+
+    :param rect: Rectangle to invalidate. If this is None, the whole
+          window is invalidated. If you pass a rectangle corresponding
+          to the area of the window exposed by the scroll, your
+          painting handler can optimize painting by checking for the
+          invalidated region.");
+    
+
+    DocDeclStr(
+        virtual bool , ScrollLines(int lines),
+        "If the platform and window class supports it, scrolls the window by
+the given number of lines down, if lines is positive, or up if lines
+is negative.  Returns True if the window was scrolled, False if it was
+already on top/bottom and nothing was done.", "");
+    
+    DocDeclStr(
+        virtual bool , ScrollPages(int pages),
+        "If the platform and window class supports it, scrolls the window by
+the given number of pages down, if pages is positive, or up if pages
+is negative.  Returns True if the window was scrolled, False if it was
+already on top/bottom and nothing was done.", "");
+    
+
+    DocDeclStr(
+        bool , LineUp(),
+        "This is just a wrapper for ScrollLines(-1).", "");
+    
+    DocDeclStr(
+        bool , LineDown(),
+        "This is just a wrapper for ScrollLines(1).", "");
+    
+    DocDeclStr(
+        bool , PageUp(),
+        "This is just a wrapper for ScrollPages(-1).", "");
+    
+    DocDeclStr(
+        bool , PageDown(),
+        "This is just a wrapper for ScrollPages(1).", "");
+    

 
 
 
     // context-sensitive help
     // ----------------------
 
 
 
 
     // context-sensitive help
     // ----------------------
 

-    // associate this help text with this window
-    void SetHelpText(const wxString& text);
+    DocDeclStr(
+        void , SetHelpText(const wxString& text),
+        "Sets the help text to be used as context-sensitive help for this
+window.  Note that the text is actually stored by the current
+`wx.HelpProvider` implementation, and not in the window object itself.", "");
+    

 
 

-    // associate this help text with all windows with the same id as this
-    // one
-    void SetHelpTextForId(const wxString& text);
+    DocDeclStr(
+        void , SetHelpTextForId(const wxString& text),
+        "Associate this help text with all windows with the same id as this
+one.", "");
+    

 
 

-    // get the help string associated with this window (may be empty)
-    wxString GetHelpText() const;
+    DocDeclStr(
+        virtual wxString , GetHelpTextAtPoint(const wxPoint& pt,
+                                              wxHelpEvent::Origin origin) const,
+        "Get the help string associated with the given position in this window.
+
+Notice that pt may be invalid if event origin is keyboard or unknown
+and this method should return the global window help text then
+", "");
+    
+    
+   DocDeclStr(
+        wxString , GetHelpText() const,
+        "Gets the help text to be used as context-sensitive help for this
+window.  Note that the text is actually stored by the current
+`wx.HelpProvider` implementation, and not in the window object itself.", "");
+    

 
 
 #ifndef __WXX11__
     // tooltips
     // --------
 
 
 
 #ifndef __WXX11__
     // tooltips
     // --------
 

-    // the easiest way to set a tooltip for a window is to use this method
-    %name(SetToolTipString) void SetToolTip( const wxString &tip );
+    DocStr(SetToolTip,
+           "Attach a tooltip to the window.", "");
+    %Rename(SetToolTipString, void,  SetToolTip( const wxString &tip ));

 
 

-    // attach a tooltip to the window
+    %disownarg( wxToolTip *tip );

     void SetToolTip( wxToolTip *tip );
     void SetToolTip( wxToolTip *tip );

+    %cleardisown( wxToolTip *tip );

 
 

-    // get the associated tooltip or NULL if none
-    wxToolTip* GetToolTip() const;
+    DocDeclStr(
+        wxToolTip* , GetToolTip() const,
+        "get the associated tooltip or None if none", "");
+    

     // LINK ERROR --> wxString GetToolTipText() const;
 #endif
 
     // LINK ERROR --> wxString GetToolTipText() const;
 #endif
 


@@ -681,16 +1863,28 @@ public:
     // drag and drop
     // -------------
 
     // drag and drop
     // -------------
 

-    // set/retrieve the drop target associated with this window (may be
-    // NULL; it's owned by the window and will be deleted by it)
-    %apply SWIGTYPE *DISOWN { wxPyDropTarget *dropTarget };
-    virtual void SetDropTarget( wxPyDropTarget *dropTarget );
-    %clear wxPyDropTarget *dropTarget;
+    %disownarg( wxPyDropTarget *dropTarget );
+    DocDeclStr(
+        virtual void , SetDropTarget( wxPyDropTarget *dropTarget ),
+        "Associates a drop target with this window.  If the window already has
+a drop target, it is deleted.", "");   
+    %cleardisown( wxPyDropTarget *dropTarget );
+
+    
+    DocDeclStr(
+        virtual wxPyDropTarget *, GetDropTarget() const,
+        "Returns the associated drop target, which may be None.", "");

     
     

-    virtual wxPyDropTarget *GetDropTarget() const;

 
 

-#ifdef __WXMSW__  // TODO:  should I drop-kick this?
+    DocStr(DragAcceptFiles,
+        "Enables or disables eligibility for drop file events, EVT_DROP_FILES.
+Only functional on Windows.", "");
+#ifdef __WXMSW__  

     void DragAcceptFiles(bool accept);
     void DragAcceptFiles(bool accept);

+#else
+    %extend {
+        void DragAcceptFiles(bool accept) {}
+    }

 #endif
 #endif
     
 #endif
 #endif
     


@@ -698,28 +1892,85 @@ public:
     // constraints and sizers
     // ----------------------
 
     // constraints and sizers
     // ----------------------
 

-    // set the constraints for this window or retrieve them (may be NULL)
-    void SetConstraints( wxLayoutConstraints *constraints );
-    wxLayoutConstraints *GetConstraints() const;
+    %disownarg(wxLayoutConstraints*);
+    DocDeclStr(
+        void , SetConstraints( wxLayoutConstraints *constraints ),
+        "Sets the window to have the given layout constraints. If an existing
+layout constraints object is already owned by the window, it will be
+deleted.  Pass None to disassociate and delete the window's current
+constraints.
+
+You must call SetAutoLayout to tell a window to use the constraints
+automatically in its default EVT_SIZE handler; otherwise, you must
+handle EVT_SIZE yourself and call Layout() explicitly. When setting
+both a wx.LayoutConstraints and a wx.Sizer, only the sizer will have
+effect.", "");
+    
+    DocDeclStr(
+        wxLayoutConstraints *, GetConstraints() const,
+        "Returns a pointer to the window's layout constraints, or None if there
+are none.", "");
+    %cleardisown(wxLayoutConstraints*);
+    
+
+    DocDeclStr(
+        void , SetAutoLayout( bool autoLayout ),
+        "Determines whether the Layout function will be called automatically
+when the window is resized.  lease note that this only happens for the
+windows usually used to contain children, namely `wx.Panel` and
+`wx.TopLevelWindow` (and the classes deriving from them).

 
 

-    // when using constraints or sizers, it makes sense to update
-    // children positions automatically whenever the window is resized
-    // - this is done if autoLayout is on
-    void SetAutoLayout( bool autoLayout );
-    bool GetAutoLayout() const;
+This method is called implicitly by `SetSizer` but if you use
+`SetConstraints` you should call it manually or otherwise the window
+layout won't be correctly updated when its size changes.", "");
+    
+    DocDeclStr(
+        bool , GetAutoLayout() const,
+        "Returns the current autoLayout setting", "");
+    

 
 

-    // lay out the window and its children
-    virtual bool Layout();
+    DocDeclStr(
+        virtual bool , Layout(),
+        "Invokes the constraint-based layout algorithm or the sizer-based
+algorithm for this window.  See SetAutoLayout: when auto layout is on,
+this function gets called automatically by the default EVT_SIZE
+handler when the window is resized.", "");
+    

 
 

-    // sizers
-    void SetSizer(wxSizer *sizer, bool deleteOld = True );
-    void SetSizerAndFit( wxSizer *sizer, bool deleteOld = True );
+    %disownarg( wxSizer *sizer );
+    DocDeclStr(
+        void , SetSizer(wxSizer *sizer, bool deleteOld = true ),
+        "Sets the window to have the given layout sizer. The window will then
+own the object, and will take care of its deletion. If an existing
+layout sizer object is already owned by the window, it will be deleted
+if the deleteOld parameter is true. Note that this function will also
+call SetAutoLayout implicitly with a True parameter if the sizer is
+non-None, and False otherwise.", "");
+    
+    DocDeclStr(
+        void , SetSizerAndFit( wxSizer *sizer, bool deleteOld = true ),
+        "The same as SetSizer, except it also sets the size hints for the
+window based on the sizer's minimum size.", "");
+    %cleardisown( wxSizer *sizer );

 
 

-    wxSizer *GetSizer() const;
+
+    DocDeclStr(
+        wxSizer *, GetSizer() const,
+        "Return the sizer associated with the window by a previous call to
+SetSizer or None if there isn't one.", "");
+    

 
     // Track if this window is a member of a sizer
 
     // Track if this window is a member of a sizer

-    void SetContainingSizer(wxSizer* sizer);
-    wxSizer *GetContainingSizer() const;
+    DocDeclStr(
+        void , SetContainingSizer(wxSizer* sizer),
+        "This normally does not need to be called by application code. It is
+called internally when a window is added to a sizer, and is used so
+the window can remove itself from the sizer when it is destroyed.", "");
+    
+    DocDeclStr(
+        wxSizer *, GetContainingSizer() const,
+        "Return the sizer that this window is a member of, if any, otherwise None.", "");
+    

 
 
 
 
 
 


@@ -741,10 +1992,73 @@ public:
 
 
 
 
 
 

+
+    DocDeclStr(
+        virtual void , InheritAttributes(),
+        "This function is (or should be, in case of custom controls) called
+during window creation to intelligently set up the window visual
+attributes, that is the font and the foreground and background
+colours.
+
+By 'intelligently' the following is meant: by default, all windows use
+their own default attributes. However if some of the parent's
+attributes are explicitly changed (that is, using SetFont and not
+SetOwnFont) and if the corresponding attribute hadn't been
+explicitly set for this window itself, then this window takes the same
+value as used by the parent. In addition, if the window overrides
+ShouldInheritColours to return false, the colours will not be changed
+no matter what and only the font might.
+
+This rather complicated logic is necessary in order to accommodate the
+different usage scenarios. The most common one is when all default
+attributes are used and in this case, nothing should be inherited as
+in modern GUIs different controls use different fonts (and colours)
+than their siblings so they can't inherit the same value from the
+parent. However it was also deemed desirable to allow to simply change
+the attributes of all children at once by just changing the font or
+colour of their common parent, hence in this case we do inherit the
+parents attributes.
+", "");
+
+    
+// TODO:  Virtualize this with directors    
+    DocDeclStr(
+        virtual bool , ShouldInheritColours() const,
+        "Return true from here to allow the colours of this window to be
+changed by InheritAttributes, returning false forbids inheriting them
+from the parent window.
+
+The base class version returns false, but this method is overridden in
+wxControl where it returns true.", "");
+    
+
+
+    DocDeclStr(
+        virtual bool , CanSetTransparent(),
+        "Returns ``True`` if the platform supports setting the transparency for
+this window.  Note that this method will err on the side of caution,
+so it is possible that this will return ``False`` when it is in fact
+possible to set the transparency.
+
+NOTE: On X-windows systems the X server must have the composite
+extension loaded, and there must be a composite manager program (such
+as xcompmgr) running.", "");
+
+    DocDeclStr(
+        virtual bool , SetTransparent(byte alpha),
+        "Attempt to set the transparency of this window to the ``alpha`` value,
+returns True on success.  The ``alpha`` value is an integer in the
+range of 0 to 255, where 0 is fully transparent and 255 is fully
+opaque.", "");
+    
+    
+

     %pythoncode {
     def PostCreate(self, pre):
     %pythoncode {
     def PostCreate(self, pre):

-        """Phase 3 of the 2-phase create <wink!>
-           Call this method after precreating the window with the 2-phase create method."""
+        """
+        Phase 3 of the 2-phase create <wink!>
+        Call this method after precreating the window with the 2-phase create method.
+        """

         self.this = pre.this
         self.thisown = pre.thisown
         pre.thisown = 0
         self.this = pre.this
         self.thisown = pre.thisown
         pre.thisown = 0


@@ -753,9 +2067,73 @@ public:
         if hasattr(self, '_setCallbackInfo'):
             self._setCallbackInfo(self, self.__class__)
     }
         if hasattr(self, '_setCallbackInfo'):
             self._setCallbackInfo(self, self.__class__)
     }

-};

 
 

+    %pythoncode {
+    def SendSizeEvent(self):
+        self.GetEventHandler().ProcessEvent(wx.SizeEvent((-1,-1)))
+    }

 
 

+    
+    %property(AcceleratorTable, GetAcceleratorTable, SetAcceleratorTable, doc="See `GetAcceleratorTable` and `SetAcceleratorTable`");
+    %property(AdjustedBestSize, GetAdjustedBestSize, doc="See `GetAdjustedBestSize`");
+    %property(AutoLayout, GetAutoLayout, SetAutoLayout, doc="See `GetAutoLayout` and `SetAutoLayout`");
+    %property(BackgroundColour, GetBackgroundColour, SetBackgroundColour, doc="See `GetBackgroundColour` and `SetBackgroundColour`");
+    %property(BackgroundStyle, GetBackgroundStyle, SetBackgroundStyle, doc="See `GetBackgroundStyle` and `SetBackgroundStyle`");
+    %property(BestFittingSize, GetBestFittingSize, SetBestFittingSize, doc="See `GetBestFittingSize` and `SetBestFittingSize`");
+    %property(BestSize, GetBestSize, doc="See `GetBestSize`");
+    %property(BestVirtualSize, GetBestVirtualSize, doc="See `GetBestVirtualSize`");
+    %property(Border, GetBorder, doc="See `GetBorder`");
+    %property(Caret, GetCaret, SetCaret, doc="See `GetCaret` and `SetCaret`");
+    %property(CharHeight, GetCharHeight, doc="See `GetCharHeight`");
+    %property(CharWidth, GetCharWidth, doc="See `GetCharWidth`");
+    %property(Children, GetChildren, doc="See `GetChildren`");
+    %property(ClientAreaOrigin, GetClientAreaOrigin, doc="See `GetClientAreaOrigin`");
+    %property(ClientRect, GetClientRect, SetClientRect, doc="See `GetClientRect` and `SetClientRect`");
+    %property(ClientSize, GetClientSize, SetClientSize, doc="See `GetClientSize` and `SetClientSize`");
+    %property(Constraints, GetConstraints, SetConstraints, doc="See `GetConstraints` and `SetConstraints`");
+    %property(ContainingSizer, GetContainingSizer, SetContainingSizer, doc="See `GetContainingSizer` and `SetContainingSizer`");
+    %property(Cursor, GetCursor, SetCursor, doc="See `GetCursor` and `SetCursor`");
+    %property(DefaultAttributes, GetDefaultAttributes, doc="See `GetDefaultAttributes`");
+    %property(DropTarget, GetDropTarget, SetDropTarget, doc="See `GetDropTarget` and `SetDropTarget`");
+    %property(EventHandler, GetEventHandler, SetEventHandler, doc="See `GetEventHandler` and `SetEventHandler`");
+    %property(ExtraStyle, GetExtraStyle, SetExtraStyle, doc="See `GetExtraStyle` and `SetExtraStyle`");
+    %property(Font, GetFont, SetFont, doc="See `GetFont` and `SetFont`");
+    %property(ForegroundColour, GetForegroundColour, SetForegroundColour, doc="See `GetForegroundColour` and `SetForegroundColour`");
+    %property(GrandParent, GetGrandParent, doc="See `GetGrandParent`");
+    %property(Handle, GetHandle, doc="See `GetHandle`");
+    %property(HelpText, GetHelpText, SetHelpText, doc="See `GetHelpText` and `SetHelpText`");
+    %property(Id, GetId, SetId, doc="See `GetId` and `SetId`");
+    %property(Label, GetLabel, SetLabel, doc="See `GetLabel` and `SetLabel`");
+    %property(LayoutDirection, GetLayoutDirection, SetLayoutDirection, doc="See `GetLayoutDirection` and `SetLayoutDirection`");
+    %property(MaxHeight, GetMaxHeight, doc="See `GetMaxHeight`");
+    %property(MaxSize, GetMaxSize, SetMaxSize, doc="See `GetMaxSize` and `SetMaxSize`");
+    %property(MaxWidth, GetMaxWidth, doc="See `GetMaxWidth`");
+    %property(MinHeight, GetMinHeight, doc="See `GetMinHeight`");
+    %property(MinSize, GetMinSize, SetMinSize, doc="See `GetMinSize` and `SetMinSize`");
+    %property(MinWidth, GetMinWidth, doc="See `GetMinWidth`");
+    %property(Name, GetName, SetName, doc="See `GetName` and `SetName`");
+    %property(Parent, GetParent, doc="See `GetParent`");
+    %property(Position, GetPosition, SetPosition, doc="See `GetPosition` and `SetPosition`");
+    %property(Rect, GetRect, SetRect, doc="See `GetRect` and `SetRect`");
+    %property(ScreenPosition, GetScreenPosition, doc="See `GetScreenPosition`");
+    %property(ScreenRect, GetScreenRect, doc="See `GetScreenRect`");
+    %property(Size, GetSize, SetSize, doc="See `GetSize` and `SetSize`");
+    %property(Sizer, GetSizer, SetSizer, doc="See `GetSizer` and `SetSizer`");
+    %property(ThemeEnabled, GetThemeEnabled, SetThemeEnabled, doc="See `GetThemeEnabled` and `SetThemeEnabled`");
+    %property(ToolTip, GetToolTip, SetToolTip, doc="See `GetToolTip` and `SetToolTip`");
+    %property(UpdateClientRect, GetUpdateClientRect, doc="See `GetUpdateClientRect`");
+    %property(UpdateRegion, GetUpdateRegion, doc="See `GetUpdateRegion`");
+    %property(Validator, GetValidator, SetValidator, doc="See `GetValidator` and `SetValidator`");
+    %property(VirtualSize, GetVirtualSize, SetVirtualSize, doc="See `GetVirtualSize` and `SetVirtualSize`");
+    %property(WindowStyle, GetWindowStyle, SetWindowStyle, doc="See `GetWindowStyle` and `SetWindowStyle`");
+    %property(WindowStyleFlag, GetWindowStyleFlag, SetWindowStyleFlag, doc="See `GetWindowStyleFlag` and `SetWindowStyleFlag`");
+    %property(WindowVariant, GetWindowVariant, SetWindowVariant, doc="See `GetWindowVariant` and `SetWindowVariant`");
+
+    %property(Shown, IsShown, Show, doc="See `IsShown` and `Show`");
+    %property(Enabled, IsEnabled, Enable, doc="See `IsEnabled` and `Enable`");
+    %property(TopLevel, IsTopLevel, doc="See `IsTopLevel`");
+    
+};

 
 
 
 
 
 


@@ -764,12 +2142,20 @@ public:
 
 %pythoncode {
 def DLG_PNT(win, point_or_x, y=None):
 
 %pythoncode {
 def DLG_PNT(win, point_or_x, y=None):

+    """
+    Convenience function for converting a Point or (x,y) in
+    dialog units to pixel units.
+    """

     if y is None:
         return win.ConvertDialogPointToPixels(point_or_x)
     else:
         return win.ConvertDialogPointToPixels(wx.Point(point_or_x, y))
 
 def DLG_SZE(win, size_width, height=None):
     if y is None:
         return win.ConvertDialogPointToPixels(point_or_x)
     else:
         return win.ConvertDialogPointToPixels(wx.Point(point_or_x, y))
 
 def DLG_SZE(win, size_width, height=None):

+    """
+    Convenience function for converting a Size or (w,h) in
+    dialog units to pixel units.
+    """

     if height is None:
         return win.ConvertDialogSizeToPixels(size_width)
     else:
     if height is None:
         return win.ConvertDialogSizeToPixels(size_width)
     else:


@@ -785,7 +2171,33 @@ def DLG_SZE(win, size_width, height=None):
 // standalone functions for them.
 
 
 // standalone functions for them.
 
 

-// Find a window among any window in the application (all return NULL if not found)
+DocStr(wxFindWindowById,
+"Find the first window in the application with the given id. If parent
+is None, the search will start from all top-level frames and dialog
+boxes; if non-None, the search will be limited to the given window
+hierarchy. The search is recursive in both cases.", "");
+
+DocStr(wxFindWindowByName,
+"Find a window by its name (as given in a window constructor or Create
+function call). If parent is None, the search will start from all
+top-level frames and dialog boxes; if non-None, the search will be
+limited to the given window hierarchy. The search is recursive in both
+cases.
+
+If no window with such name is found, wx.FindWindowByLabel is called.", "");
+
+DocStr(wxFindWindowByLabel,
+"Find a window by its label. Depending on the type of window, the label
+may be a window title or panel item label. If parent is None, the
+search will start from all top-level frames and dialog boxes; if
+non-None, the search will be limited to the given window
+hierarchy. The search is recursive in both cases.", "");
+
+
+MustHaveApp(wxFindWindowById);
+MustHaveApp(wxFindWindowByName);
+MustHaveApp(wxFindWindowByLabel);
+

 %inline %{
 wxWindow* wxFindWindowById( long id, const wxWindow *parent = NULL ) {
     return wxWindow::FindWindowById(id, parent);
 %inline %{
 wxWindow* wxFindWindowById( long id, const wxWindow *parent = NULL ) {
     return wxWindow::FindWindowById(id, parent);


@@ -804,12 +2216,26 @@ wxWindow* wxFindWindowByLabel( const wxString& label,
 
 
 
 
 
 

+%{
+#ifdef __WXMSW__
+#include <wx/msw/private.h>  // to get wxGetWindowId
+#endif
+%}
+

 %inline %{
 %inline %{

-    wxWindow* wxWindow_FromHWND(unsigned long hWnd) {
+    wxWindow* wxWindow_FromHWND(wxWindow* parent, unsigned long _hWnd) {

 #ifdef __WXMSW__
 #ifdef __WXMSW__

+        WXHWND hWnd = (WXHWND)_hWnd;
+        long id = wxGetWindowId(hWnd);

         wxWindow* win = new wxWindow;
         wxWindow* win = new wxWindow;

+        if (parent)
+            parent->AddChild(win);
+        win->SetEventHandler(win);

         win->SetHWND(hWnd);
         win->SetHWND(hWnd);

+        win->SetId(id);

         win->SubclassWin(hWnd);
         win->SubclassWin(hWnd);

+        win->AdoptAttributesFromHWND();
+        win->SetupColours();

         return win;
 #else
         wxPyRaiseNotImplemented();
         return win;
 #else
         wxPyRaiseNotImplemented();


@@ -818,6 +2244,20 @@ wxWindow* wxFindWindowByLabel( const wxString& label,
     }
 %}
 
     }
 %}
 

+//---------------------------------------------------------------------------
+
+DocStr(GetTopLevelWindows,
+"Returns a list of the the application's top-level windows, (frames,
+dialogs, etc.)  NOTE: Currently this is a copy of the list maintained
+by wxWidgets, and so it is only valid as long as no top-level windows
+are closed or new top-level windows are created.
+", "");
+%inline %{
+    PyObject* GetTopLevelWindows() {
+        return wxPy_ConvertList(&wxTopLevelWindows);
+    }
+%}
+

 //---------------------------------------------------------------------------
 //---------------------------------------------------------------------------
 
 //---------------------------------------------------------------------------
 //---------------------------------------------------------------------------