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