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