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