docstring tweak

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

diff --git a/wxPython/src/_window.i b/wxPython/src/_window.i
index 92c48f1a83421f8756a4c39380a7d14d3640899b..7f5cb655ec6d63cbddc25d67aa50746ffe5c4bfb 100644 (file)
--- a/wxPython/src/_window.i
+++ b/wxPython/src/_window.i
@@ -24,6 +24,40 @@ 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() {}
+    }
+    
+    // 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
 DocStr(wxWindow,
 "
 wx.Window is the base class for all windows and represents any visible


@@ -157,8 +191,10 @@ public:
     %pythonAppend wxWindow         "self._setOORInfo(self)"
     %pythonAppend wxWindow()       ""
 
     %pythonAppend wxWindow         "self._setOORInfo(self)"
     %pythonAppend wxWindow()       ""
 

+    RefDoc(wxWindow, ""); // turn it off for the ctors
+    

     DocCtorStr(
     DocCtorStr(

-        wxWindow(wxWindow* parent, const wxWindowID id,
+        wxWindow(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,


@@ -172,7 +208,7 @@ public:
     
 
     DocDeclStr(
     
 
     DocDeclStr(

-        bool , Create(wxWindow* parent, const wxWindowID id,
+        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,


@@ -253,30 +289,43 @@ has been added to the list of windows pending real deletion.");
     
     DocDeclStr(
         virtual wxString , GetLabel() const,
     
     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.");
+        "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.");

     
 
     
 

-    // the window name is used for ressource setting in X, it is not the
-    // same as the window title/label

     DocDeclStr(
         virtual void , SetName( const wxString &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");
+        "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,
     
     DocDeclStr(
         virtual wxString , GetName() const,

-        "Returns the window's 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.");
+        "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,
+        "");

     
 
     
 

-    // window id uniquely identifies the window among its siblings unless
-    // it is -1 which means "don't care"

     DocDeclStr(
         void , SetId( wxWindowID winid ),
         "Sets the identifier of the window.  Each window has an integer
     DocDeclStr(
         void , SetId( wxWindowID winid ),
         "Sets the identifier of the window.  Each window has an integer


@@ -503,26 +552,32 @@ windows without an interior sizer. This function similarly won't do
 anything if there are no subwindows.");
     
 
 anything if there are no subwindows.");
     
 

-
-    DocDeclStr(
-        virtual void , SetSizeHints( int minW, int minH,
-                                     int maxW = -1, int maxH = -1,
-                                     int incW = -1, int incH = -1 ),
+    
+    %nokwargs SetSizeHints;
+    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. The
 resizing increments are only significant under Motif or Xt.");
         "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. The
 resizing increments are only significant under Motif or Xt.");

-    
+    virtual void SetSizeHints( int minW, int minH,
+                               int maxW = -1, int maxH = -1,
+                               int incW = -1, int incH = -1 );
+    void SetSizeHints( const wxSize& minSize,
+                       const wxSize& maxSize=wxDefaultSize,
+                       const wxSize& incSize=wxDefaultSize);

 
 

-    DocDeclStr(
-        virtual void , SetVirtualSizeHints( int minW, int minH,
-                                            int maxW = -1, int maxH = -1 ),
+    
+    %nokwargs SetVirtualSizeHints;
+    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.");
         "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 );
+    void SetVirtualSizeHints( const wxSize& minSize,
+                              const wxSize& maxSize=wxDefaultSize);

     
     DocDeclStr(
         virtual int , GetMinWidth() const,
     
     DocDeclStr(
         virtual int , GetMinWidth() const,


@@ -546,6 +601,10 @@ the virtual area of the window outside the given bounds.");
         "");
     
 
         "");
     
 

+    DocDeclStr(
+        virtual wxSize , GetMinSize() const,
+        "");
+    

     
     DocStr(SetVirtualSize,
            "Set the the virtual size of a window in pixels.  For most windows this
     
     DocStr(SetVirtualSize,
            "Set the the virtual size of a window in pixels.  For most windows this


@@ -588,8 +647,8 @@ sizer, interior children, or other means)");
         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
         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
+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(
 because it already was in the requested state.");
     
     DocDeclStr(


@@ -629,7 +688,8 @@ after changing the others for the change to take place immediately.");
     
     DocDeclStr(
         virtual long , GetWindowStyleFlag() const,
     
     DocDeclStr(
         virtual long , GetWindowStyleFlag() const,

-        "Gets the window style that was passed to the constructor or Create method.");    
+        "Gets the window style that was passed to the constructor or Create
+method.");    

 
     %pythoncode { SetWindowStyle = SetWindowStyleFlag; GetWindowStyle = GetWindowStyleFlag }
     
 
     %pythoncode { SetWindowStyle = SetWindowStyleFlag; GetWindowStyle = GetWindowStyleFlag }
     


@@ -723,8 +783,7 @@ or None.");
         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
         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.
-");
+it.");

     
 
 
     
 
 


@@ -732,8 +791,7 @@ it.
     DocDeclStr(
         virtual wxWindow *, GetDefaultItem() const,
         "Get the default child of this parent, i.e. the one which is activated
     DocDeclStr(
         virtual wxWindow *, GetDefaultItem() const,
         "Get the default child of this parent, i.e. the one which is activated

-by pressing <Enter> such as the OK button on a wx.Dialog.
-");
+by pressing <Enter> such as the OK button on a wx.Dialog.");

     
     DocDeclStr(
         virtual wxWindow *, SetDefaultItem(wxWindow * child),
     
     DocDeclStr(
         virtual wxWindow *, SetDefaultItem(wxWindow * child),


@@ -891,6 +949,37 @@ type.");
         virtual wxValidator *, GetValidator(),
         "Returns a pointer to the current validator for the window, or None if
 there is none.");
         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.");
+    

     
 
 
     
 
 


@@ -921,11 +1010,11 @@ 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) {
 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) {

-        #if wxUSE_HOTKEY
+        %#if wxUSE_HOTKEY

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

-        #else
+        %#else

             return False;
             return False;

-        #endif
+        %#endif

         }
 
         
         }
 
         


@@ -946,8 +1035,8 @@ hotkey was registered successfully.");
     // ---------------------------
 
     DocStr(ConvertDialogToPixels,
     // ---------------------------
 
     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
+           "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
 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


@@ -1047,9 +1136,10 @@ colour. Does not cause an erase background event to be generated.");
 
     DocDeclStr(
         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.
+        "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.

 
 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
 
 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


@@ -1060,7 +1150,9 @@ mandatory directive.");
 
     DocDeclStr(
         virtual void , Thaw(),
 
     DocDeclStr(
         virtual void , Thaw(),

-        "Reenables window updating after a previous call to Freeze.");
+        "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.");

     
 
     DocDeclStr(
     
 
     DocDeclStr(


@@ -1088,17 +1180,37 @@ optimize redrawing by only redrawing those areas, which have been
 exposed.");
     bool IsExposed( int x, int y, int w=1, int h=1 ) const;
     %name(IsExposedPoint) bool IsExposed( const wxPoint& pt ) const;
 exposed.");
     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;
+    %name(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

 
 

+    DocDeclStr(
+        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 users 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 users 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 SetWindowVariant for more about this.");
+    

     
     DocDeclStr(
         virtual bool , SetBackgroundColour( const wxColour &colour ),
     
     DocDeclStr(
         virtual bool , SetBackgroundColour( const wxColour &colour ),


@@ -1122,7 +1234,7 @@ modules.");
 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.");
 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(
         wxColour , GetBackgroundColour() const,
 
     DocDeclStr(
         wxColour , GetBackgroundColour() const,


@@ -1157,7 +1269,7 @@ be reset back to default.");
     
     DocDeclStr(
         wxFont& , GetFont(),
     
     DocDeclStr(
         wxFont& , GetFont(),

-        "Returns a reference to the font for this window.");
+        "Returns the default font used for this window.");

 
     
 
 
     
 


@@ -1688,12 +1800,25 @@ 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;

+        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();