]>
git.saurik.com Git - wxWidgets.git/blob - interface/listbox.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxListBox
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
13 A listbox is used to select one or more of a list of strings. The
14 strings are displayed in a scrolling box, with the selected string(s)
15 marked in reverse video. A listbox can be single selection (if an item
16 is selected, the previous selection is removed) or multiple selection
17 (clicking an item toggles the item on or off independently of other
20 List box elements are numbered from zero. Their number may be limited
23 A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for single
25 wxEVT_COMMAND_LISTBOX_DOUBLECLICKED for double clicks.
29 Single-selection list.
31 Multiple-selection list: the user can toggle multiple items on and
34 Extended-selection list: the user can select multiple items using
35 the SHIFT key and the mouse or special key combinations.
37 Create horizontal scrollbar if contents are too wide (Windows only).
38 @style{wxLB_ALWAYS_SB}
39 Always show a vertical scrollbar.
40 @style{wxLB_NEEDED_SB}
41 Only create a vertical scrollbar if needed.
43 The listbox contents are sorted in alphabetical order.
46 @beginEventTable{wxCommandEvent}
47 @event{EVT_LISTBOX(id, func)}
48 Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the
49 list is selected or the selection changes.
50 @event{EVT_LISTBOX_DCLICK(id, func)}
51 Process a wxEVT_COMMAND_LISTBOXDOUBLECLICKED event, when the
52 listbox is double-clicked.
57 @appearance{listbox.png}
59 @see wxChoice, wxComboBox, wxListCtrl, wxCommandEvent
61 class wxListBox
: public wxControlWithItems
66 Constructor, creating and showing a list box.
69 Parent window. Must not be @NULL.
71 Window identifier. The value wxID_ANY indicates a default value.
75 Window size. If wxDefaultSize is specified then the window is
79 Number of strings with which to initialise the control.
81 An array of strings with which to initialise the control.
83 Window style. See wxListBox.
89 @see Create(), wxValidator
92 wxListBox(wxWindow
* parent
, wxWindowID id
,
93 const wxPoint
& pos
= wxDefaultPosition
,
94 const wxSize
& size
= wxDefaultSize
,
96 const wxString choices
[] = NULL
,
98 const wxValidator
& validator
= wxDefaultValidator
,
99 const wxString
& name
= "listBox");
100 wxListBox(wxWindow
* parent
, wxWindowID id
,
103 const wxArrayString
& choices
,
105 const wxValidator
& validator
= wxDefaultValidator
,
106 const wxString
& name
= "listBox");
110 Destructor, destroying the list box.
116 Creates the listbox for two-step construction. See wxListBox()
119 bool Create(wxWindow
* parent
, wxWindowID id
,
120 const wxPoint
& pos
= wxDefaultPosition
,
121 const wxSize
& size
= wxDefaultSize
,
123 const wxString choices
[] = NULL
,
125 const wxValidator
& validator
= wxDefaultValidator
,
126 const wxString
& name
= "listBox");
127 bool Create(wxWindow
* parent
, wxWindowID id
,
130 const wxArrayString
& choices
,
132 const wxValidator
& validator
= wxDefaultValidator
,
133 const wxString
& name
= "listBox");
137 Deselects an item in the list box.
140 The zero-based item to deselect.
142 @remarks This applies to multiple selection listboxes only.
144 void Deselect(int n
);
147 Fill an array of ints with the positions of the currently selected items.
150 A reference to an wxArrayInt instance that is used to store the result of
153 @returns The number of selections.
155 @remarks Use this with a multiple selection listbox.
157 @see wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection,
158 wxControlWithItems::SetSelection
160 int GetSelections(wxArrayInt
& selections
) const;
163 Returns the item located at @e point, or @c wxNOT_FOUND if there
164 is no item located at @e point.
166 It is currently implemented for wxMSW, wxMac and wxGTK2 ports.
169 Point of item (in client coordinates) to obtain
171 @returns Item located at point, or wxNOT_FOUND if unimplemented or the
176 int HitTest(const wxPoint point
) const;
180 Insert the given number of strings before the specified position.
183 Number of items in the array items
185 Labels of items to be inserted
187 Position before which to insert the items: for example, if pos is 0 the
189 will be inserted in the beginning of the listbox
191 void InsertItems(int nItems
, const wxString items
,
193 void InsertItems(const wxArrayString
& nItems
,
198 Determines whether an item is selected.
201 The zero-based item index.
203 @returns @true if the given item is selected, @false otherwise.
205 bool IsSelected(int n
) const;
209 Clears the list box and adds the given strings to it.
212 The number of strings to set.
214 An array of strings to set.
216 Options array of client data pointers
218 @remarks You may free the array from the calling program after this
219 function has been called.
221 void Set(int n
, const wxString
* choices
, void clientData
= NULL
);
222 void Set(const wxArrayString
& choices
,
223 void clientData
= NULL
);
228 Set the specified item to be the first visible item.
231 The zero-based item index.
233 The string that should be visible.
235 void SetFirstItem(int n
);
236 void SetFirstItem(const wxString
& string
);