wxPython/src/_control.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _control.i
   3 // Purpose:     SWIG interface defs for wxControl and other base classes
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     10-June-1998
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2003 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 // Not a %module
  14
  15
  16 //---------------------------------------------------------------------------
  17
  18 MAKE_CONST_WXSTRING(ControlNameStr);
  19
  20 //---------------------------------------------------------------------------
  21 %newgroup;
  22
  23
  24 DocStr(wxControl,
  25 "This is the base class for a control or 'widget'.
  26
  27 A control is generally a small window which processes user input
  28 and/or displays one or more item of data.", "");
  29
  30 class wxControl : public wxWindow
  31 {
  32 public:
  33     %pythonAppend wxControl         "self._setOORInfo(self)"
  34     %pythonAppend wxControl()       ""
  35
  36     DocCtorStr(
  37         wxControl(wxWindow *parent,
  38               wxWindowID id,
  39               const wxPoint& pos=wxDefaultPosition,
  40               const wxSize& size=wxDefaultSize,
  41               long style=0,
  42               const wxValidator& validator=wxDefaultValidator,
  43                   const wxString& name=wxPyControlNameStr),
  44         "Create a Control.  Normally you should only call this from a subclass'
  45 __init__ as a plain old wx.Control is not very useful.", "");
  46
  47     DocCtorStrName(
  48         wxControl(),
  49         "Precreate a Control control for 2-phase creation", "",
  50         PreControl);
  51
  52     DocDeclStr(
  53         bool , Create(wxWindow *parent,
  54                       wxWindowID id,
  55                       const wxPoint& pos=wxDefaultPosition,
  56                       const wxSize& size=wxDefaultSize,
  57                       long style=0,
  58                       const wxValidator& validator=wxDefaultValidator,
  59                       const wxString& name=wxPyControlNameStr),
  60         "Do the 2nd phase and create the GUI control.", "");
  61
  62
  63     DocDeclStr(
  64         void , Command(wxCommandEvent& event),
  65         "Simulates the effect of the user issuing a command to the item.
  66
  67 :see: `wx.CommandEvent`
  68 ", "");
  69
  70     DocDeclStr(
  71         wxString , GetLabel(),
  72         "Return a control's text.", "");
  73
  74     DocDeclStr(
  75         void , SetLabel(const wxString& label),
  76         "Sets the item's text.", "");
  77
  78
  79     static wxVisualAttributes
  80     GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
  81 };
  82
  83
  84 //---------------------------------------------------------------------------
  85 %newgroup;
  86
  87
  88 DocStr(wxItemContainer,
  89 "wx.ItemContainer defines an interface which is implemented by all
  90 controls which have string subitems, each of which may be selected,
  91 such as `wx.ListBox`, `wx.CheckListBox`, `wx.Choice` as well as
  92 `wx.ComboBox` which implements an extended interface deriving from
  93 this one.
  94
  95 It defines the methods for accessing the control's items and although
  96 each of the derived classes implements them differently, they still
  97 all conform to the same interface.
  98
  99 The items in a wx.ItemContainer have (non empty) string labels and,
 100 optionally, client data associated with them.
 101 ", "");
 102
 103 class wxItemContainer
 104 {
 105 public:
 106     // wxItemContainer() { m_clientDataItemsType = wxClientData_None; }  ** It's an ABC
 107
 108
 109     %extend {
 110         DocStr(Append,
 111                "Adds the item to the control, associating the given data with the item
 112 if not None.  The return value is the index of the newly added item
 113 which may be different from the last one if the control is sorted (e.g.
 114 has wx.LB_SORT or wx.CB_SORT style).", "");
 115         int Append(const wxString& item, PyObject* clientData=NULL) {
 116             if (clientData) {
 117                 wxPyClientData* data = new wxPyClientData(clientData);
 118                 return self->Append(item, data);
 119             } else
 120                 return self->Append(item);
 121         }
 122     }
 123
 124     DocDeclStrName(
 125         void , Append(const wxArrayString& strings),
 126         "Apend several items at once to the control.  Notice that calling this
 127 method may be much faster than appending the items one by one if you
 128 need to add a lot of items.", "",
 129         AppendItems);
 130
 131
 132     %extend {
 133         DocStr(Insert,
 134                "Insert an item into the control before the item at the ``pos`` index,
 135 optionally associating some data object with the item.", "");
 136         int Insert(const wxString& item, int pos, PyObject* clientData=NULL) {
 137             if (clientData) {
 138                 wxPyClientData* data = new wxPyClientData(clientData);
 139                 return self->Insert(item, pos, data);
 140             } else
 141                 return self->Insert(item, pos);
 142         }
 143     }
 144
 145
 146     DocDeclStr(
 147         virtual void , Clear(),
 148         "Removes all items from the control.", "");
 149
 150     DocDeclStr(
 151         virtual void , Delete(int n),
 152         "Deletes the item at the zero-based index 'n' from the control. Note
 153 that it is an error (signalled by a `wx.PyAssertionError` exception if
 154 enabled) to remove an item with the index negative or greater or equal
 155 than the number of items in the control.", "");
 156
 157
 158
 159     DocDeclStr(
 160         virtual int , GetCount() const,
 161         "Returns the number of items in the control.", "");
 162
 163     DocDeclStr(
 164         bool , IsEmpty() const,
 165         "Returns True if the control is empty or False if it has some items.", "");
 166
 167     DocDeclStr(
 168         virtual wxString , GetString(int n) const,
 169         "Returns the label of the item with the given index.", "");
 170
 171     DocDeclStr(
 172         wxArrayString , GetStrings() const,
 173         "", "");
 174
 175     DocDeclStr(
 176         virtual void , SetString(int n, const wxString& s),
 177         "Sets the label for the given item.", "");
 178
 179     DocDeclStr(
 180         virtual int , FindString(const wxString& s) const,
 181         "Finds an item whose label matches the given string.  Returns the
 182 zero-based position of the item, or ``wx.NOT_FOUND`` if the string was not
 183 found.", "");
 184
 185
 186
 187     DocDeclStr(
 188         virtual void , Select(int n),
 189         "Sets the item at index 'n' to be the selected item.", "");
 190
 191     %pythoncode { SetSelection = Select }
 192
 193     DocDeclStr(
 194         virtual int , GetSelection() const,
 195         "Returns the index of the selected item or ``wx.NOT_FOUND`` if no item
 196 is selected.", "");
 197
 198
 199     DocDeclStr(
 200         wxString , GetStringSelection() const,
 201         "Returns the label of the selected item or an empty string if no item
 202 is selected.", "");
 203
 204
 205
 206     %extend {
 207         DocStr(GetClientData,
 208                "Returns the client data associated with the given item, (if any.)", "");
 209         PyObject* GetClientData(int n) {
 210             wxPyClientData* data = (wxPyClientData*)self->GetClientObject(n);
 211             if (data) {
 212                 Py_INCREF(data->m_obj);
 213                 return data->m_obj;
 214             } else {
 215                 Py_INCREF(Py_None);
 216                 return Py_None;
 217             }
 218         }
 219
 220         DocStr(SetClientData,
 221                "Associate the given client data with the item at position n.", "");
 222         void SetClientData(int n, PyObject* clientData) {
 223             wxPyClientData* data = new wxPyClientData(clientData);
 224             self->SetClientObject(n, data);
 225         }
 226     }
 227
 228 };
 229
 230
 231 //---------------------------------------------------------------------------
 232 %newgroup;
 233
 234 DocStr(wxControlWithItems,
 235 "wx.ControlWithItems combines the ``wx.ItemContainer`` class with the
 236 wx.Control class, and is used for the base class of various controls
 237 that have items.", "");
 238
 239 class wxControlWithItems : public wxControl, public wxItemContainer
 240 {
 241 public:
 242 };
 243
 244 //---------------------------------------------------------------------------
 245