From 861d483291fc24105808125c6fa442b882f3c622 Mon Sep 17 00:00:00 2001 From: Robin Dunn Date: Tue, 24 Feb 2004 02:09:17 +0000 Subject: [PATCH] Added docstrings git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@25937 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- wxPython/src/_constraints.i | 235 ++++++++++++++++++++++++++++-------- wxPython/src/_control.i | 186 +++++++++++++++++++--------- 2 files changed, 310 insertions(+), 111 deletions(-) diff --git a/wxPython/src/_constraints.i b/wxPython/src/_constraints.i index 2bf490f82c..664e8bff30 100644 --- a/wxPython/src/_constraints.i +++ b/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( + void , LeftOf(wxWindow *sibling, int marg = 0), + "Sibling relationship"); + + DocDeclStr( + void , RightOf(wxWindow *sibling, int marg = 0), + "Sibling relationship"); + + DocDeclStr( + void , Above(wxWindow *sibling, int marg = 0), + "Sibling relationship"); + + DocDeclStr( + void , Below(wxWindow *sibling, int marg = 0), + "Sibling relationship"); - // - // 'Same edge' alignment - // - void SameAs(wxWindow *otherW, wxEdge edge, int marg = 0); + DocDeclStr( + void , SameAs(wxWindow *otherW, wxEdge edge, int marg = 0), + "'Same edge' alignment"); + - // The edge is a percentage of the other window's edge - void PercentOf(wxWindow *otherW, wxEdge wh, int per); + DocDeclStr( + void , PercentOf(wxWindow *otherW, wxEdge wh, int per), + "The edge is a percentage of the other window's edge"); + - // - // Edge has absolute value - // - void Absolute(int val); + DocDeclStr( + void , Absolute(int val), + "Edge has absolute value"); - // - // Dimension is unconstrained - // - void Unconstrained() { relationship = wxUnconstrained; } + DocDeclStr( + void , Unconstrained(), + "Dimension is unconstrained"); + - // - // Dimension is 'as is' (use current size settings) - // - void AsIs() { relationship = wxAsIs; } + DocDeclStr( + void , AsIs(), + "Dimension is 'as is' (use current size settings)"); + - // - // 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); + 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), + ""); + - // Reset constraint if it mentions otherWin - bool ResetIfWin(wxWindow *otherW); + DocDeclStr( + bool , ResetIfWin(wxWindow *otherW), + "Reset constraint if it mentions otherWin"); + - // Try to satisfy constraint - bool SatisfyConstraint(wxLayoutConstraints *constraints, wxWindow *win); - - // Get the value of this edge or dimension, or if this - // is not determinable, -1. - int GetEdge(wxEdge which, wxWindow *thisWin, wxWindow *other) const; + 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(); + %mutable; + + DocCtorStr( + wxLayoutConstraints(), + ""); DocDeclA( bool, SatisfyConstraints(wxWindow *win, int *OUTPUT), diff --git a/wxPython/src/_control.i b/wxPython/src/_control.i index 69c67f3da3..460f5fda47 100644 --- a/wxPython/src/_control.i +++ b/wxPython/src/_control.i @@ -21,45 +21,57 @@ MAKE_CONST_WXSTRING(ControlNameStr); %newgroup; -// 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. +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."); + class wxControl : public wxWindow { public: %pythonAppend wxControl "self._setOORInfo(self)" %pythonAppend wxControl() "" - wxControl(wxWindow *parent, + 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, - wxWindowID id, - const wxPoint& pos=wxDefaultPosition, - const wxSize& size=wxDefaultSize, - long style=0, - const wxValidator& validator=wxDefaultValidator, - const wxString& name=wxPyControlNameStr); - - - // Simulates the effect of the user issuing a command to the item. See - // wxCommandEvent. - void Command(wxCommandEvent& event); - - // Return a control's text. - wxString GetLabel(); - - // Sets the item's text. - void SetLabel(const wxString& label); + 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), + "Do the 2nd phase and create the GUI control."); + + DocDeclStr( + void , Command(wxCommandEvent& event), + "Simulates the effect of the user issuing a command to the\n" + "item. See wxCommandEvent."); + + DocDeclStr( + wxString , GetLabel(), + "Return a control's text."); + + 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 -// which have string subitems each of which may be selected. -// -// Examples: wxListBox, wxCheckListBox, wxChoice and wxComboBox (which -// implements an extended interface deriving from this one) +DocStr(wxItemContainer, +"wx.ItemContainer defines an interface which is implemented by all +controls which have string subitems, each of which may be +selected, such as wx.ListBox, wx.CheckListBox, wx.Choice and +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 - // item if not None. + DocStr(Append, + "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 - %name(AppendItems) void Append(const wxArrayString& strings); + DocDeclStrName( + 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 - virtual void Clear(); - virtual void Delete(int n); + DocDeclStr( + virtual void , Clear(), + "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; - bool IsEmpty() const; - virtual wxString GetString(int n) const; - wxArrayString GetStrings() const; - virtual void SetString(int n, const wxString& s); - virtual int FindString(const wxString& s) const; + DocDeclStr( + virtual int , GetCount() const, + "Returns the number of items in the control."); + + DocDeclStr( + 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; + DocDeclStr( + virtual void , Select(int n), + "Sets the item at index 'n' to be the selected item."); - wxString GetStringSelection() const; + %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: