[wxWidgets.git] / wxPython / src / _combobox.i

/////////////////////////////////////////////////////////////////////////////
// Name:        _combobox.i
// Purpose:     SWIG interface defs for wxComboBox
//
// Author:      Robin Dunn
//
// Created:     10-June-1998
// RCS-ID:      $Id$
// Copyright:   (c) 2003 by Total Control Software
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

// Not a %module


//---------------------------------------------------------------------------

MAKE_CONST_WXSTRING(ComboBoxNameStr);

//---------------------------------------------------------------------------
%newgroup;


DocStr(wxComboBox,
"A combobox is like a combination of an edit control and a
listbox. It can be displayed as static list with editable or
read-only text field; or a drop-down list with text field.

A combobox permits a single selection only. Combobox items are
numbered from zero.", "

Styles
------
    ================    ===============================================
    wx.CB_SIMPLE        Creates a combobox with a permanently
                        displayed list.  Windows only.

    wx.CB_DROPDOWN      Creates a combobox with a drop-down list.

    wx.CB_READONLY      Same as wxCB_DROPDOWN but only the strings
                        specified as the combobox choices can be
                        selected, it is impossible to select
                        (even from a program) a string which is
                        not in the choices list.

    wx.CB_SORT          Sorts the entries in the list alphabetically.
    ================    ===============================================

Events
-------
    ================    ===============================================
    EVT_COMBOBOX        Sent when an item on the list is selected.
                        Note that calling `GetValue` in this handler 
                        will return the newly selected value.
    EVT_TEXT            Sent when the combobox text changes.
    EVT_TEXT_ENTER      Sent when the RETURN/ENTER key is pressed in
                        the combobox.
    ================    ===============================================
");


MustHaveApp(wxComboBox);

#ifdef __WXMSW__
class wxComboBox : public wxChoice
#else
class wxComboBox : public wxControl, public wxItemContainer
#endif
{
public:
    %pythonAppend wxComboBox         "self._setOORInfo(self)"
    %pythonAppend wxComboBox()       ""

    DocCtorAStr(
        wxComboBox(wxWindow* parent, wxWindowID id=-1,
                   const wxString& value = wxPyEmptyString,
                   const wxPoint& pos = wxDefaultPosition,
                   const wxSize& size = wxDefaultSize,
                   const wxArrayString& choices = wxPyEmptyStringArray,
                   long style = 0,
                   const wxValidator& validator = wxDefaultValidator,
                   const wxString& name = wxPyComboBoxNameStr),
        "__init__(Window parent, int id, String value=EmptyString,
    Point pos=DefaultPosition, Size size=DefaultSize,
    List choices=EmptyList, long style=0, Validator validator=DefaultValidator,
    String name=ComboBoxNameStr) -> ComboBox",
        "Constructor, creates and shows a ComboBox control.", "");

    DocCtorStrName(
        wxComboBox(),
        "Precreate a ComboBox control for 2-phase creation.", "",
        PreComboBox);


    DocDeclAStr(
        bool, Create(wxWindow *parent, wxWindowID id=-1,
                     const wxString& value = wxPyEmptyString,
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     const wxArrayString& choices = wxPyEmptyStringArray,
                     long style = 0,
                     const wxValidator& validator = wxDefaultValidator,
                     const wxString& name = wxPyChoiceNameStr),
        "Create(Window parent, int id, String value=EmptyString,
    Point pos=DefaultPosition, Size size=DefaultSize,
    List choices=EmptyList, long style=0, Validator validator=DefaultValidator,
    String name=ChoiceNameStr) -> bool",
        "Actually create the GUI wxComboBox control for 2-phase creation", "");
    

    DocDeclStr(
        virtual wxString , GetValue() const,
        "Returns the current value in the combobox text field.", "");
    
    DocDeclStr(
        virtual void , SetValue(const wxString& value),
        "", "");
    

    DocDeclStr(
        virtual void , Copy(),
        "Copies the selected text to the clipboard.", "");
    
    DocDeclStr(
        virtual void , Cut(),
        "Copies the selected text to the clipboard and removes the selection.", "");
    
    DocDeclStr(
        virtual void , Paste(),
        "Pastes text from the clipboard to the text field.", "");
    
    
    DocDeclStr(
        virtual void , SetInsertionPoint(long pos),
        "Sets the insertion point in the combobox text field.", "");
    
    DocDeclStr(
        virtual long , GetInsertionPoint() const,
        "Returns the insertion point for the combobox's text field.", "");
    
    DocDeclStr(
        virtual long , GetLastPosition() const,
        "Returns the last position in the combobox text field.", "");
    
    DocDeclStr(
        virtual void , Replace(long from, long to, const wxString& value),
        "Replaces the text between two positions with the given text, in the
combobox text field.", "");
    
    DocDeclStr(
        void , SetSelection(int n),
        "Sets the item at index 'n' to be the selected item.", "");
    
    DocDeclStrName(
        virtual void , SetSelection(long from, long to),
        "Selects the text between the two positions in the combobox text field.", "",
        SetMark);    

#ifndef __WXMAC__
    DocDeclAStrName(
        virtual void , GetSelection(long* OUTPUT, long* OUTPUT),
        "GetMark(self) -> (from, to)",
        "Gets the positions of the begining and ending of the selection mark in
the combobox text field.", "",
        GetMark);
#endif

    DocDeclStr(
        int , GetCurrentSelection() const,
        "Unlike `GetSelection` which only returns the accepted selection value,
i.e. the selection in the control once the user closes the dropdown
list, this function returns the current selection.  That is, while the
dropdown list is shown, it returns the currently selected item in
it. When it is not shown, its result is the same as for the other
function.", "");
    
    DocDeclStr(
        bool , SetStringSelection(const wxString& string),
        "Select the item with the specifed string", "");
    
    DocDeclStr(
        void , SetString(int n, const wxString& string),
        "Set the label for the n'th item (zero based) in the list.", "");
    
    DocDeclStr(
        virtual void , SetEditable(bool editable),
        "", "");
    

    DocDeclStr(
        virtual void , SetInsertionPointEnd(),
        "Sets the insertion point at the end of the combobox text field.", "");
    
    DocDeclStr(
        virtual void , Remove(long from, long to),
        "Removes the text between the two positions in the combobox text field.", "");


    DocDeclStr(
        bool , IsEditable() const,
        "Returns True if the combo is ediatable (not read-only.)", "");
    

    DocDeclStr(
        void , Undo(),
        "Redoes the last undo in the text field. Windows only.", "");
    
    DocDeclStr(
        void , Redo(),
        "Undoes the last edit in the text field. Windows only.", "");
    
    DocDeclStr(
        void , SelectAll(),
        "Select all the text in the combo's text field.", "");
    

    DocDeclStr(
        bool , CanCopy() const,
        "Returns True if the combobox is editable and there is a text selection
to copy to the clipboard.  Only available on Windows.", "");
    
    DocDeclStr(
        bool , CanCut() const,
        "Returns True if the combobox is editable and there is a text selection
to copy to the clipboard.  Only available on Windows.", "");
    
    DocDeclStr(
        bool , CanPaste() const,
        "Returns True if the combobox is editable and there is text on the
clipboard that can be pasted into the text field. Only available on
Windows.", "");
    
    DocDeclStr(
        bool , CanUndo() const,
        "Returns True if the combobox is editable and the last edit can be
undone.  Only available on Windows.", "");
    
    DocDeclStr(
        bool , CanRedo() const,
        "Returns True if the combobox is editable and the last undo can be
redone.  Only available on Windows.", "");
    

    static wxVisualAttributes
    GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
};

//---------------------------------------------------------------------------
Commit	Line	Data
d14a1e28 RD	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: _combobox.i
	3	// Purpose: SWIG interface defs for wxComboBox
	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
b2dc1044	18	MAKE_CONST_WXSTRING(ComboBoxNameStr);
d14a1e28 RD	19
	20	//---------------------------------------------------------------------------
	21	%newgroup;
	22
	23
6ad421ae	24	DocStr(wxComboBox,
d07d2bc9 RD	25	"A combobox is like a combination of an edit control and a
	26	listbox. It can be displayed as static list with editable or
	27	read-only text field; or a drop-down list with text field.
	28
	29	A combobox permits a single selection only. Combobox items are
	30	numbered from zero.", "
	31
	32	Styles
	33	------
	34	================ ===============================================
	35	wx.CB_SIMPLE Creates a combobox with a permanently
	36	displayed list. Windows only.
	37
	38	wx.CB_DROPDOWN Creates a combobox with a drop-down list.
	39
	40	wx.CB_READONLY Same as wxCB_DROPDOWN but only the strings
	41	specified as the combobox choices can be
	42	selected, it is impossible to select
	43	(even from a program) a string which is
	44	not in the choices list.
	45
	46	wx.CB_SORT Sorts the entries in the list alphabetically.
	47	================ ===============================================
	48
	49	Events
	50	-------
	51	================ ===============================================
	52	EVT_COMBOBOX Sent when an item on the list is selected.
b7287719 RD	53	Note that calling `GetValue` in this handler
b7287719 RD	54	will return the newly selected value.
d07d2bc9	55	EVT_TEXT Sent when the combobox text changes.
c9463abb RD	56	EVT_TEXT_ENTER Sent when the RETURN/ENTER key is pressed in
c9463abb RD	57	the combobox.
d07d2bc9	58	================ ===============================================
6ad421ae RD	59	");
	60
	61
	62
ab1f7d2a RD	63	MustHaveApp(wxComboBox);
ab1f7d2a RD	64
d14a1e28 RD	65	#ifdef __WXMSW__
	66	class wxComboBox : public wxChoice
	67	#else
	68	class wxComboBox : public wxControl, public wxItemContainer
	69	#endif
	70	{
	71	public:
2b9048c5 RD	72	%pythonAppend wxComboBox "self._setOORInfo(self)"
2b9048c5 RD	73	%pythonAppend wxComboBox() ""
d14a1e28	74
6ad421ae	75	DocCtorAStr(
907c2926	76	wxComboBox(wxWindow* parent, wxWindowID id=-1,
6ad421ae RD	77	const wxString& value = wxPyEmptyString,
	78	const wxPoint& pos = wxDefaultPosition,
	79	const wxSize& size = wxDefaultSize,
	80	const wxArrayString& choices = wxPyEmptyStringArray,
	81	long style = 0,
	82	const wxValidator& validator = wxDefaultValidator,
	83	const wxString& name = wxPyComboBoxNameStr),
d07d2bc9 RD	84	"__init__(Window parent, int id, String value=EmptyString,
d07d2bc9 RD	85	Point pos=DefaultPosition, Size size=DefaultSize,
40a0d6ca	86	List choices=EmptyList, long style=0, Validator validator=DefaultValidator,
d07d2bc9 RD	87	String name=ComboBoxNameStr) -> ComboBox",
d07d2bc9 RD	88	"Constructor, creates and shows a ComboBox control.", "");
6ad421ae RD	89
	90	DocCtorStrName(
	91	wxComboBox(),
d07d2bc9	92	"Precreate a ComboBox control for 2-phase creation.", "",
6ad421ae RD	93	PreComboBox);
	94
	95
	96	DocDeclAStr(
907c2926	97	bool, Create(wxWindow *parent, wxWindowID id=-1,
6ad421ae RD	98	const wxString& value = wxPyEmptyString,
	99	const wxPoint& pos = wxDefaultPosition,
	100	const wxSize& size = wxDefaultSize,
	101	const wxArrayString& choices = wxPyEmptyStringArray,
	102	long style = 0,
	103	const wxValidator& validator = wxDefaultValidator,
	104	const wxString& name = wxPyChoiceNameStr),
d07d2bc9 RD	105	"Create(Window parent, int id, String value=EmptyString,
d07d2bc9 RD	106	Point pos=DefaultPosition, Size size=DefaultSize,
40a0d6ca	107	List choices=EmptyList, long style=0, Validator validator=DefaultValidator,
d07d2bc9 RD	108	String name=ChoiceNameStr) -> bool",
d07d2bc9 RD	109	"Actually create the GUI wxComboBox control for 2-phase creation", "");
6ad421ae RD	110
	111
	112	DocDeclStr(
	113	virtual wxString , GetValue() const,
d07d2bc9	114	"Returns the current value in the combobox text field.", "");
6ad421ae RD	115
	116	DocDeclStr(
	117	virtual void , SetValue(const wxString& value),
d07d2bc9	118	"", "");
6ad421ae RD	119
	120
	121	DocDeclStr(
	122	virtual void , Copy(),
d07d2bc9	123	"Copies the selected text to the clipboard.", "");
6ad421ae RD	124
	125	DocDeclStr(
	126	virtual void , Cut(),
d07d2bc9	127	"Copies the selected text to the clipboard and removes the selection.", "");
6ad421ae RD	128
	129	DocDeclStr(
	130	virtual void , Paste(),
d07d2bc9	131	"Pastes text from the clipboard to the text field.", "");
6ad421ae RD	132
	133
	134	DocDeclStr(
	135	virtual void , SetInsertionPoint(long pos),
d07d2bc9	136	"Sets the insertion point in the combobox text field.", "");
6ad421ae RD	137
	138	DocDeclStr(
	139	virtual long , GetInsertionPoint() const,
d07d2bc9	140	"Returns the insertion point for the combobox's text field.", "");
6ad421ae RD	141
	142	DocDeclStr(
	143	virtual long , GetLastPosition() const,
d07d2bc9	144	"Returns the last position in the combobox text field.", "");
6ad421ae RD	145
	146	DocDeclStr(
	147	virtual void , Replace(long from, long to, const wxString& value),
d07d2bc9 RD	148	"Replaces the text between two positions with the given text, in the
d07d2bc9 RD	149	combobox text field.", "");
6ad421ae RD	150
	151	DocDeclStr(
	152	void , SetSelection(int n),
d07d2bc9	153	"Sets the item at index 'n' to be the selected item.", "");
d14a1e28	154
f8c88923 RD	155	DocDeclStrName(
f8c88923 RD	156	virtual void , SetSelection(long from, long to),
d07d2bc9	157	"Selects the text between the two positions in the combobox text field.", "",
f8c88923	158	SetMark);
d14a1e28	159
e4e84ccd	160	#ifndef __WXMAC__
2c25de3f RD	161	DocDeclAStrName(
	162	virtual void , GetSelection(long* OUTPUT, long* OUTPUT),
	163	"GetMark(self) -> (from, to)",
	164	"Gets the positions of the begining and ending of the selection mark in
	165	the combobox text field.", "",
	166	GetMark);
	167	#endif
	168
02b800ce RD	169	DocDeclStr(
	170	int , GetCurrentSelection() const,
	171	"Unlike `GetSelection` which only returns the accepted selection value,
	172	i.e. the selection in the control once the user closes the dropdown
	173	list, this function returns the current selection. That is, while the
	174	dropdown list is shown, it returns the currently selected item in
	175	it. When it is not shown, its result is the same as for the other
	176	function.", "");
	177
f8c88923 RD	178	DocDeclStr(
f8c88923 RD	179	bool , SetStringSelection(const wxString& string),
d07d2bc9	180	"Select the item with the specifed string", "");
f8c88923 RD	181
	182	DocDeclStr(
	183	void , SetString(int n, const wxString& string),
d07d2bc9	184	"Set the label for the n'th item (zero based) in the list.", "");
f8c88923	185
6ad421ae RD	186	DocDeclStr(
6ad421ae RD	187	virtual void , SetEditable(bool editable),
d07d2bc9	188	"", "");
6ad421ae RD	189
	190
	191	DocDeclStr(
	192	virtual void , SetInsertionPointEnd(),
d07d2bc9	193	"Sets the insertion point at the end of the combobox text field.", "");
6ad421ae RD	194
	195	DocDeclStr(
	196	virtual void , Remove(long from, long to),
d07d2bc9	197	"Removes the text between the two positions in the combobox text field.", "");
c9463abb RD	198
	199
	200
	201	DocDeclStr(
	202	bool , IsEditable() const,
	203	"Returns True if the combo is ediatable (not read-only.)", "");
	204
	205
	206	DocDeclStr(
	207	void , Undo(),
	208	"Redoes the last undo in the text field. Windows only.", "");
	209
	210	DocDeclStr(
	211	void , Redo(),
	212	"Undoes the last edit in the text field. Windows only.", "");
	213
	214	DocDeclStr(
	215	void , SelectAll(),
	216	"Select all the text in the combo's text field.", "");
	217
	218
	219	DocDeclStr(
	220	bool , CanCopy() const,
	221	"Returns True if the combobox is editable and there is a text selection
	222	to copy to the clipboard. Only available on Windows.", "");
	223
	224	DocDeclStr(
	225	bool , CanCut() const,
	226	"Returns True if the combobox is editable and there is a text selection
	227	to copy to the clipboard. Only available on Windows.", "");
	228
	229	DocDeclStr(
	230	bool , CanPaste() const,
	231	"Returns True if the combobox is editable and there is text on the
	232	clipboard that can be pasted into the text field. Only available on
	233	Windows.", "");
	234
	235	DocDeclStr(
	236	bool , CanUndo() const,
	237	"Returns True if the combobox is editable and the last edit can be
	238	undone. Only available on Windows.", "");
	239
	240	DocDeclStr(
	241	bool , CanRedo() const,
	242	"Returns True if the combobox is editable and the last undo can be
	243	redone. Only available on Windows.", "");
	244
	245
6ad421ae	246
880715c9 RD	247	static wxVisualAttributes
880715c9 RD	248	GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
d14a1e28 RD	249	};
	250
	251	//---------------------------------------------------------------------------