]>
Commit | Line | Data |
---|---|---|
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 |