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