]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/vlbox.h
Corrected library association
[wxWidgets.git] / interface / wx / vlbox.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: vlbox.h
3 // Purpose: interface of wxVListBox
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxVListBox
11
12 wxVListBox is a wxListBox-like control with the following two main
13 differences from a regular wxListBox: it can have an arbitrarily huge
14 number of items because it doesn't store them itself but uses the
15 OnDrawItem() callback to draw them (so it is a virtual listbox) and its
16 items can have variable height as determined by OnMeasureItem() (so it is
17 also a listbox with the lines of variable height).
18
19 Also, as a consequence of its virtual nature, it doesn't have any methods
20 to append or insert items in it as it isn't necessary to do it: you just
21 have to call SetItemCount() to tell the control how many items it should
22 display. Of course, this also means that you will never use this class
23 directly because it has pure virtual functions, but will need to derive
24 your own class from it (for example, wxHtmlListBox).
25
26 However it emits the same events as wxListBox and the same event macros may
27 be used with it. Since wxVListBox does not store its items itself, the
28 events will only contain the index, not any contents such as the string of
29 an item.
30
31 @library{wxcore}
32 @category{ctrl}
33 @appearance{vlistbox.png}
34
35 @see wxSimpleHtmlListBox, wxHtmlListBox
36 */
37 class wxVListBox : public wxVScrolledWindow
38 {
39 public:
40 /**
41 Default constructor, you must call Create() later.
42 */
43 wxVListBox();
44 /**
45 Normal constructor which calls Create() internally.
46 */
47 wxVListBox(wxWindow* parent, wxWindowID id = wxID_ANY,
48 const wxPoint& pos = wxDefaultPosition,
49 const wxSize& size = wxDefaultSize,
50 long style = 0, const wxString& name = wxVListBoxNameStr);
51
52 /**
53 Destructor.
54 */
55 virtual ~wxVListBox();
56
57 /**
58 Deletes all items from the control.
59 */
60 void Clear();
61
62 /**
63 Creates the control. To finish creating it you also should call
64 SetItemCount() to let it know about the number of items it contains.
65
66 The only special style which may be used with wxVListBox is
67 @c wxLB_MULTIPLE which indicates that the listbox should support
68 multiple selection.
69
70 @return @true on success or @false if the control couldn't be created.
71 */
72 bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
73 const wxPoint& pos = wxDefaultPosition,
74 const wxSize& size = wxDefaultSize, long style = 0,
75 const wxString& name = wxVListBoxNameStr);
76
77 /**
78 Deselects all the items in the listbox. This method is only valid for
79 multi selection listboxes.
80
81 @return @true if any items were changed, i.e. if there had been any
82 selected items before, or @false if all the items were already
83 deselected.
84
85 @see SelectAll(), Select()
86 */
87 bool DeselectAll();
88
89 /**
90 Returns the index of the first selected item in the listbox or
91 @c wxNOT_FOUND if no items are currently selected.
92
93 @a cookie is an opaque parameter which should be passed to the
94 subsequent calls to GetNextSelected(). It is needed in order to allow
95 parallel iterations over the selected items.
96
97 Here is a typical example of using these functions:
98
99 @code
100 unsigned long cookie;
101 int item = hlbox->GetFirstSelected(cookie);
102 while ( item != wxNOT_FOUND )
103 {
104 // ... process item ...
105 item = hlbox->GetNextSelected(cookie);
106 }
107 @endcode
108
109 This method is only valid for multi selection listboxes.
110 */
111 int GetFirstSelected(unsigned long& cookie) const;
112
113 /**
114 Get the number of items in the control.
115
116 @see SetItemCount()
117 */
118 size_t GetItemCount() const;
119
120 /**
121 Returns the margins used by the control. The @c x field of the returned
122 point is the horizontal margin and the @c y field is the vertical one.
123
124 @see SetMargins()
125 */
126 wxPoint GetMargins() const;
127
128 /**
129 Returns the rectangle occupied by this item in physical coordinates.
130
131 If the item is not currently visible, returns an empty rectangle.
132
133 @since 2.9.0
134 */
135 wxRect GetItemRect(size_t item) const;
136
137 /**
138 Returns the index of the next selected item or @c wxNOT_FOUND if there
139 are no more.
140
141 This method is only valid for multi selection listboxes.
142
143 @see GetFirstSelected()
144 */
145 int GetNextSelected(unsigned long& cookie) const;
146
147 /**
148 Returns the number of the items currently selected.
149
150 It is valid for both single and multi selection controls. In the former
151 case it may only return 0 or 1 however.
152
153 @see IsSelected(), GetFirstSelected(), GetNextSelected()
154 */
155 size_t GetSelectedCount() const;
156
157 /**
158 Get the currently selected item or @c wxNOT_FOUND if there is no
159 selection.
160 */
161 int GetSelection() const;
162
163 /**
164 Returns the background colour used for the selected cells. By default
165 the standard system colour is used.
166
167 @see wxSystemSettings::GetColour(), SetSelectionBackground()
168 */
169 const wxColour& GetSelectionBackground() const;
170
171 /**
172 Returns @true if the listbox was created with @c wxLB_MULTIPLE style
173 and so supports multiple selection or @false if it is a single
174 selection listbox.
175 */
176 bool HasMultipleSelection() const;
177
178 /**
179 Returns @true if this item is the current one, @false otherwise.
180
181 The current item is always the same as selected one for the single
182 selection listbox and in this case this method is equivalent to
183 IsSelected() but they are different for multi selection listboxes where
184 many items may be selected but only one (at most) is current.
185 */
186 bool IsCurrent(size_t item) const;
187
188 /**
189 Returns @true if this item is selected, @false otherwise.
190 */
191 bool IsSelected(size_t item) const;
192
193 /**
194 This method is used to draw the items background and, maybe, a border
195 around it.
196
197 The base class version implements a reasonable default behaviour which
198 consists in drawing the selected item with the standard background
199 colour and drawing a border around the item if it is either selected or
200 current.
201
202 @todo Change this function signature to non-const.
203 */
204 virtual void OnDrawBackground(wxDC& dc, const wxRect& rect, size_t n) const;
205
206 /**
207 This method may be used to draw separators between the lines. The
208 rectangle passed to it may be modified, typically to deflate it a bit
209 before passing to OnDrawItem().
210
211 The base class version of this method doesn't do anything.
212
213 @param dc
214 The device context to use for drawing.
215 @param rect
216 The bounding rectangle for the item.
217 @param n
218 The index of the item.
219
220 @todo Change this function signature to non-const.
221 */
222 virtual void OnDrawSeparator(wxDC& dc, wxRect& rect, size_t n) const;
223
224 /**
225 Selects or deselects the specified item which must be valid (i.e. not
226 equal to @c wxNOT_FOUND).
227
228 @return @true if the items selection status has changed or @false
229 otherwise.
230
231 This function is only valid for the multiple selection listboxes, use
232 SetSelection() for the single selection ones.
233 */
234 bool Select(size_t item, bool select = true);
235
236 /**
237 Selects all the items in the listbox.
238
239 @return @true if any items were changed, i.e. if there had been any
240 unselected items before, or @false if all the items were
241 already selected.
242
243 This method is only valid for multi selection listboxes.
244
245 @see DeselectAll(), Select()
246 */
247 bool SelectAll();
248
249 /**
250 Selects all items in the specified range which may be given in any
251 order.
252
253 @return @true if the items selection status has changed or @false
254 otherwise.
255
256 This method is only valid for multi selection listboxes.
257
258 @see SelectAll(), Select()
259 */
260 bool SelectRange(size_t from, size_t to);
261
262 /**
263 Set the number of items to be shown in the control.
264
265 This is just a synonym for wxVScrolledWindow::SetRowCount().
266 */
267 virtual void SetItemCount(size_t count);
268
269 //@{
270 /**
271 Set the margins: horizontal margin is the distance between the window
272 border and the item contents while vertical margin is half of the
273 distance between items.
274
275 By default both margins are 0.
276 */
277 void SetMargins(const wxPoint& pt);
278 void SetMargins(wxCoord x, wxCoord y);
279 //@}
280
281 /**
282 Set the selection to the specified item, if it is -1 the selection is
283 unset. The selected item will be automatically scrolled into view if it
284 isn't currently visible.
285
286 This method may be used both with single and multiple selection
287 listboxes.
288 */
289 void SetSelection(int selection);
290
291 /**
292 Sets the colour to be used for the selected cells background. The
293 background of the standard cells may be changed by simply calling
294 wxWindow::SetBackgroundColour().
295
296 @note Using a non-default background colour may result in control
297 having an appearance different from the similar native controls
298 and should be avoided in general.
299
300 @see GetSelectionBackground()
301 */
302 void SetSelectionBackground(const wxColour& col);
303
304 /**
305 Toggles the state of the specified @a item, i.e. selects it if it was
306 unselected and deselects it if it was selected.
307
308 This method is only valid for multi selection listboxes.
309
310 @see Select()
311 */
312 void Toggle(size_t item);
313
314 protected:
315
316 /**
317 The derived class must implement this function to actually draw the
318 item with the given index on the provided DC.
319
320 @param dc
321 The device context to use for drawing.
322 @param rect
323 The bounding rectangle for the item being drawn (DC clipping
324 region is set to this rectangle before calling this function).
325 @param n
326 The index of the item to be drawn.
327
328 @todo Change this function signature to non-const.
329 */
330 virtual void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n) const = 0;
331
332 /**
333 The derived class must implement this method to return the height of
334 the specified item (in pixels).
335 */
336 virtual wxCoord OnMeasureItem(size_t n) const = 0;
337 };
338