%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:
- %addtofunc wxControl "self._setOORInfo(self)"
- %addtofunc wxControl() ""
+ %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);
-
- %name(PreControl)wxControl();
-
- 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);
+ 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);
+
+ 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.", "");
+
- // Return a control's text.
- wxString GetLabel();
+ DocDeclStr(
+ void , Command(wxCommandEvent& event),
+ "Simulates the effect of the user issuing a command to the item.
- // Sets the item's text.
- void SetLabel(const wxString& label);
+:see: `wx.CommandEvent`
+", "");
+
+ DocDeclStr(
+ wxString , GetLabel(),
+ "Return a control's text.", "");
+
+ DocDeclStr(
+ void , SetLabel(const wxString& label),
+ "Sets the item's text.", "");
+
+ static wxVisualAttributes
+ GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
};
%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` 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.
+", "");
+
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 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);
}
}
- // 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 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);
}
- // 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. 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.", "");
+
- // 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
+zero-based position of the item, or ``wx.NOT_FOUND`` if the string 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) {
}
}
- // 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);
//---------------------------------------------------------------------------
%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:
projects / wxWidgets.git / blobdiff