]>
git.saurik.com Git - wxWidgets.git/blob - interface/vlbox.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxVListBox
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
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).
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).
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
34 <!-- @appearance{vlistbox.png} -->
36 @see wxSimpleHtmlListBox, wxHtmlListBox
38 class wxVListBox
: public wxVScrolledWindow
42 Default constructor, you must call Create() later.
46 Normal constructor which calls Create() internally.
48 wxVListBox(wxWindow
* parent
, wxWindowID id
= wxID_ANY
,
49 const wxPoint
& pos
= wxDefaultPosition
,
50 const wxSize
& size
= wxDefaultSize
,
51 size_t countItems
= 0, long style
= 0,
52 const wxString
& name
= wxVListBoxNameStr
);
57 virtual ~wxVListBox();
60 Deletes all items from the control.
65 Creates the control. To finish creating it you also should call
66 SetItemCount() to let it know about the number of items it contains.
68 The only special style which may be used with wxVListBox is
69 @c wxLB_MULTIPLE which indicates that the listbox should support
72 @returns @true on success or @false if the control couldn't be created.
74 bool Create(wxWindow
* parent
, wxWindowID id
= wxID_ANY
,
75 const wxPoint
& pos
= wxDefaultPosition
,
76 const wxSize
& size
= wxDefaultSize
, long style
= 0,
77 const wxString
& name
= wxVListBoxNameStr
);
80 Deselects all the items in the listbox. This method is only valid for
81 multi selection listboxes.
83 @returns @true if any items were changed, i.e. if there had been any
84 selected items before, or @false if all the items were already
87 @see SelectAll(), Select()
92 Returns the index of the first selected item in the listbox or
93 @c wxNOT_FOUND if no items are currently selected.
95 @a cookie is an opaque parameter which should be passed to the
96 subsequent calls to GetNextSelected(). It is needed in order to allow
97 parallel iterations over the selected items.
99 Here is a typical example of using these functions:
102 unsigned long cookie;
103 int item = hlbox->GetFirstSelected(cookie);
104 while ( item != wxNOT_FOUND )
106 // ... process item ...
107 item = hlbox->GetNextSelected(cookie);
111 This method is only valid for multi selection listboxes.
113 int GetFirstSelected(unsigned long& cookie
) const;
116 Get the number of items in the control.
120 size_t GetItemCount() const;
123 Returns the margins used by the control. The @c x field of the returned
124 point is the horizontal margin and the @c y field is the vertical one.
128 wxPoint
GetMargins() const;
131 Returns the index of the next selected item or @c wxNOT_FOUND if there
134 This method is only valid for multi selection listboxes.
136 @see GetFirstSelected()
138 int GetNextSelected(unsigned long& cookie
) const;
141 Returns the number of the items currently selected.
143 It is valid for both single and multi selection controls. In the former
144 case it may only return 0 or 1 however.
146 @see IsSelected(), GetFirstSelected(), GetNextSelected()
148 size_t GetSelectedCount() const;
151 Get the currently selected item or @c wxNOT_FOUND if there is no
154 int GetSelection() const;
157 Returns the background colour used for the selected cells. By default
158 the standard system colour is used.
160 @see wxSystemSettings::GetColour(), SetSelectionBackground()
162 const wxColour
& GetSelectionBackground() const;
165 Returns @true if the listbox was created with @c wxLB_MULTIPLE style
166 and so supports multiple selection or @false if it is a single
169 bool HasMultipleSelection() const;
172 Returns @true if this item is the current one, @false otherwise.
174 The current item is always the same as selected one for the single
175 selection listbox and in this case this method is equivalent to
176 IsSelected() but they are different for multi selection listboxes where
177 many items may be selected but only one (at most) is current.
179 bool IsCurrent(size_t item
) const;
182 Returns @true if this item is selected, @false otherwise.
184 bool IsSelected(size_t item
) const;
187 This method is used to draw the items background and, maybe, a border
190 The base class version implements a reasonable default behaviour which
191 consists in drawing the selected item with the standard background
192 colour and drawing a border around the item if it is either selected or
195 void OnDrawBackground(wxDC
& dc
, const wxRect
& rect
, size_t n
) const;
198 The derived class must implement this function to actually draw the
199 item with the given index on the provided DC.
202 The device context to use for drawing.
204 The bounding rectangle for the item being drawn (DC clipping
205 region is set to this rectangle before calling this function).
207 The index of the item to be drawn.
209 virtual void OnDrawItem(wxDC
& dc
, const wxRect
& rect
, size_t n
) const;
212 This method may be used to draw separators between the lines. The
213 rectangle passed to it may be modified, typically to deflate it a bit
214 before passing to OnDrawItem().
216 The base class version of this method doesn't do anything.
219 The device context to use for drawing.
221 The bounding rectangle for the item.
223 The index of the item.
225 virtual void OnDrawSeparator(wxDC
& dc
, wxRect
& rect
, size_t n
) const;
228 The derived class must implement this method to return the height of
229 the specified item (in pixels).
231 virtual wxCoord
OnMeasureItem(size_t n
) const;
234 Selects or deselects the specified item which must be valid (i.e. not
235 equal to @c wxNOT_FOUND).
237 @returns @true if the items selection status has changed or @false
240 This function is only valid for the multiple selection listboxes, use
241 SetSelection() for the single selection ones.
243 bool Select(size_t item
, bool select
= true);
246 Selects all the items in the listbox.
248 @returns @true if any items were changed, i.e. if there had been any
249 unselected items before, or @false if all the items were
252 This method is only valid for multi selection listboxes.
254 @see DeselectAll(), Select()
259 Selects all items in the specified range which may be given in any
262 @returns @true if the items selection status has changed or @false
265 This method is only valid for multi selection listboxes.
267 @see SelectAll(), Select()
269 bool SelectRange(size_t from
, size_t to
);
272 Set the number of items to be shown in the control.
274 This is just a synonym for wxVScrolledWindow::SetRowCount().
276 void SetItemCount(size_t count
);
280 Set the margins: horizontal margin is the distance between the window
281 border and the item contents while vertical margin is half of the
282 distance between items.
284 By default both margins are 0.
286 void SetMargins(const wxPoint
& pt
);
287 void SetMargins(wxCoord x
, wxCoord y
);
291 Set the selection to the specified item, if it is -1 the selection is
292 unset. The selected item will be automatically scrolled into view if it
293 isn't currently visible.
295 This method may be used both with single and multiple selection
298 void SetSelection(int selection
);
301 Sets the colour to be used for the selected cells background. The
302 background of the standard cells may be changed by simply calling
303 wxWindow::SetBackgroundColour().
305 @note Using a non-default background colour may result in control
306 having an appearance different from the similar native controls
307 and should be avoided in general.
309 @see GetSelectionBackground()
311 void SetSelectionBackground(const wxColour
& col
);
314 Toggles the state of the specified @a item, i.e. selects it if it was
315 unselected and deselects it if it was selected.
317 This method is only valid for multi selection listboxes.
321 void Toggle(size_t item
);