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