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