X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b2dc104421c340091342156d6b01f61f1ccff438..32485259c1342115488d219776dfebeb3d4d81b1:/wxPython/src/_control.i diff --git a/wxPython/src/_control.i b/wxPython/src/_control.i index 1035fbb4f7..64326a0c32 100644 --- a/wxPython/src/_control.i +++ b/wxPython/src/_control.i @@ -21,69 +21,120 @@ 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.", ""); + +MustHaveApp(wxControl); + class wxControl : public wxWindow { public: - %addtofunc wxControl "self._setOORInfo(self)" - %addtofunc wxControl() "" + %pythonAppend wxControl "self._setOORInfo(self)" + %pythonAppend wxControl() "" + %typemap(out) wxControl*; // turn off this typemap + + DocCtorStr( + wxControl(wxWindow *parent, + wxWindowID id=-1, + const wxPoint& pos=wxDefaultPosition, + const wxSize& size=wxDefaultSize, + long style=0, + const wxValidator& validator=wxDefaultValidator, + const wxString& name=wxPyControlNameStr), + "Create a Control. Normally you should only call this from a subclass' +__init__ as a plain old wx.Control is not very useful.", ""); + + DocCtorStrName( + wxControl(), + "Precreate a Control control for 2-phase creation", "", + PreControl); + + // Turn it back on again + %typemap(out) wxControl* { $result = wxPyMake_wxObject($1, $owner); } + + + DocDeclStr( + bool , Create(wxWindow *parent, + wxWindowID id=-1, + 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.", ""); + - wxControl(wxWindow *parent, - wxWindowID id, - const wxPoint& pos=wxDefaultPosition, - const wxSize& size=wxDefaultSize, - long style=0, - const wxValidator& validator=wxDefaultValidator, - const wxString& name=wxPyControlNameStr); + DocDeclStr( + void , Command(wxCommandEvent& event), + "Simulates the effect of the user issuing a command to the item. - %name(PreControl)wxControl(); +:see: `wx.CommandEvent` +", ""); + + DocDeclStr( + wxString , GetLabel(), + "Return a control's text.", ""); + + DocDeclStr( + void , SetLabel(const wxString& label), + "Sets the item's text.", ""); - 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); +// DocDeclStr( +// bool , GetAdjustMinSizeFlag(), +// "Returns whether the minsize should be adjusted for this control when +// `SetLabel` or `SetFont` are called.", ""); + +// DocDeclStr( +// void , SetAdjustMinSizeFlag(bool adjust), +// "By default controls will readjust their size and minsize when +// `SetLabel` or `SetFont` are called. This flag will allow you to +// control this behavior.", " + +// :see: `GetAdjustMinSizeFlag` +// "); + + static wxVisualAttributes + GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); +}; - // 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(); +//--------------------------------------------------------------------------- +%newgroup; - // Sets the item's text. - void SetLabel(const wxString& label); -}; -//--------------------------------------------------------------------------- -%newgroup; +DocStr(wxItemContainer, +"The wx.ItemContainer class 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` as well +as `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. +", ""); -// 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) class wxItemContainer { public: - // wxItemContainer() { m_clientDataItemsType = wxClientData_None; } ** It's an ABC - + // wxItemContainer() ** 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 item +if not None. The return value is the index of the newly added item +which may be different from the last one if the 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 +144,19 @@ public: } } - // append several items at once to the control - %name(AppendItems) void Append(const wxArrayString& strings); + DocDeclAStrName( + void , Append(const wxArrayString& strings), + "AppendItems(self, List strings)", + "Apend several items at once to the control. Notice that calling this +method may be much faster than appending the items one by 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, +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 +167,23 @@ public: } - // deleting items - virtual void Clear(); - virtual void Delete(int n); - - - // 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 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. Note +that it is an error (signalled by a `wx.PyAssertionError` exception if +enabled) to remove an item with the index negative or greater or equal +than the number of items in the control.", ""); - // selection - virtual void Select(int n); - virtual int GetSelection() const; - - wxString GetStringSelection() const; - // client data stuff - %extend { - // Returns the client data associated with the given item, (if any.) + + %extend { + 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,19 +195,79 @@ 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); } } - + + + + 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 +zero-based position of the item, or ``wx.NOT_FOUND`` if the string was not +found.", ""); + + + DocDeclStr( + virtual void , SetSelection(int n), + "Sets the item at index 'n' to be the selected item.", ""); + + DocDeclStr( + virtual int , GetSelection() const, + "Returns the index of the selected item or ``wx.NOT_FOUND`` if no item +is selected.", ""); + + + bool SetStringSelection(const wxString& s); + + DocDeclStr( + wxString , GetStringSelection() const, + "Returns the label of the selected item or an empty string if no item +is selected.", ""); + + + DocDeclStr( + void , Select(int n), + "This is the same as `SetSelection` and exists only because it is +slightly more natural for controls which support multiple selection.", ""); + + + }; //--------------------------------------------------------------------------- %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: