]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/vlbox.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxVListBox
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
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).
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).
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
33 <!-- @appearance{vlistbox.png} -->
35 @see wxSimpleHtmlListBox, wxHtmlListBox
37 class wxVListBox
: public wxVScrolledWindow
41 Default constructor, you must call Create() later.
45 Normal constructor which calls Create() internally.
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
);
55 virtual ~wxVListBox();
58 Deletes all items from the control.
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.
66 The only special style which may be used with wxVListBox is
67 @c wxLB_MULTIPLE which indicates that the listbox should support
70 @return @true on success or @false if the control couldn't be created.
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
);
78 Deselects all the items in the listbox. This method is only valid for
79 multi selection listboxes.
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
85 @see SelectAll(), Select()
90 Returns the index of the first selected item in the listbox or
91 @c wxNOT_FOUND if no items are currently selected.
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.
97 Here is a typical example of using these functions:
100 unsigned long cookie;
101 int item = hlbox->GetFirstSelected(cookie);
102 while ( item != wxNOT_FOUND )
104 // ... process item ...
105 item = hlbox->GetNextSelected(cookie);
109 This method is only valid for multi selection listboxes.
111 int GetFirstSelected(unsigned long& cookie
) const;
114 Get the number of items in the control.
118 size_t GetItemCount() const;
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.
126 wxPoint
GetMargins() const;
129 Returns the index of the next selected item or @c wxNOT_FOUND if there
132 This method is only valid for multi selection listboxes.
134 @see GetFirstSelected()
136 int GetNextSelected(unsigned long& cookie
) const;
139 Returns the number of the items currently selected.
141 It is valid for both single and multi selection controls. In the former
142 case it may only return 0 or 1 however.
144 @see IsSelected(), GetFirstSelected(), GetNextSelected()
146 size_t GetSelectedCount() const;
149 Get the currently selected item or @c wxNOT_FOUND if there is no
152 int GetSelection() const;
155 Returns the background colour used for the selected cells. By default
156 the standard system colour is used.
158 @see wxSystemSettings::GetColour(), SetSelectionBackground()
160 const wxColour
& GetSelectionBackground() const;
163 Returns @true if the listbox was created with @c wxLB_MULTIPLE style
164 and so supports multiple selection or @false if it is a single
167 bool HasMultipleSelection() const;
170 Returns @true if this item is the current one, @false otherwise.
172 The current item is always the same as selected one for the single
173 selection listbox and in this case this method is equivalent to
174 IsSelected() but they are different for multi selection listboxes where
175 many items may be selected but only one (at most) is current.
177 bool IsCurrent(size_t item
) const;
180 Returns @true if this item is selected, @false otherwise.
182 bool IsSelected(size_t item
) const;
185 This method is used to draw the items background and, maybe, a border
188 The base class version implements a reasonable default behaviour which
189 consists in drawing the selected item with the standard background
190 colour and drawing a border around the item if it is either selected or
193 @todo Change this function signature to non-const.
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 @todo Change this function signature to non-const.
211 virtual void OnDrawItem(wxDC
& dc
, const wxRect
& rect
, size_t n
) const;
214 This method may be used to draw separators between the lines. The
215 rectangle passed to it may be modified, typically to deflate it a bit
216 before passing to OnDrawItem().
218 The base class version of this method doesn't do anything.
221 The device context to use for drawing.
223 The bounding rectangle for the item.
225 The index of the item.
227 @todo Change this function signature to non-const.
229 virtual void OnDrawSeparator(wxDC
& dc
, wxRect
& rect
, size_t n
) const;
232 The derived class must implement this method to return the height of
233 the specified item (in pixels).
235 virtual wxCoord
OnMeasureItem(size_t n
) const;
238 Selects or deselects the specified item which must be valid (i.e. not
239 equal to @c wxNOT_FOUND).
241 @return @true if the items selection status has changed or @false
244 This function is only valid for the multiple selection listboxes, use
245 SetSelection() for the single selection ones.
247 bool Select(size_t item
, bool select
= true);
250 Selects all the items in the listbox.
252 @return @true if any items were changed, i.e. if there had been any
253 unselected items before, or @false if all the items were
256 This method is only valid for multi selection listboxes.
258 @see DeselectAll(), Select()
263 Selects all items in the specified range which may be given in any
266 @return @true if the items selection status has changed or @false
269 This method is only valid for multi selection listboxes.
271 @see SelectAll(), Select()
273 bool SelectRange(size_t from
, size_t to
);
276 Set the number of items to be shown in the control.
278 This is just a synonym for wxVScrolledWindow::SetRowCount().
280 void SetItemCount(size_t count
);
284 Set the margins: horizontal margin is the distance between the window
285 border and the item contents while vertical margin is half of the
286 distance between items.
288 By default both margins are 0.
290 void SetMargins(const wxPoint
& pt
);
291 void SetMargins(wxCoord x
, wxCoord y
);
295 Set the selection to the specified item, if it is -1 the selection is
296 unset. The selected item will be automatically scrolled into view if it
297 isn't currently visible.
299 This method may be used both with single and multiple selection
302 void SetSelection(int selection
);
305 Sets the colour to be used for the selected cells background. The
306 background of the standard cells may be changed by simply calling
307 wxWindow::SetBackgroundColour().
309 @note Using a non-default background colour may result in control
310 having an appearance different from the similar native controls
311 and should be avoided in general.
313 @see GetSelectionBackground()
315 void SetSelectionBackground(const wxColour
& col
);
318 Toggles the state of the specified @a item, i.e. selects it if it was
319 unselected and deselects it if it was selected.
321 This method is only valid for multi selection listboxes.
325 void Toggle(size_t item
);