]> git.saurik.com Git - wxWidgets.git/blame - include/wx/vlbox.h
Minor corrections to make dist after reports
[wxWidgets.git] / include / wx / vlbox.h
CommitLineData
e0c6027b
VZ
1///////////////////////////////////////////////////////////////////////////////
2// Name: wx/vlbox.h
3// Purpose: wxVListBox is a virtual listbox with lines of variable height
4// Author: Vadim Zeitlin
5// Modified by:
6// Created: 31.05.03
7// RCS-ID: $Id$
77ffb593 8// Copyright: (c) 2003 Vadim Zeitlin <vadim@wxwidgets.org>
65571936 9// Licence: wxWindows licence
e0c6027b
VZ
10///////////////////////////////////////////////////////////////////////////////
11
12#ifndef _WX_VLBOX_H_
13#define _WX_VLBOX_H_
14
15#include "wx/vscroll.h" // base class
4c81b431 16#include "wx/bitmap.h"
e0c6027b 17
b5dbe15d 18class WXDLLIMPEXP_FWD_CORE wxSelectionStore;
be465555 19
e0c6027b
VZ
20#define wxVListBoxNameStr _T("wxVListBox")
21
22// ----------------------------------------------------------------------------
23// wxVListBox
24// ----------------------------------------------------------------------------
25
26/*
27 This class has two main differences from a regular listbox: it can have an
28 arbitrarily huge number of items because it doesn't store them itself but
29 uses OnDrawItem() callback to draw them and its items can have variable
30 height as determined by OnMeasureItem().
31
32 It emits the same events as wxListBox and the same event macros may be used
33 with it.
34 */
53a2db12 35class WXDLLIMPEXP_CORE wxVListBox : public wxVScrolledWindow
e0c6027b
VZ
36{
37public:
38 // constructors and such
39 // ---------------------
40
41 // default constructor, you must call Create() later
42 wxVListBox() { Init(); }
43
44 // normal constructor which calls Create() internally
45 wxVListBox(wxWindow *parent,
46 wxWindowID id = wxID_ANY,
47 const wxPoint& pos = wxDefaultPosition,
48 const wxSize& size = wxDefaultSize,
e0c6027b
VZ
49 long style = 0,
50 const wxString& name = wxVListBoxNameStr)
51 {
52 Init();
53
be465555 54 (void)Create(parent, id, pos, size, style, name);
e0c6027b
VZ
55 }
56
57 // really creates the control and sets the initial number of items in it
58 // (which may be changed later with SetItemCount())
59 //
be465555 60 // the only special style which may be specified here is wxLB_MULTIPLE
e0c6027b
VZ
61 //
62 // returns true on success or false if the control couldn't be created
63 bool Create(wxWindow *parent,
64 wxWindowID id = wxID_ANY,
65 const wxPoint& pos = wxDefaultPosition,
66 const wxSize& size = wxDefaultSize,
e0c6027b
VZ
67 long style = 0,
68 const wxString& name = wxVListBoxNameStr);
69
be465555
VZ
70 // dtor does some internal cleanup (deletes m_selStore if any)
71 virtual ~wxVListBox();
72
73
74 // accessors
75 // ---------
76
77 // get the number of items in the control
f18eaf26 78 size_t GetItemCount() const { return GetRowCount(); }
be465555
VZ
79
80 // does this control use multiple selection?
81 bool HasMultipleSelection() const { return m_selStore != NULL; }
82
83 // get the currently selected item or wxNOT_FOUND if there is no selection
84 //
85 // this method is only valid for the single selection listboxes
86 int GetSelection() const
87 {
88 wxASSERT_MSG( !HasMultipleSelection(),
89 _T("GetSelection() can't be used with wxLB_MULTIPLE") );
90
91 return m_current;
92 }
93
94 // is this item the current one?
95 bool IsCurrent(size_t item) const { return item == (size_t)m_current; }
8a39593e
JS
96 #ifdef __WXUNIVERSAL__
97 bool IsCurrent() const { return wxVScrolledWindow::IsCurrent(); }
98 #endif
be465555
VZ
99
100 // is this item selected?
101 bool IsSelected(size_t item) const;
102
103 // get the number of the selected items (maybe 0)
104 //
105 // this method is valid for both single and multi selection listboxes
106 size_t GetSelectedCount() const;
107
108 // get the first selected item, returns wxNOT_FOUND if none
109 //
110 // cookie is an opaque parameter which should be passed to
111 // GetNextSelected() later
112 //
113 // this method is only valid for the multi selection listboxes
114 int GetFirstSelected(unsigned long& cookie) const;
115
116 // get next selection item, return wxNOT_FOUND if no more
117 //
118 // cookie must be the same parameter that was passed to GetFirstSelected()
119 // before
120 //
121 // this method is only valid for the multi selection listboxes
122 int GetNextSelected(unsigned long& cookie) const;
123
124 // get the margins around each item
125 wxPoint GetMargins() const { return m_ptMargins; }
126
9a9b4940
VZ
127 // get the background colour of selected cells
128 const wxColour& GetSelectionBackground() const { return m_colBgSel; }
129
293b15f7
VZ
130 // get the item rect, returns empty rect if the item is not visible
131 wxRect GetItemRect(size_t n) const;
e0c6027b
VZ
132
133 // operations
134 // ----------
135
136 // set the number of items to be shown in the control
137 //
f18eaf26 138 // this is just a synonym for wxVScrolledWindow::SetRowCount()
03495767 139 virtual void SetItemCount(size_t count);
e0c6027b
VZ
140
141 // delete all items from the control
142 void Clear() { SetItemCount(0); }
143
970b97a2
VZ
144 // set the selection to the specified item, if it is wxNOT_FOUND the
145 // selection is unset
be465555
VZ
146 //
147 // this function is only valid for the single selection listboxes
148 void SetSelection(int selection);
149
150 // selects or deselects the specified item which must be valid (i.e. not
970b97a2 151 // equal to wxNOT_FOUND)
be465555
VZ
152 //
153 // return true if the items selection status has changed or false
154 // otherwise
155 //
156 // this function is only valid for the multiple selection listboxes
157 bool Select(size_t item, bool select = true);
158
159 // selects the items in the specified range whose end points may be given
160 // in any order
161 //
162 // return true if any items selection status has changed, false otherwise
163 //
164 // this function is only valid for the single selection listboxes
165 bool SelectRange(size_t from, size_t to);
166
167 // toggle the selection of the specified item (must be valid)
168 //
169 // this function is only valid for the multiple selection listboxes
170 void Toggle(size_t item) { Select(item, !IsSelected(item)); }
171
172 // select all items in the listbox
173 //
174 // the return code indicates if any items were affected by this operation
175 // (true) or if nothing has changed (false)
176 bool SelectAll() { return DoSelectAll(true); }
177
178 // unselect all items in the listbox
179 //
180 // the return code has the same meaning as for SelectAll()
181 bool DeselectAll() { return DoSelectAll(false); }
e0c6027b
VZ
182
183 // set the margins: horizontal margin is the distance between the window
184 // border and the item contents while vertical margin is half of the
185 // distance between items
186 //
187 // by default both margins are 0
188 void SetMargins(const wxPoint& pt);
189 void SetMargins(wxCoord x, wxCoord y) { SetMargins(wxPoint(x, y)); }
190
9a9b4940
VZ
191 // change the background colour of the selected cells
192 void SetSelectionBackground(const wxColour& col);
193
04125489
VZ
194 // refreshes only the selected items
195 void RefreshSelected();
196
e0c6027b 197
dc596072
RD
198 virtual wxVisualAttributes GetDefaultAttributes() const
199 {
200 return GetClassDefaultAttributes(GetWindowVariant());
201 }
202
203 static wxVisualAttributes
204 GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
cab1a605 205
3c75d8ba 206protected:
28319afe 207 virtual wxBorder GetDefaultBorder() const { return wxBORDER_THEME; }
a047aff2 208
e0c6027b
VZ
209 // the derived class must implement this function to actually draw the item
210 // with the given index on the provided DC
211 virtual void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n) const = 0;
212
213 // the derived class must implement this method to return the height of the
214 // specified item
215 virtual wxCoord OnMeasureItem(size_t n) const = 0;
216
217 // this method may be used to draw separators between the lines; note that
218 // the rectangle may be modified, typically to deflate it a bit before
219 // passing to OnDrawItem()
220 //
221 // the base class version doesn't do anything
222 virtual void OnDrawSeparator(wxDC& dc, wxRect& rect, size_t n) const;
223
27d0dcd0
VZ
224 // this method is used to draw the items background and, maybe, a border
225 // around it
226 //
227 // the base class version implements a reasonable default behaviour which
228 // consists in drawing the selected item with the standard background
229 // colour and drawing a border around the item if it is either selected or
230 // current
231 virtual void OnDrawBackground(wxDC& dc, const wxRect& rect, size_t n) const;
e0c6027b 232
e02c72fa 233 // we implement OnGetRowHeight() in terms of OnMeasureItem() because this
e0c6027b
VZ
234 // allows us to add borders to the items easily
235 //
0c8392ca 236 // this function is not supposed to be overridden by the derived classes
e02c72fa 237 virtual wxCoord OnGetRowHeight(size_t line) const;
e0c6027b
VZ
238
239
240 // event handlers
241 void OnPaint(wxPaintEvent& event);
242 void OnKeyDown(wxKeyEvent& event);
243 void OnLeftDown(wxMouseEvent& event);
244 void OnLeftDClick(wxMouseEvent& event);
04125489 245 void OnSetOrKillFocus(wxFocusEvent& event);
e0c6027b
VZ
246
247 // common part of all ctors
248 void Init();
249
be465555
VZ
250 // send the wxEVT_COMMAND_LISTBOX_SELECTED event
251 void SendSelectedEvent();
252
253 // common implementation of SelectAll() and DeselectAll()
254 bool DoSelectAll(bool select);
255
256 // change the current item (in single selection listbox it also implicitly
970b97a2
VZ
257 // changes the selection); current may be wxNOT_FOUND in which case there
258 // will be no current item any more
be465555
VZ
259 //
260 // return true if the current item changed, false otherwise
261 bool DoSetCurrent(int current);
262
970b97a2
VZ
263 // flags for DoHandleItemClick
264 enum
265 {
266 ItemClick_Shift = 1, // item shift-clicked
267 ItemClick_Ctrl = 2, // ctrl
268 ItemClick_Kbd = 4 // item selected from keyboard
269 };
270
be465555 271 // common part of keyboard and mouse handling processing code
970b97a2 272 void DoHandleItemClick(int item, int flags);
e0c6027b 273
c848185a
VZ
274 // paint the background of the given item using the provided colour if it's
275 // valid, otherwise just return false and do nothing (this is used by
276 // OnDrawBackground())
277 bool DoDrawSolidBackground(const wxColour& col,
278 wxDC& dc,
279 const wxRect& rect,
280 size_t n) const;
281
e0c6027b 282private:
970b97a2 283 // the current item or wxNOT_FOUND
be465555
VZ
284 //
285 // if m_selStore == NULL this is also the selected item, otherwise the
286 // selections are managed by m_selStore
287 int m_current;
288
970b97a2
VZ
289 // the anchor of the selection for the multiselection listboxes:
290 // shift-clicking an item extends the selection from m_anchor to the item
291 // clicked, for example
292 //
293 // always wxNOT_FOUND for single selection listboxes
294 int m_anchor;
295
be465555
VZ
296 // the object managing our selected items if not NULL
297 wxSelectionStore *m_selStore;
e0c6027b
VZ
298
299 // margins
300 wxPoint m_ptMargins;
301
9a9b4940
VZ
302 // the selection bg colour
303 wxColour m_colBgSel;
304
e0c6027b 305 DECLARE_EVENT_TABLE()
27d0dcd0 306 DECLARE_NO_COPY_CLASS(wxVListBox)
0c8392ca 307 DECLARE_ABSTRACT_CLASS(wxVListBox)
e0c6027b
VZ
308};
309
310#endif // _WX_VLBOX_H_
311