Resolve ambiguity between GetClientXXX() methods in wxOSX wxComboBox.
[wxWidgets.git] / interface / wx / choice.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: choice.h
e54c96f1 3// Purpose: interface of wxChoice
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
526954c5 6// Licence: wxWindows licence
23324ae1
FM
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxChoice
7c913512 11
23324ae1 12 A choice item is used to select one of a list of strings. Unlike a
bfac6166 13 wxListBox, only the selection is visible until the user pulls down the
23324ae1 14 menu of choices.
7c913512 15
23324ae1 16 @beginStyleTable
8c6791e4 17 @style{wxCB_SORT}
23324ae1
FM
18 Sorts the entries alphabetically.
19 @endStyleTable
7c913512 20
3051a44a 21 @beginEventEmissionTable{wxCommandEvent}
8c6791e4 22 @event{EVT_CHOICE(id, func)}
3a194bda 23 Process a @c wxEVT_COMMAND_CHOICE_SELECTED event, when an item on the
23324ae1
FM
24 list is selected.
25 @endEventTable
7c913512 26
23324ae1
FM
27 @library{wxcore}
28 @category{ctrl}
7e59b885 29 @appearance{choice.png}
7c913512 30
e54c96f1 31 @see wxListBox, wxComboBox, wxCommandEvent
23324ae1
FM
32*/
33class wxChoice : public wxControlWithItems
34{
35public:
bfac6166
BP
36 /**
37 Default constructor.
38
39 @see Create(), wxValidator
40 */
41 wxChoice();
42
23324ae1
FM
43 /**
44 Constructor, creating and showing a choice.
3c4f71cc 45
7c913512 46 @param parent
4cc4bfaf 47 Parent window. Must not be @NULL.
7c913512 48 @param id
4cc4bfaf 49 Window identifier. The value wxID_ANY indicates a default value.
7c913512 50 @param pos
4cc4bfaf 51 Window position.
dc1b07fd 52 If ::wxDefaultPosition is specified then a default position is chosen.
7c913512 53 @param size
dc1b07fd
FM
54 Window size.
55 If ::wxDefaultSize is specified then the choice is sized appropriately.
7c913512 56 @param n
4cc4bfaf 57 Number of strings with which to initialise the choice control.
7c913512 58 @param choices
4cc4bfaf 59 An array of strings with which to initialise the choice control.
7c913512 60 @param style
4cc4bfaf 61 Window style. See wxChoice.
7c913512 62 @param validator
4cc4bfaf 63 Window validator.
7c913512 64 @param name
4cc4bfaf 65 Window name.
3c4f71cc 66
4cc4bfaf 67 @see Create(), wxValidator
bfac6166
BP
68
69 @beginWxPythonOnly
70
71 The wxChoice constructor in wxPython reduces the @a n and @a choices
72 arguments to a single argument, which is a list of strings.
73
74 @endWxPythonOnly
1058f652
MB
75
76 @beginWxPerlOnly
77 Not supported by wxPerl.
78 @endWxPerlOnly
23324ae1 79 */
882678eb
FM
80 wxChoice( wxWindow *parent, wxWindowID id,
81 const wxPoint& pos = wxDefaultPosition,
82 const wxSize& size = wxDefaultSize,
83 int n = 0, const wxString choices[] = NULL,
84 long style = 0,
85 const wxValidator& validator = wxDefaultValidator,
86 const wxString& name = wxChoiceNameStr );
792255cc
VZ
87
88 /**
89 Constructor, creating and showing a choice.
90
91 @param parent
92 Parent window. Must not be @NULL.
93 @param id
94 Window identifier. The value wxID_ANY indicates a default value.
95 @param pos
96 Window position.
97 @param size
98 Window size. If wxDefaultSize is specified then the choice is sized
99 appropriately.
100 @param choices
101 An array of strings with which to initialise the choice control.
102 @param style
103 Window style. See wxChoice.
104 @param validator
105 Window validator.
106 @param name
107 Window name.
108
109 @see Create(), wxValidator
110
111 @beginWxPythonOnly
112
113 The wxChoice constructor in wxPython reduces the @a n and @a choices
114 arguments to a single argument, which is a list of strings.
115
116 @endWxPythonOnly
1058f652
MB
117
118 @beginWxPerlOnly
119 Use an array reference for the @a choices parameter.
120 @endWxPerlOnly
792255cc 121 */
882678eb
FM
122 wxChoice( wxWindow *parent, wxWindowID id,
123 const wxPoint& pos,
124 const wxSize& size,
125 const wxArrayString& choices,
126 long style = 0,
127 const wxValidator& validator = wxDefaultValidator,
128 const wxString& name = wxChoiceNameStr );
23324ae1
FM
129
130 /**
131 Destructor, destroying the choice item.
132 */
b7e94bd7 133 virtual ~wxChoice();
23324ae1
FM
134
135 //@{
136 /**
137 Creates the choice for two-step construction. See wxChoice().
138 */
882678eb
FM
139 bool Create( wxWindow *parent, wxWindowID id,
140 const wxPoint& pos = wxDefaultPosition,
141 const wxSize& size = wxDefaultSize,
142 int n = 0, const wxString choices[] = NULL,
143 long style = 0,
144 const wxValidator& validator = wxDefaultValidator,
145 const wxString& name = wxChoiceNameStr );
146 bool Create( wxWindow *parent, wxWindowID id,
147 const wxPoint& pos,
148 const wxSize& size,
149 const wxArrayString& choices,
150 long style = 0,
151 const wxValidator& validator = wxDefaultValidator,
152 const wxString& name = wxChoiceNameStr );
23324ae1
FM
153 //@}
154
155 /**
156 Gets the number of columns in this choice item.
3c4f71cc 157
882678eb 158 @remarks This is implemented for GTK and Motif only and always
3f16e52c 159 returns 1 for the other platforms.
23324ae1 160 */
b7e94bd7 161 virtual int GetColumns() const;
23324ae1
FM
162
163 /**
bfac6166
BP
164 Unlike wxControlWithItems::GetSelection() which only returns the
165 accepted selection value, i.e. the selection in the control once the
166 user closes the dropdown list, this function returns the current
167 selection. That is, while the dropdown list is shown, it returns the
168 currently selected item in it. When it is not shown, its result is the
169 same as for the other function.
170
1e24c2af
VS
171 @since 2.6.2.
172 In older versions, wxControlWithItems::GetSelection() itself
173 behaved like this.
23324ae1 174 */
b7e94bd7 175 virtual int GetCurrentSelection() const;
23324ae1
FM
176
177 /**
178 Sets the number of columns in this choice item.
3c4f71cc 179
7c913512 180 @param n
4cc4bfaf 181 Number of columns.
bfac6166 182
882678eb 183 @remarks This is implemented for GTK and Motif only and doesn’t do
3f16e52c 184 anything under other platforms.
23324ae1 185 */
b7e94bd7 186 virtual void SetColumns(int n = 1);
23324ae1 187};
e54c96f1 188