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