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