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         int , GetAlignment() const,
  72         "Get the control alignment (left/right/centre, top/bottom/centre)", "");
  73
  74
  75     DocDeclStr(
  76         wxString , GetLabelText() const,
  77         "Get just the text of the label, without mnemonic characters ('&')", "");
  78
  79
  80
  81     DocDeclStr(
  82         void , Command(wxCommandEvent& event),
  83         "Simulates the effect of the user issuing a command to the item.
  84
  85 :see: `wx.CommandEvent`
  86 ", "");
  87
  88
  89 //     DocDeclStr(
  90 //         bool , GetAdjustMinSizeFlag(),
  91 //         "Returns whether the minsize should be adjusted for this control when
  92 // `SetLabel` or `SetFont` are called.", "");
  93
  94 //     DocDeclStr(
  95 //         void , SetAdjustMinSizeFlag(bool adjust),
  96 //         "By default controls will readjust their size and minsize when
  97 // `SetLabel` or `SetFont` are called.  This flag will allow you to
  98 // control this behavior.", "
  99
 100 // :see: `GetAdjustMinSizeFlag`
 101 // ");
 102
 103     static wxVisualAttributes
 104     GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
 105
 106     %property(Alignment, GetAlignment, doc="See `GetAlignment`");
 107     %property(LabelText, GetLabelText, doc="See `GetLabelText`");
 108
 109 };
 110
 111
 112 //---------------------------------------------------------------------------
 113 %newgroup;
 114
 115
 116
 117
 118 DocStr(wxItemContainer,
 119 "The wx.ItemContainer class defines an interface which is implemented
 120 by all controls which have string subitems, each of which may be
 121 selected, such as `wx.ListBox`, `wx.CheckListBox`, `wx.Choice` as well
 122 as `wx.ComboBox` which implements an extended interface deriving from
 123 this one.
 124
 125 It defines the methods for accessing the control's items and although
 126 each of the derived classes implements them differently, they still
 127 all conform to the same interface.
 128
 129 The items in a wx.ItemContainer have (non empty) string labels and,
 130 optionally, client data associated with them.
 131 ", "");
 132
 133 class wxItemContainer
 134 {
 135 public:
 136     // wxItemContainer()  ** It's an ABC
 137
 138
 139     %extend {
 140         DocStr(Append,
 141                "Adds the item to the control, associating the given data with the item
 142 if not None.  The return value is the index of the newly added item
 143 which may be different from the last one if the control is sorted (e.g.
 144 has wx.LB_SORT or wx.CB_SORT style).", "");
 145         int Append(const wxString& item, PyObject* clientData=NULL) {
 146             if (clientData) {
 147                 wxPyClientData* data = new wxPyClientData(clientData);
 148                 return self->Append(item, data);
 149             } else
 150                 return self->Append(item);
 151         }
 152     }
 153
 154     DocDeclAStrName(
 155         void , Append(const wxArrayString& strings),
 156         "AppendItems(self, List strings)",
 157         "Apend several items at once to the control.  Notice that calling this
 158 method may be much faster than appending the items one by one if you
 159 need to add a lot of items.", "",
 160         AppendItems);
 161
 162
 163     %extend {
 164         DocStr(Insert,
 165                "Insert an item into the control before the item at the ``pos`` index,
 166 optionally associating some data object with the item.", "");
 167         int Insert(const wxString& item, unsigned int pos, PyObject* clientData=NULL) {
 168             if (clientData) {
 169                 wxPyClientData* data = new wxPyClientData(clientData);
 170                 return self->Insert(item, pos, data);
 171             } else
 172                 return self->Insert(item, pos);
 173         }
 174     }
 175
 176
 177     DocDeclStr(
 178         virtual void , Clear(),
 179         "Removes all items from the control.", "");
 180
 181     DocDeclStr(
 182         virtual void , Delete(unsigned int n),
 183         "Deletes the item at the zero-based index 'n' from the control. Note
 184 that it is an error (signalled by a `wx.PyAssertionError` exception if
 185 enabled) to remove an item with the index negative or greater or equal
 186 than the number of items in the control.", "");
 187
 188
 189
 190
 191      %extend {
 192         DocStr(GetClientData,
 193                "Returns the client data associated with the given item, (if any.)", "");
 194         PyObject* GetClientData(unsigned int n) {
 195             wxPyClientData* data = (wxPyClientData*)self->GetClientObject(n);
 196             if (data) {
 197                 Py_INCREF(data->m_obj);
 198                 return data->m_obj;
 199             } else {
 200                 Py_INCREF(Py_None);
 201                 return Py_None;
 202             }
 203         }
 204
 205         DocStr(SetClientData,
 206                "Associate the given client data with the item at position n.", "");
 207         void SetClientData(unsigned int n, PyObject* clientData) {
 208             wxPyClientData* data = new wxPyClientData(clientData);
 209             self->SetClientObject(n, data);
 210         }
 211     }
 212
 213
 214
 215     DocDeclStr(
 216         virtual unsigned int , GetCount() const,
 217         "Returns the number of items in the control.", "");
 218
 219     DocDeclStr(
 220         bool , IsEmpty() const,
 221         "Returns True if the control is empty or False if it has some items.", "");
 222
 223     DocDeclStr(
 224         virtual wxString , GetString(unsigned int n) const,
 225         "Returns the label of the item with the given index.", "");
 226
 227     DocDeclStr(
 228         wxArrayString , GetStrings() const,
 229         "", "");
 230
 231     DocDeclStr(
 232         virtual void , SetString(unsigned int n, const wxString& s),
 233         "Sets the label for the given item.", "");
 234
 235     DocDeclStr(
 236         virtual int , FindString(const wxString& s) const,
 237         "Finds an item whose label matches the given string.  Returns the
 238 zero-based position of the item, or ``wx.NOT_FOUND`` if the string was not
 239 found.", "");
 240
 241
 242     DocDeclStr(
 243         virtual void , SetSelection(int n),
 244         "Sets the item at index 'n' to be the selected item.", "");
 245
 246     DocDeclStr(
 247         virtual int , GetSelection() const,
 248         "Returns the index of the selected item or ``wx.NOT_FOUND`` if no item
 249 is selected.", "");
 250
 251
 252     bool SetStringSelection(const wxString& s);
 253
 254     DocDeclStr(
 255         wxString , GetStringSelection() const,
 256         "Returns the label of the selected item or an empty string if no item
 257 is selected.", "");
 258
 259
 260     DocDeclStr(
 261         void , Select(int n),
 262         "This is the same as `SetSelection` and exists only because it is
 263 slightly more natural for controls which support multiple selection.", "");
 264
 265
 266     %pythoncode {
 267         def GetItems(self):
 268             """Return a list of the strings in the control"""
 269             return [self.GetString(i) for i in xrange(self.GetCount())]
 270
 271         def SetItems(self, items):
 272             """Clear and set the strings in the control from a list"""
 273             self.Clear()
 274             for i in items:
 275                 self.Append(i)
 276     }
 277
 278     %property(Count, GetCount, doc="See `GetCount`");
 279     %property(Items, GetItems, SetItems, doc="See `GetItems` and `SetItems`");
 280     %property(Selection, GetSelection, SetSelection, doc="See `GetSelection` and `SetSelection`");
 281     %property(StringSelection, GetStringSelection, SetStringSelection, doc="See `GetStringSelection` and `SetStringSelection`");
 282     %property(Strings, GetStrings, doc="See `GetStrings`");
 283
 284 };
 285
 286
 287 //---------------------------------------------------------------------------
 288 %newgroup;
 289
 290 DocStr(wxControlWithItems,
 291 "wx.ControlWithItems combines the ``wx.ItemContainer`` class with the
 292 wx.Control class, and is used for the base class of various controls
 293 that have items.", "");
 294
 295 class wxControlWithItems : public wxControl, public wxItemContainer
 296 {
 297 public:
 298 };
 299
 300 //---------------------------------------------------------------------------
 301