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 and/or
  28 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\n"
  45         "subclass' __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\n"
  66         "item. See wxCommandEvent.");
  67
  68     DocDeclStr(
  69         wxString , GetLabel(),
  70         "Return a control's text.");
  71
  72     DocDeclStr(
  73         void , SetLabel(const wxString& label),
  74         "Sets the item's text.");
  75 };
  76
  77
  78 //---------------------------------------------------------------------------
  79 %newgroup;
  80
  81
  82 DocStr(wxItemContainer,
  83 "wx.ItemContainer defines an interface which is implemented by all
  84 controls which have string subitems, each of which may be
  85 selected, such as wx.ListBox, wx.CheckListBox, wx.Choice and
  86 wx.ComboBox (which implements an extended interface deriving from
  87 this one)
  88
  89 It defines the methods for accessing the control's items and
  90 although each of the derived classes implements them differently,
  91 they still all conform to the same interface.
  92
  93 The items in a wx.ItemContainer have (non empty) string labels
  94 and, optionally, client data associated with them.
  95 ");
  96
  97 class wxItemContainer
  98 {
  99 public:
 100     // wxItemContainer() { m_clientDataItemsType = wxClientData_None; }  ** It's an ABC
 101
 102
 103     %extend {
 104         DocStr(Append,
 105                "Adds the item to the control, associating the given data with the\n"
 106                "item if not None.  The return value is the index of the newly\n"
 107                "added item which may be different from the last one if the\n"
 108                "control is sorted (e.g. has wx.LB_SORT or wx.CB_SORT style).");
 109         int Append(const wxString& item, PyObject* clientData=NULL) {
 110             if (clientData) {
 111                 wxPyClientData* data = new wxPyClientData(clientData);
 112                 return self->Append(item, data);
 113             } else
 114                 return self->Append(item);
 115         }
 116     }
 117
 118     DocDeclStrName(
 119         void , Append(const wxArrayString& strings),
 120         "Apend several items at once to the control.  Notice that calling\n"
 121         "this method may be much faster than appending the items one by\n"
 122         "one if you need to add a lot of items.",
 123         AppendItems);
 124
 125
 126     %extend {
 127         DocStr(Insert,
 128                "Insert an item into the control before the item at the pos index,\n"
 129                "optionally associating some data object with the item.");
 130         int Insert(const wxString& item, int pos, PyObject* clientData=NULL) {
 131             if (clientData) {
 132                 wxPyClientData* data = new wxPyClientData(clientData);
 133                 return self->Insert(item, pos, data);
 134             } else
 135                 return self->Insert(item, pos);
 136         }
 137     }
 138
 139
 140     DocDeclStr(
 141         virtual void , Clear(),
 142         "Removes all items from the control.");
 143
 144     DocDeclStr(
 145         virtual void , Delete(int n),
 146         "Deletes the item at the zero-based index 'n' from the control.\n"
 147         "Note that it is an error (signalled by a PyAssertionError\n"
 148         "exception if enabled) to remove an item with the index negative\n"
 149         "or greater or equal than the number of items in the control.");
 150
 151
 152
 153     DocDeclStr(
 154         virtual int , GetCount() const,
 155         "Returns the number of items in the control.");
 156
 157     DocDeclStr(
 158         bool , IsEmpty() const,
 159         "Returns True if the control is empty or False if it has some items.");
 160
 161     DocDeclStr(
 162         virtual wxString , GetString(int n) const,
 163         "Returns the label of the item with the given index.");
 164
 165     DocDeclStr(
 166         wxArrayString , GetStrings() const,
 167         "");
 168
 169     DocDeclStr(
 170         virtual void , SetString(int n, const wxString& s),
 171         "Sets the label for the given item.");
 172
 173     DocDeclStr(
 174         virtual int , FindString(const wxString& s) const,
 175         "Finds an item whose label matches the given string.  Returns the\n"
 176         "zero-based position of the item, or wx.NOT_FOUND if the string\n"
 177         "was not found.");
 178
 179
 180
 181     DocDeclStr(
 182         virtual void , Select(int n),
 183         "Sets the item at index 'n' to be the selected item.");
 184
 185     %pythoncode { SetSelection = Select }
 186
 187     DocDeclStr(
 188         virtual int , GetSelection() const,
 189         "Returns the index of the selected item or wx.NOT_FOUND if no item is selected.");
 190
 191
 192     DocDeclStr(
 193         wxString , GetStringSelection() const,
 194         "Returns the label of the selected item or an empty string if no item is selected.");
 195
 196
 197
 198     %extend {
 199         DocStr(GetClientData,
 200                "Returns the client data associated with the given item, (if any.)");
 201         PyObject* GetClientData(int n) {
 202             wxPyClientData* data = (wxPyClientData*)self->GetClientObject(n);
 203             if (data) {
 204                 Py_INCREF(data->m_obj);
 205                 return data->m_obj;
 206             } else {
 207                 Py_INCREF(Py_None);
 208                 return Py_None;
 209             }
 210         }
 211
 212         DocStr(SetClientData,
 213                "Associate the given client data with the item at position n.");
 214         void SetClientData(int n, PyObject* clientData) {
 215             wxPyClientData* data = new wxPyClientData(clientData);
 216             self->SetClientObject(n, data);
 217         }
 218     }
 219
 220 };
 221
 222
 223 //---------------------------------------------------------------------------
 224 %newgroup;
 225
 226 DocStr(wxControlWithItems,
 227 "wx.ControlWithItems combines the wx.ItemContainer class with the
 228 wx.Control class, and is used for the base class of various
 229 controls that have items.");
 230
 231 class wxControlWithItems : public wxControl, public wxItemContainer
 232 {
 233 public:
 234 };
 235
 236 //---------------------------------------------------------------------------
 237