Added docstrings

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@25937 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

wxPython/src/_constraints.i

@@ -42,6 +42,51 @@ enum wxRelationship
 };
 
 
+DocStr(wxIndividualLayoutConstraint,
+"Objects of this class are stored in the wx.LayoutConstraint class as one of
+eight possible constraints that a window can be involved in.  You will never
+need to create an instance of wx.IndividualLayoutConstraint, rather you should
+use create a wx.LayoutContstraints instance and use the individual contstraints
+that it contains.
+
+Constraints are initially set to have the relationship wx.Unconstrained, which
+means that their values should be calculated by looking at known constraints.
+
+The Edge specifies the type of edge or dimension of a window.
+
+ Edges
+
+    wx.Left 	The left edge.
+    wx.Top 	The top edge.
+    wx.Right 	The right edge.
+    wx.Bottom 	The bottom edge.
+    wx.CentreX 	The x-coordinate of the centre of the window.
+    wx.CentreY 	The y-coordinate of the centre of the window. 
+
+
+The Relationship specifies the relationship that this edge or dimension has
+with another specified edge or dimension. Normally, the user doesn't use these
+directly because functions such as Below and RightOf are a convenience for
+using the more general Set function.
+
+ Relationships
+
+    wx.Unconstrained 	The edge or dimension is unconstrained
+                        (the default for edges.)
+    wx.AsIs 	        The edge or dimension is to be taken from the current
+                        window position or size (the default for dimensions.)
+    wx.Above 	        The edge should be above another edge.
+    wx.Below 	        The edge should be below another edge.
+    wx.LeftOf 	        The edge should be to the left of another edge.
+    wx.RightOf 	        The edge should be to the right of another edge.
+    wx.SameAs 	        The edge or dimension should be the same as another edge
+                        or dimension.
+    wx.PercentOf 	The edge or dimension should be a percentage of another
+                        edge or dimension.
+    wx.Absolute 	The edge or dimension should be a given absolute value.
+
+");
+
 // wxIndividualLayoutConstraint: a constraint on window position
 class wxIndividualLayoutConstraint : public wxObject
 {
@@ -49,89 +94,173 @@ public:
 //    wxIndividualLayoutConstraint();
 //    ~wxIndividualLayoutConstraint();
 
-    void Set(wxRelationship rel, wxWindow *otherW, wxEdge otherE, int val = 0, int marg = wxLAYOUT_DEFAULT_MARGIN);
+    DocDeclStr(
+        void , Set(wxRelationship rel, wxWindow *otherW, wxEdge otherE,
+                   int val = 0, int marg = wxLAYOUT_DEFAULT_MARGIN),
+        "");
     
-    //
-    // Sibling relationships
-    //
-    void LeftOf(wxWindow *sibling, int marg = 0);
-    void RightOf(wxWindow *sibling, int marg = 0);
-    void Above(wxWindow *sibling, int marg = 0);
-    void Below(wxWindow *sibling, int marg = 0);
 
-    //
+     DocDeclStr(
-    // 'Same edge' alignment
+        void , LeftOf(wxWindow *sibling, int marg = 0),
-    //
+        "Sibling relationship");
-    void SameAs(wxWindow *otherW, wxEdge edge, int marg = 0);
     
-    // The edge is a percentage of the other window's edge
+    DocDeclStr(
-    void PercentOf(wxWindow *otherW, wxEdge wh, int per);
+        void , RightOf(wxWindow *sibling, int marg = 0),
+        "Sibling relationship");
     
-    //
+    DocDeclStr(
-    // Edge has absolute value
+        void , Above(wxWindow *sibling, int marg = 0),
-    //
+        "Sibling relationship");
-    void Absolute(int val);
     
-    //
+    DocDeclStr(
-    // Dimension is unconstrained
+        void , Below(wxWindow *sibling, int marg = 0),
-    //
+        "Sibling relationship");
-    void Unconstrained() { relationship = wxUnconstrained; }
 
-    //
+    DocDeclStr(
-    // Dimension is 'as is' (use current size settings)
+        void , SameAs(wxWindow *otherW, wxEdge edge, int marg = 0),
-    //
+        "'Same edge' alignment");
-    void AsIs() { relationship = wxAsIs; }
     
-    //
-    // Accessors
-    //
-    wxWindow *GetOtherWindow();
-    wxEdge GetMyEdge() const;
-    void SetEdge(wxEdge which);
-    void SetValue(int v);
-    int GetMargin();
-    void SetMargin(int m);
-    int GetValue() const;
-    int GetPercent() const;
-    int GetOtherEdge() const;
-    bool GetDone() const;
-    void SetDone(bool d);
-    wxRelationship GetRelationship();
-    void SetRelationship(wxRelationship r);
 
-    // Reset constraint if it mentions otherWin
+    DocDeclStr(
-    bool ResetIfWin(wxWindow *otherW);
+        void , PercentOf(wxWindow *otherW, wxEdge wh, int per),
+        "The edge is a percentage of the other window's edge");
     
-    // Try to satisfy constraint
-    bool SatisfyConstraint(wxLayoutConstraints *constraints, wxWindow *win);
 
-    // Get the value of this edge or dimension, or if this
+    DocDeclStr(
-    // is not determinable, -1.
+        void , Absolute(int val),
-    int GetEdge(wxEdge which, wxWindow *thisWin, wxWindow *other) const;
+        "Edge has absolute value");
 
+    DocDeclStr(
+        void , Unconstrained(),
+        "Dimension is unconstrained");
+    
+
+    DocDeclStr(
+        void , AsIs(),
+        "Dimension is 'as is' (use current size settings)");
+    
+
+    DocDeclStr(
+        wxWindow *, GetOtherWindow(),
+        "");
+        
+    DocDeclStr(
+        wxEdge , GetMyEdge() const,
+        "");
+    
+    DocDeclStr(
+        void , SetEdge(wxEdge which),
+        "");
+    
+    DocDeclStr(
+        void , SetValue(int v),
+        "");
+    
+    DocDeclStr(
+        int , GetMargin(),
+        "");
+    
+    DocDeclStr(
+        void , SetMargin(int m),
+        "");
+    
+    DocDeclStr(
+        int , GetValue() const,
+        "");
+    
+    DocDeclStr(
+        int , GetPercent() const,
+        "");
+    
+    DocDeclStr(
+        int , GetOtherEdge() const,
+        "");
+    
+    DocDeclStr(
+        bool , GetDone() const,
+        "");
+    
+    DocDeclStr(
+        void , SetDone(bool d),
+        "");
+    
+    DocDeclStr(
+        wxRelationship , GetRelationship(),
+        "");
+    
+    DocDeclStr(
+        void , SetRelationship(wxRelationship r),
+        "");
+    
+
+    DocDeclStr(
+        bool , ResetIfWin(wxWindow *otherW),
+        "Reset constraint if it mentions otherWin");
+    
+
+    DocDeclStr(
+        bool , SatisfyConstraint(wxLayoutConstraints *constraints, wxWindow *win),
+        "Try to satisfy constraint");
+    
+
+    DocDeclStr(
+        int , GetEdge(wxEdge which, wxWindow *thisWin, wxWindow *other) const,
+        "Get the value of this edge or dimension, or if this\n"
+        "is not determinable, -1.");
 };
 
+DocStr(wxLayoutConstraints,
+"Note: constraints are now deprecated and you should use sizers instead.
+
+Objects of this class can be associated with a window to define its layout
+constraints, with respect to siblings or its parent.
+
+The class consists of the following eight constraints of class
+wx.IndividualLayoutConstraint, some or all of which should be accessed
+directly to set the appropriate constraints.
+
+    * left: represents the left hand edge of the window
+    * right: represents the right hand edge of the window
+    * top: represents the top edge of the window
+    * bottom: represents the bottom edge of the window
+    * width: represents the width of the window
+    * height: represents the height of the window
+    * centreX: represents the horizontal centre point of the window
+    * centreY: represents the vertical centre point of the window 
+
+Most constraints are initially set to have the relationship wxUnconstrained,
+which means that their values should be calculated by looking at known
+constraints. The exceptions are width and height, which are set to wxAsIs to
+ensure that if the user does not specify a constraint, the existing width and
+height will be used, to be compatible with panel items which often have take a
+default size. If the constraint is wxAsIs, the dimension will not be changed.
+");
        
 // wxLayoutConstraints: the complete set of constraints for a window
 class wxLayoutConstraints : public wxObject
 {
 public:
     %immutable;
+
     // Edge constraints
     wxIndividualLayoutConstraint left;
     wxIndividualLayoutConstraint top;
     wxIndividualLayoutConstraint right;
     wxIndividualLayoutConstraint bottom;
+
     // Size constraints
     wxIndividualLayoutConstraint width;
     wxIndividualLayoutConstraint height;
+    
     // Centre constraints
     wxIndividualLayoutConstraint centreX;
     wxIndividualLayoutConstraint centreY;
+
     %mutable;
 
-    wxLayoutConstraints();
+    DocCtorStr(
-
+        wxLayoutConstraints(),
+        "");
     
     DocDeclA(
         bool, SatisfyConstraints(wxWindow *win, int *OUTPUT),

wxPython/src/_control.i

@@ -21,45 +21,57 @@ MAKE_CONST_WXSTRING(ControlNameStr);
 %newgroup;
 
 
-//  This is the base class for a control or 'widget'.
+DocStr(wxControl,
-//
+"This is the base class for a control or 'widget'.
-//  A control is generally a small window which processes user input and/or
+
-//  displays one or more item of data.
+A control is generally a small window which processes user input and/or
+displays one or more item of data.");
+
 class wxControl : public wxWindow
 {
 public:
     %pythonAppend wxControl         "self._setOORInfo(self)"
     %pythonAppend wxControl()       ""
 
+    DocCtorStr(
         wxControl(wxWindow *parent,
               wxWindowID id,
               const wxPoint& pos=wxDefaultPosition,
               const wxSize& size=wxDefaultSize,
               long style=0,
               const wxValidator& validator=wxDefaultValidator,
-              const wxString& name=wxPyControlNameStr);
+                  const wxString& name=wxPyControlNameStr),
+        "Create a Control.  Normally you should only call this from a\n"
+        "subclass' __init__ as a plain old wx.Control is not very useful.");
 
-    %name(PreControl)wxControl();
+    DocCtorStrName(
+        wxControl(),
+        "Precreate a Control control for 2-phase creation",
+        PreControl);
 
-    bool Create(wxWindow *parent,
+    DocDeclStr(
+        bool , Create(wxWindow *parent,
                       wxWindowID id,
                       const wxPoint& pos=wxDefaultPosition,
                       const wxSize& size=wxDefaultSize,
                       long style=0,
                       const wxValidator& validator=wxDefaultValidator,
-                       const wxString& name=wxPyControlNameStr);
+                      const wxString& name=wxPyControlNameStr),
+        "Do the 2nd phase and create the GUI control.");
     
 
-    // Simulates the effect of the user issuing a command to the item. See
+    DocDeclStr(
-    // wxCommandEvent.
+        void , Command(wxCommandEvent& event),
-    void Command(wxCommandEvent& event);
+        "Simulates the effect of the user issuing a command to the\n"
+        "item. See wxCommandEvent.");
    
-    // Return a control's text.
+    DocDeclStr(
-    wxString GetLabel();
+        wxString , GetLabel(),
-
+        "Return a control's text.");
-    // Sets the item's text.
-    void SetLabel(const wxString& label);
     
+    DocDeclStr(
+        void , SetLabel(const wxString& label),
+        "Sets the item's text.");
 };
 
 
@@ -67,23 +79,33 @@ public:
 %newgroup;
 
 
-// wxItemContainer defines an interface which is implemented by all controls
+DocStr(wxItemContainer,
-// which have string subitems each of which may be selected.
+"wx.ItemContainer defines an interface which is implemented by all
-//
+controls which have string subitems, each of which may be
-// Examples: wxListBox, wxCheckListBox, wxChoice and wxComboBox (which
+selected, such as wx.ListBox, wx.CheckListBox, wx.Choice and
-// implements an extended interface deriving from this one)
+wx.ComboBox (which implements an extended interface deriving from
+this one)
+
+It defines the methods for accessing the control's items and
+although each of the derived classes implements them differently,
+they still all conform to the same interface.
+
+The items in a wx.ItemContainer have (non empty) string labels
+and, optionally, client data associated with them.
+");
+
 class wxItemContainer
 {
 public:
     // wxItemContainer() { m_clientDataItemsType = wxClientData_None; }  ** It's an ABC
     
 
-    // int Append(const wxString& item)
-    // int Append(const wxString& item, void *clientData)
-    // int Append(const wxString& item, wxClientData *clientData)
     %extend {
-        // Adds the item to the control, associating the given data with the
+        DocStr(Append,
-        // item if not None.
+               "Adds the item to the control, associating the given data with the\n"
+               "item if not None.  The return value is the index of the newly\n"
+               "added item which may be different from the last one if the\n"
+               "control is sorted (e.g. has wx.LB_SORT or wx.CB_SORT style).");
         int Append(const wxString& item, PyObject* clientData=NULL) {
             if (clientData) {
                 wxPyClientData* data = new wxPyClientData(clientData);
@@ -93,13 +115,18 @@ public:
         }
     }
     
-    // append several items at once to the control
+    DocDeclStrName(
-    %name(AppendItems) void Append(const wxArrayString& strings);
+        void , Append(const wxArrayString& strings),
+        "Apend several items at once to the control.  Notice that calling\n"
+        "this method may be much faster than appending the items one by\n"
+        "one if you need to add a lot of items.",
+        AppendItems);
+
     
-    // int Insert(const wxString& item, int pos)
-    // int Insert(const wxString& item, int pos, void *clientData);
-    // int Insert(const wxString& item, int pos, wxClientData *clientData);
     %extend {
+        DocStr(Insert,
+               "Insert an item into the control before the item at the pos index,\n"
+               "optionally associating some data object with the item.");
         int Insert(const wxString& item, int pos, PyObject* clientData=NULL) {
             if (clientData) {
                 wxPyClientData* data = new wxPyClientData(clientData);
@@ -110,30 +137,67 @@ public:
     }
     
     
-    // deleting items
+    DocDeclStr(
-    virtual void Clear();
+        virtual void , Clear(),
-    virtual void Delete(int n);
+        "Removes all items from the control.");
+    
+    DocDeclStr(
+        virtual void , Delete(int n),
+        "Deletes the item at the zero-based index 'n' from the control.\n"
+        "Note that it is an error (signalled by a PyAssertionError\n"
+        "exception if enabled) to remove an item with the index negative\n"
+        "or greater or equal than the number of items in the control.");
     
 
-    // accessing strings
+
-    virtual int GetCount() const;
+    DocDeclStr(
-    bool IsEmpty() const;
+        virtual int , GetCount() const,
-    virtual wxString GetString(int n) const;
+        "Returns the number of items in the control.");
-    wxArrayString GetStrings() const;
+    
-    virtual void SetString(int n, const wxString& s);
+    DocDeclStr(
-    virtual int FindString(const wxString& s) const;
+        bool , IsEmpty() const,
+        "Returns True if the control is empty or False if it has some items.");
+    
+    DocDeclStr(
+        virtual wxString , GetString(int n) const,
+        "Returns the label of the item with the given index.");
+    
+    DocDeclStr(
+        wxArrayString , GetStrings() const,
+        "");
+    
+    DocDeclStr(
+        virtual void , SetString(int n, const wxString& s),
+        "Sets the label for the given item.");
+    
+    DocDeclStr(
+        virtual int , FindString(const wxString& s) const,
+        "Finds an item whose label matches the given string.  Returns the\n"
+        "zero-based position of the item, or wx.NOT_FOUND if the string\n"
+        "was not found.");
     
 
-    // selection
-    virtual void Select(int n);
-    virtual int GetSelection() const;
     
-    wxString GetStringSelection() const;
+    DocDeclStr(
+        virtual void , Select(int n),
+        "Sets the item at index 'n' to be the selected item.");
+
+    %pythoncode { SetSelection = Select }
+    
+    DocDeclStr(
+        virtual int , GetSelection() const,
+        "Returns the index of the selected item or wx.NOT_FOUND if no item is selected.");
+    
+
+    DocDeclStr(
+        wxString , GetStringSelection() const,
+        "Returns the label of the selected item or an empty string if no item is selected.");
+    
 
 
-    // client data stuff
     %extend {
-          // Returns the client data associated with the given item, (if any.)
+        DocStr(GetClientData,
+               "Returns the client data associated with the given item, (if any.)");
         PyObject* GetClientData(int n) {
             wxPyClientData* data = (wxPyClientData*)self->GetClientObject(n);
             if (data) {
@@ -145,7 +209,8 @@ public:
             }
         }
 
-        // Associate the given client data with the item at position n.
+        DocStr(SetClientData,
+               "Associate the given client data with the item at position n.");
         void SetClientData(int n, PyObject* clientData) {
             wxPyClientData* data = new wxPyClientData(clientData);
             self->SetClientObject(n, data);
@@ -158,6 +223,11 @@ public:
 //---------------------------------------------------------------------------
 %newgroup;
 
+DocStr(wxControlWithItems,
+"wx.ControlWithItems combines the wx.ItemContainer class with the
+wx.Control class, and is used for the base class of various
+controls that have items.");
+
 class wxControlWithItems : public wxControl, public wxItemContainer
 {
 public: