]>
Commit | Line | Data |
---|---|---|
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$ | |
8 | // Copyright: (c) 2003 Vadim Zeitlin <vadim@wxwidgets.org> | |
9 | // Licence: wxWindows licence | |
10 | /////////////////////////////////////////////////////////////////////////////// | |
11 | ||
12 | #ifndef _WX_VLBOX_H_ | |
13 | #define _WX_VLBOX_H_ | |
14 | ||
15 | #include "wx/vscroll.h" // base class | |
16 | #include "wx/bitmap.h" | |
17 | ||
18 | class WXDLLIMPEXP_FWD_CORE wxSelectionStore; | |
19 | ||
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 | */ | |
35 | class WXDLLIMPEXP_CORE wxVListBox : public wxVScrolledWindow | |
36 | { | |
37 | public: | |
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, | |
49 | long style = 0, | |
50 | const wxString& name = wxVListBoxNameStr) | |
51 | { | |
52 | Init(); | |
53 | ||
54 | (void)Create(parent, id, pos, size, style, name); | |
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 | // | |
60 | // the only special style which may be specified here is wxLB_MULTIPLE | |
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, | |
67 | long style = 0, | |
68 | const wxString& name = wxVListBoxNameStr); | |
69 | ||
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 | |
78 | size_t GetItemCount() const { return GetRowCount(); } | |
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; } | |
96 | #ifdef __WXUNIVERSAL__ | |
97 | bool IsCurrent() const { return wxVScrolledWindow::IsCurrent(); } | |
98 | #endif | |
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 | ||
127 | // get the background colour of selected cells | |
128 | const wxColour& GetSelectionBackground() const { return m_colBgSel; } | |
129 | ||
130 | // get the item rect, returns empty rect if the item is not visible | |
131 | wxRect GetItemRect(size_t n) const; | |
132 | ||
133 | // operations | |
134 | // ---------- | |
135 | ||
136 | // set the number of items to be shown in the control | |
137 | // | |
138 | // this is just a synonym for wxVScrolledWindow::SetRowCount() | |
139 | virtual void SetItemCount(size_t count); | |
140 | ||
141 | // delete all items from the control | |
142 | void Clear() { SetItemCount(0); } | |
143 | ||
144 | // set the selection to the specified item, if it is wxNOT_FOUND the | |
145 | // selection is unset | |
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 | |
151 | // equal to wxNOT_FOUND) | |
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); } | |
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 | ||
191 | // change the background colour of the selected cells | |
192 | void SetSelectionBackground(const wxColour& col); | |
193 | ||
194 | // refreshes only the selected items | |
195 | void RefreshSelected(); | |
196 | ||
197 | ||
198 | virtual wxVisualAttributes GetDefaultAttributes() const | |
199 | { | |
200 | return GetClassDefaultAttributes(GetWindowVariant()); | |
201 | } | |
202 | ||
203 | static wxVisualAttributes | |
204 | GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); | |
205 | ||
206 | protected: | |
207 | virtual wxBorder GetDefaultBorder() const { return wxBORDER_THEME; } | |
208 | ||
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 | ||
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; | |
232 | ||
233 | // we implement OnGetRowHeight() in terms of OnMeasureItem() because this | |
234 | // allows us to add borders to the items easily | |
235 | // | |
236 | // this function is not supposed to be overridden by the derived classes | |
237 | virtual wxCoord OnGetRowHeight(size_t line) const; | |
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); | |
245 | void OnSetOrKillFocus(wxFocusEvent& event); | |
246 | void OnSize(wxSizeEvent& event); | |
247 | ||
248 | // common part of all ctors | |
249 | void Init(); | |
250 | ||
251 | // send the wxEVT_COMMAND_LISTBOX_SELECTED event | |
252 | void SendSelectedEvent(); | |
253 | ||
254 | // common implementation of SelectAll() and DeselectAll() | |
255 | bool DoSelectAll(bool select); | |
256 | ||
257 | // change the current item (in single selection listbox it also implicitly | |
258 | // changes the selection); current may be wxNOT_FOUND in which case there | |
259 | // will be no current item any more | |
260 | // | |
261 | // return true if the current item changed, false otherwise | |
262 | bool DoSetCurrent(int current); | |
263 | ||
264 | // flags for DoHandleItemClick | |
265 | enum | |
266 | { | |
267 | ItemClick_Shift = 1, // item shift-clicked | |
268 | ItemClick_Ctrl = 2, // ctrl | |
269 | ItemClick_Kbd = 4 // item selected from keyboard | |
270 | }; | |
271 | ||
272 | // common part of keyboard and mouse handling processing code | |
273 | void DoHandleItemClick(int item, int flags); | |
274 | ||
275 | // paint the background of the given item using the provided colour if it's | |
276 | // valid, otherwise just return false and do nothing (this is used by | |
277 | // OnDrawBackground()) | |
278 | bool DoDrawSolidBackground(const wxColour& col, | |
279 | wxDC& dc, | |
280 | const wxRect& rect, | |
281 | size_t n) const; | |
282 | ||
283 | private: | |
284 | // the current item or wxNOT_FOUND | |
285 | // | |
286 | // if m_selStore == NULL this is also the selected item, otherwise the | |
287 | // selections are managed by m_selStore | |
288 | int m_current; | |
289 | ||
290 | // the anchor of the selection for the multiselection listboxes: | |
291 | // shift-clicking an item extends the selection from m_anchor to the item | |
292 | // clicked, for example | |
293 | // | |
294 | // always wxNOT_FOUND for single selection listboxes | |
295 | int m_anchor; | |
296 | ||
297 | // the object managing our selected items if not NULL | |
298 | wxSelectionStore *m_selStore; | |
299 | ||
300 | // margins | |
301 | wxPoint m_ptMargins; | |
302 | ||
303 | // the selection bg colour | |
304 | wxColour m_colBgSel; | |
305 | ||
306 | DECLARE_EVENT_TABLE() | |
307 | DECLARE_NO_COPY_CLASS(wxVListBox) | |
308 | DECLARE_ABSTRACT_CLASS(wxVListBox) | |
309 | }; | |
310 | ||
311 | #endif // _WX_VLBOX_H_ | |
312 |