1 ///////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxVListBox is a virtual listbox with lines of variable height
4 // Author: Vadim Zeitlin
8 // Copyright: (c) 2003 Vadim Zeitlin <vadim@wxwindows.org>
9 // Licence: wxWindows licence
10 ///////////////////////////////////////////////////////////////////////////////
15 #include "wx/vscroll.h" // base class
17 class WXDLLEXPORT wxSelectionStore
;
19 #define wxVListBoxNameStr _T("wxVListBox")
21 // ----------------------------------------------------------------------------
23 // ----------------------------------------------------------------------------
26 This class has two main differences from a regular listbox: it can have an
27 arbitrarily huge number of items because it doesn't store them itself but
28 uses OnDrawItem() callback to draw them and its items can have variable
29 height as determined by OnMeasureItem().
31 It emits the same events as wxListBox and the same event macros may be used
34 class WXDLLEXPORT wxVListBox
: public wxVScrolledWindow
37 // constructors and such
38 // ---------------------
40 // default constructor, you must call Create() later
41 wxVListBox() { Init(); }
43 // normal constructor which calls Create() internally
44 wxVListBox(wxWindow
*parent
,
45 wxWindowID id
= wxID_ANY
,
46 const wxPoint
& pos
= wxDefaultPosition
,
47 const wxSize
& size
= wxDefaultSize
,
49 const wxString
& name
= wxVListBoxNameStr
)
53 (void)Create(parent
, id
, pos
, size
, style
, name
);
56 // really creates the control and sets the initial number of items in it
57 // (which may be changed later with SetItemCount())
59 // the only special style which may be specified here is wxLB_MULTIPLE
61 // returns true on success or false if the control couldn't be created
62 bool Create(wxWindow
*parent
,
63 wxWindowID id
= wxID_ANY
,
64 const wxPoint
& pos
= wxDefaultPosition
,
65 const wxSize
& size
= wxDefaultSize
,
67 const wxString
& name
= wxVListBoxNameStr
);
69 // dtor does some internal cleanup (deletes m_selStore if any)
70 virtual ~wxVListBox();
76 // get the number of items in the control
77 size_t GetItemCount() const { return GetLineCount(); }
79 // does this control use multiple selection?
80 bool HasMultipleSelection() const { return m_selStore
!= NULL
; }
82 // get the currently selected item or wxNOT_FOUND if there is no selection
84 // this method is only valid for the single selection listboxes
85 int GetSelection() const
87 wxASSERT_MSG( !HasMultipleSelection(),
88 _T("GetSelection() can't be used with wxLB_MULTIPLE") );
93 // is this item the current one?
94 bool IsCurrent(size_t item
) const { return item
== (size_t)m_current
; }
95 #ifdef __WXUNIVERSAL__
96 bool IsCurrent() const { return wxVScrolledWindow::IsCurrent(); }
99 // is this item selected?
100 bool IsSelected(size_t item
) const;
102 // get the number of the selected items (maybe 0)
104 // this method is valid for both single and multi selection listboxes
105 size_t GetSelectedCount() const;
107 // get the first selected item, returns wxNOT_FOUND if none
109 // cookie is an opaque parameter which should be passed to
110 // GetNextSelected() later
112 // this method is only valid for the multi selection listboxes
113 int GetFirstSelected(unsigned long& cookie
) const;
115 // get next selection item, return wxNOT_FOUND if no more
117 // cookie must be the same parameter that was passed to GetFirstSelected()
120 // this method is only valid for the multi selection listboxes
121 int GetNextSelected(unsigned long& cookie
) const;
123 // get the margins around each item
124 wxPoint
GetMargins() const { return m_ptMargins
; }
126 // get the background colour of selected cells
127 const wxColour
& GetSelectionBackground() const { return m_colBgSel
; }
133 // set the number of items to be shown in the control
135 // this is just a synonym for wxVScrolledWindow::SetLineCount()
136 virtual void SetItemCount(size_t count
);
138 // delete all items from the control
139 void Clear() { SetItemCount(0); }
141 // set the selection to the specified item, if it is wxNOT_FOUND the
142 // selection is unset
144 // this function is only valid for the single selection listboxes
145 void SetSelection(int selection
);
147 // selects or deselects the specified item which must be valid (i.e. not
148 // equal to wxNOT_FOUND)
150 // return true if the items selection status has changed or false
153 // this function is only valid for the multiple selection listboxes
154 bool Select(size_t item
, bool select
= true);
156 // selects the items in the specified range whose end points may be given
159 // return true if any items selection status has changed, false otherwise
161 // this function is only valid for the single selection listboxes
162 bool SelectRange(size_t from
, size_t to
);
164 // toggle the selection of the specified item (must be valid)
166 // this function is only valid for the multiple selection listboxes
167 void Toggle(size_t item
) { Select(item
, !IsSelected(item
)); }
169 // select all items in the listbox
171 // the return code indicates if any items were affected by this operation
172 // (true) or if nothing has changed (false)
173 bool SelectAll() { return DoSelectAll(true); }
175 // unselect all items in the listbox
177 // the return code has the same meaning as for SelectAll()
178 bool DeselectAll() { return DoSelectAll(false); }
180 // set the margins: horizontal margin is the distance between the window
181 // border and the item contents while vertical margin is half of the
182 // distance between items
184 // by default both margins are 0
185 void SetMargins(const wxPoint
& pt
);
186 void SetMargins(wxCoord x
, wxCoord y
) { SetMargins(wxPoint(x
, y
)); }
188 // change the background colour of the selected cells
189 void SetSelectionBackground(const wxColour
& col
);
192 virtual bool CanApplyParentThemeBackground() const { return false; }
195 // the derived class must implement this function to actually draw the item
196 // with the given index on the provided DC
197 virtual void OnDrawItem(wxDC
& dc
, const wxRect
& rect
, size_t n
) const = 0;
199 // the derived class must implement this method to return the height of the
201 virtual wxCoord
OnMeasureItem(size_t n
) const = 0;
203 // this method may be used to draw separators between the lines; note that
204 // the rectangle may be modified, typically to deflate it a bit before
205 // passing to OnDrawItem()
207 // the base class version doesn't do anything
208 virtual void OnDrawSeparator(wxDC
& dc
, wxRect
& rect
, size_t n
) const;
210 // this method is used to draw the items background and, maybe, a border
213 // the base class version implements a reasonable default behaviour which
214 // consists in drawing the selected item with the standard background
215 // colour and drawing a border around the item if it is either selected or
217 virtual void OnDrawBackground(wxDC
& dc
, const wxRect
& rect
, size_t n
) const;
219 // we implement OnGetLineHeight() in terms of OnMeasureItem() because this
220 // allows us to add borders to the items easily
222 // this function is not supposed to be overridden by the derived classes
223 virtual wxCoord
OnGetLineHeight(size_t line
) const;
227 void OnPaint(wxPaintEvent
& event
);
228 void OnKeyDown(wxKeyEvent
& event
);
229 void OnLeftDown(wxMouseEvent
& event
);
230 void OnLeftDClick(wxMouseEvent
& event
);
233 // common part of all ctors
236 // send the wxEVT_COMMAND_LISTBOX_SELECTED event
237 void SendSelectedEvent();
239 // common implementation of SelectAll() and DeselectAll()
240 bool DoSelectAll(bool select
);
242 // change the current item (in single selection listbox it also implicitly
243 // changes the selection); current may be wxNOT_FOUND in which case there
244 // will be no current item any more
246 // return true if the current item changed, false otherwise
247 bool DoSetCurrent(int current
);
249 // flags for DoHandleItemClick
252 ItemClick_Shift
= 1, // item shift-clicked
253 ItemClick_Ctrl
= 2, // ctrl
254 ItemClick_Kbd
= 4 // item selected from keyboard
257 // common part of keyboard and mouse handling processing code
258 void DoHandleItemClick(int item
, int flags
);
261 // the current item or wxNOT_FOUND
263 // if m_selStore == NULL this is also the selected item, otherwise the
264 // selections are managed by m_selStore
267 // the anchor of the selection for the multiselection listboxes:
268 // shift-clicking an item extends the selection from m_anchor to the item
269 // clicked, for example
271 // always wxNOT_FOUND for single selection listboxes
274 // the object managing our selected items if not NULL
275 wxSelectionStore
*m_selStore
;
280 // the selection bg colour
284 DECLARE_EVENT_TABLE()
285 DECLARE_NO_COPY_CLASS(wxVListBox
)
286 DECLARE_ABSTRACT_CLASS(wxVListBox
)
289 #endif // _WX_VLBOX_H_