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