]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: listctrl.h | |
3 | // Purpose: wxListCtrl class | |
4 | // Author: Julian Smart | |
5 | // Modified by: | |
6 | // Created: 01/02/97 | |
7 | // RCS-ID: $Id$ | |
8 | // Copyright: (c) Julian Smart | |
9 | // Licence: wxWindows licence | |
10 | ///////////////////////////////////////////////////////////////////////////// | |
11 | ||
12 | #ifndef _WX_LISTCTRL_H_ | |
13 | #define _WX_LISTCTRL_H_ | |
14 | ||
15 | #ifdef __GNUG__ | |
16 | #pragma interface "listctrl.h" | |
17 | #endif | |
18 | ||
19 | #include "wx/control.h" | |
20 | #include "wx/event.h" | |
21 | #include "wx/imaglist.h" | |
22 | ||
23 | /* | |
24 | The wxListCtrl can show lists of items in four different modes: | |
25 | wxLC_LIST: multicolumn list view, with optional small icons (icons could be | |
26 | optional for some platforms). Columns are computed automatically, | |
27 | i.e. you don't set columns as in wxLC_REPORT. In other words, | |
28 | the list wraps, unlike a wxListBox. | |
29 | wxLC_REPORT: single or multicolumn report view (with optional header) | |
30 | wxLC_ICON: large icon view, with optional labels | |
31 | wxLC_SMALL_ICON: small icon view, with optional labels | |
32 | ||
33 | You can change the style dynamically, either with SetSingleStyle or | |
34 | SetWindowStyleFlag. | |
35 | ||
36 | Further window styles: | |
37 | ||
38 | wxLC_ALIGN_TOP icons align to the top (default) | |
39 | wxLC_ALIGN_LEFT icons align to the left | |
40 | wxLC_AUTOARRANGE icons arrange themselves | |
41 | wxLC_USER_TEXT the app provides label text on demand, except for column headers | |
42 | wxLC_EDIT_LABELS labels are editable: app will be notified. | |
43 | wxLC_NO_HEADER no header in report mode | |
44 | wxLC_NO_SORT_HEADER can't click on header | |
45 | wxLC_SINGLE_SEL single selection | |
46 | wxLC_SORT_ASCENDING sort ascending (must still supply a comparison callback in SortItems) | |
47 | wxLC_SORT_DESCENDING sort descending (ditto) | |
48 | ||
49 | Items are referred to by their index (position in the list starting from zero). | |
50 | ||
51 | Label text is supplied via insertion/setting functions and is stored by the | |
52 | control, unless the wxLC_USER_TEXT style has been specified, in which case | |
53 | the app will be notified when text is required (see sample). | |
54 | ||
55 | Images are dealt with by (optionally) associating 3 image lists with the control. | |
56 | Zero-based indexes into these image lists indicate which image is to be used for | |
57 | which item. Each image in an image list can contain a mask, and can be made out | |
58 | of either a bitmap, two bitmaps or an icon. See ImagList.h for more details. | |
59 | ||
60 | Notifications are passed via the wxWindows 2.0 event system, or using virtual | |
61 | functions in wxWindows 1.66. | |
62 | ||
63 | See the sample wxListCtrl app for API usage. | |
64 | ||
65 | TODO: | |
66 | - addition of further convenience functions | |
67 | to avoid use of wxListItem in some functions | |
68 | - state/overlay images: probably not needed. | |
69 | - in Win95, you can be called back to supply other information | |
70 | besides text, such as state information. This saves no memory | |
71 | and is probably superfluous to requirements. | |
72 | - testing of whole API, extending current sample. | |
73 | ||
74 | ||
75 | */ | |
76 | ||
77 | // Mask flags to tell app/GUI what fields of wxListItem are valid | |
78 | #define wxLIST_MASK_STATE 0x0001 | |
79 | #define wxLIST_MASK_TEXT 0x0002 | |
80 | #define wxLIST_MASK_IMAGE 0x0004 | |
81 | #define wxLIST_MASK_DATA 0x0008 | |
82 | #define wxLIST_SET_ITEM 0x0010 | |
83 | #define wxLIST_MASK_WIDTH 0x0020 | |
84 | #define wxLIST_MASK_FORMAT 0x0040 | |
85 | ||
86 | // State flags for indicating the state of an item | |
87 | #define wxLIST_STATE_DONTCARE 0x0000 | |
88 | #define wxLIST_STATE_DROPHILITED 0x0001 | |
89 | #define wxLIST_STATE_FOCUSED 0x0002 | |
90 | #define wxLIST_STATE_SELECTED 0x0004 | |
91 | #define wxLIST_STATE_CUT 0x0008 | |
92 | ||
93 | // Hit test flags, used in HitTest | |
94 | #define wxLIST_HITTEST_ABOVE 0x0001 // Above the client area. | |
95 | #define wxLIST_HITTEST_BELOW 0x0002 // Below the client area. | |
96 | #define wxLIST_HITTEST_NOWHERE 0x0004 // In the client area but below the last item. | |
97 | #define wxLIST_HITTEST_ONITEMICON 0x0020 // On the bitmap associated with an item. | |
98 | #define wxLIST_HITTEST_ONITEMLABEL 0x0080 // On the label (string) associated with an item. | |
99 | #define wxLIST_HITTEST_ONITEMRIGHT 0x0100 // In the area to the right of an item. | |
100 | #define wxLIST_HITTEST_ONITEMSTATEICON 0x0200 // On the state icon for a tree view item that is in a user-defined state. | |
101 | #define wxLIST_HITTEST_TOLEFT 0x0400 // To the left of the client area. | |
102 | #define wxLIST_HITTEST_TORIGHT 0x0800 // To the right of the client area. | |
103 | ||
104 | #define wxLIST_HITTEST_ONITEM (wxLIST_HITTEST_ONITEMICON | wxLIST_HITTEST_ONITEMLABEL | wxLIST_HITTEST_ONITEMSTATEICON) | |
105 | ||
106 | // Flags for GetNextItem | |
107 | enum { | |
108 | wxLIST_NEXT_ABOVE, // Searches for an item above the specified item | |
109 | wxLIST_NEXT_ALL, // Searches for subsequent item by index | |
110 | wxLIST_NEXT_BELOW, // Searches for an item below the specified item | |
111 | wxLIST_NEXT_LEFT, // Searches for an item to the left of the specified item | |
112 | wxLIST_NEXT_RIGHT, // Searches for an item to the right of the specified item | |
113 | }; | |
114 | ||
115 | // Alignment flags for Arrange | |
116 | enum { | |
117 | wxLIST_ALIGN_DEFAULT, | |
118 | wxLIST_ALIGN_LEFT, | |
119 | wxLIST_ALIGN_TOP, | |
120 | wxLIST_ALIGN_SNAP_TO_GRID | |
121 | }; | |
122 | ||
123 | // Column format | |
124 | enum { | |
125 | wxLIST_FORMAT_LEFT, | |
126 | wxLIST_FORMAT_RIGHT, | |
127 | wxLIST_FORMAT_CENTRE, | |
128 | wxLIST_FORMAT_CENTER = wxLIST_FORMAT_CENTRE | |
129 | }; | |
130 | ||
131 | // Autosize values for SetColumnWidth | |
132 | enum { | |
133 | wxLIST_AUTOSIZE = -1, | |
134 | wxLIST_AUTOSIZE_USEHEADER = -2 | |
135 | }; | |
136 | ||
137 | // Flag values for GetItemRect | |
138 | enum { | |
139 | wxLIST_RECT_BOUNDS, | |
140 | wxLIST_RECT_ICON, | |
141 | wxLIST_RECT_LABEL | |
142 | }; | |
143 | ||
144 | // Flag values for FindItem | |
145 | enum { | |
146 | wxLIST_FIND_UP, | |
147 | wxLIST_FIND_DOWN, | |
148 | wxLIST_FIND_LEFT, | |
149 | wxLIST_FIND_RIGHT | |
150 | }; | |
151 | ||
152 | // wxListItem: data representing an item, or report field. | |
153 | // It also doubles up to represent entire column information | |
154 | // when inserting or setting a column. | |
155 | class WXDLLEXPORT wxListItem: public wxObject | |
156 | { | |
157 | DECLARE_DYNAMIC_CLASS(wxListItem) | |
158 | public: | |
159 | long m_mask; // Indicates what fields are valid | |
160 | long m_itemId; // The zero-based item position | |
161 | int m_col; // Zero-based column, if in report mode | |
162 | long m_state; // The state of the item | |
163 | long m_stateMask; // Which flags of m_state are valid (uses same flags) | |
164 | wxString m_text; // The label/header text | |
165 | int m_image; // The zero-based index into an image list | |
166 | long m_data; // App-defined data | |
167 | ||
168 | // For columns only | |
169 | int m_format; // left, right, centre | |
170 | int m_width; // width of column | |
171 | ||
172 | wxListItem(); | |
173 | }; | |
174 | ||
175 | // type of compare function for wxListCtrl sort operation | |
176 | typedef int (wxCALLBACK *wxListCtrlCompare)(long item1, long item2, long sortData); | |
177 | ||
178 | class WXDLLEXPORT wxListCtrl: public wxControl | |
179 | { | |
180 | DECLARE_DYNAMIC_CLASS(wxListCtrl) | |
181 | public: | |
182 | /* | |
183 | * Public interface | |
184 | */ | |
185 | ||
186 | wxListCtrl(); | |
187 | ||
188 | inline wxListCtrl(wxWindow *parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, | |
189 | long style = wxLC_ICON, const wxValidator& validator = wxDefaultValidator, | |
190 | const wxString& name = "listCtrl") | |
191 | { | |
192 | Create(parent, id, pos, size, style, validator, name); | |
193 | } | |
194 | ~wxListCtrl(); | |
195 | ||
196 | bool Create(wxWindow *parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, | |
197 | long style = wxLC_ICON, const wxValidator& validator = wxDefaultValidator, const wxString& name = "wxListCtrl"); | |
198 | ||
199 | ||
200 | // Attributes | |
201 | //////////////////////////////////////////////////////////////////////////// | |
202 | ||
203 | // Sets the background colour (GetBackgroundColour already implicit in | |
204 | // wxWindow class) | |
205 | bool SetBackgroundColour(const wxColour& col); | |
206 | ||
207 | // Gets information about this column | |
208 | bool GetColumn(int col, wxListItem& item) const; | |
209 | ||
210 | // Sets information about this column | |
211 | bool SetColumn(int col, wxListItem& item) ; | |
212 | ||
213 | // Gets the column width | |
214 | int GetColumnWidth(int col) const; | |
215 | ||
216 | // Sets the column width | |
217 | bool SetColumnWidth(int col, int width) ; | |
218 | ||
219 | // Gets the number of items that can fit vertically in the | |
220 | // visible area of the list control (list or report view) | |
221 | // or the total number of items in the list control (icon | |
222 | // or small icon view) | |
223 | int GetCountPerPage() const; | |
224 | ||
225 | // Gets the edit control for editing labels. | |
226 | wxTextCtrl* GetEditControl() const; | |
227 | ||
228 | // Gets information about the item | |
229 | bool GetItem(wxListItem& info) const ; | |
230 | ||
231 | // Sets information about the item | |
232 | bool SetItem(wxListItem& info) ; | |
233 | ||
234 | // Sets a string field at a particular column | |
235 | long SetItem(long index, int col, const wxString& label, int imageId = -1); | |
236 | ||
237 | // Gets the item state | |
238 | int GetItemState(long item, long stateMask) const ; | |
239 | ||
240 | // Sets the item state | |
241 | bool SetItemState(long item, long state, long stateMask) ; | |
242 | ||
243 | // Sets the item image | |
244 | bool SetItemImage(long item, int image, int selImage) ; | |
245 | ||
246 | // Gets the item text | |
247 | wxString GetItemText(long item) const ; | |
248 | ||
249 | // Sets the item text | |
250 | void SetItemText(long item, const wxString& str) ; | |
251 | ||
252 | // Gets the item data | |
253 | long GetItemData(long item) const ; | |
254 | ||
255 | // Sets the item data | |
256 | bool SetItemData(long item, long data) ; | |
257 | ||
258 | // Gets the item rectangle | |
259 | bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ; | |
260 | ||
261 | // Gets the item position | |
262 | bool GetItemPosition(long item, wxPoint& pos) const ; | |
263 | ||
264 | // Sets the item position | |
265 | bool SetItemPosition(long item, const wxPoint& pos) ; | |
266 | ||
267 | // Gets the number of items in the list control | |
268 | int GetItemCount() const; | |
269 | ||
270 | // Gets the number of columns in the list control | |
271 | int GetColumnCount() const { return m_colCount; } | |
272 | ||
273 | // Retrieves the spacing between icons in pixels. | |
274 | // If small is TRUE, gets the spacing for the small icon | |
275 | // view, otherwise the large icon view. | |
276 | int GetItemSpacing(bool isSmall) const; | |
277 | ||
278 | // Gets the number of selected items in the list control | |
279 | int GetSelectedItemCount() const; | |
280 | ||
281 | // Gets the text colour of the listview | |
282 | wxColour GetTextColour() const; | |
283 | ||
284 | // Sets the text colour of the listview | |
285 | void SetTextColour(const wxColour& col); | |
286 | ||
287 | // Gets the index of the topmost visible item when in | |
288 | // list or report view | |
289 | long GetTopItem() const ; | |
290 | ||
291 | // Add or remove a single window style | |
292 | void SetSingleStyle(long style, bool add = TRUE) ; | |
293 | ||
294 | // Set the whole window style | |
295 | void SetWindowStyleFlag(long style) ; | |
296 | ||
297 | // Searches for an item, starting from 'item'. | |
298 | // item can be -1 to find the first item that matches the | |
299 | // specified flags. | |
300 | // Returns the item or -1 if unsuccessful. | |
301 | long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const ; | |
302 | ||
303 | // Implementation: converts wxWindows style to MSW style. | |
304 | // Can be a single style flag or a bit list. | |
305 | // oldStyle is 'normalised' so that it doesn't contain | |
306 | // conflicting styles. | |
307 | long ConvertToMSWStyle(long& oldStyle, long style) const; | |
308 | ||
309 | // Gets one of the three image lists | |
310 | wxImageList *GetImageList(int which) const ; | |
311 | ||
312 | // Sets the image list | |
313 | // N.B. There's a quirk in the Win95 list view implementation. | |
314 | // If in wxLC_LIST mode, it'll *still* display images by the labels if | |
315 | // there's a small-icon image list set for the control - even though you | |
316 | // haven't specified wxLIST_MASK_IMAGE when inserting. | |
317 | // So you have to set a NULL small-icon image list to be sure that | |
318 | // the wxLC_LIST mode works without icons. Of course, you may want icons... | |
319 | void SetImageList(wxImageList *imageList, int which) ; | |
320 | ||
321 | // Operations | |
322 | //////////////////////////////////////////////////////////////////////////// | |
323 | ||
324 | // Arranges the items | |
325 | bool Arrange(int flag = wxLIST_ALIGN_DEFAULT); | |
326 | ||
327 | // Deletes an item | |
328 | bool DeleteItem(long item); | |
329 | ||
330 | // Deletes all items | |
331 | bool DeleteAllItems() ; | |
332 | ||
333 | // Deletes a column | |
334 | bool DeleteColumn(int col); | |
335 | ||
336 | // Deletes all columns | |
337 | bool DeleteAllColumns(); | |
338 | ||
339 | // Clears items, and columns if there are any. | |
340 | void ClearAll(); | |
341 | ||
342 | // Edit the label | |
343 | wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl)); | |
344 | ||
345 | // End label editing, optionally cancelling the edit | |
346 | bool EndEditLabel(bool cancel); | |
347 | ||
348 | // Ensures this item is visible | |
349 | bool EnsureVisible(long item) ; | |
350 | ||
351 | // Find an item whose label matches this string, starting from the item after 'start' | |
352 | // or the beginning if 'start' is -1. | |
353 | long FindItem(long start, const wxString& str, bool partial = FALSE); | |
354 | ||
355 | // Find an item whose data matches this data, starting from the item after 'start' | |
356 | // or the beginning if 'start' is -1. | |
357 | long FindItem(long start, long data); | |
358 | ||
359 | // Find an item nearest this position in the specified direction, starting from | |
360 | // the item after 'start' or the beginning if 'start' is -1. | |
361 | long FindItem(long start, const wxPoint& pt, int direction); | |
362 | ||
363 | // Determines which item (if any) is at the specified point, | |
364 | // giving details in 'flags' (see wxLIST_HITTEST_... flags above) | |
365 | long HitTest(const wxPoint& point, int& flags); | |
366 | ||
367 | // Inserts an item, returning the index of the new item if successful, | |
368 | // -1 otherwise. | |
369 | // TOD: Should also have some further convenience functions | |
370 | // which don't require setting a wxListItem object | |
371 | long InsertItem(wxListItem& info); | |
372 | ||
373 | // Insert a string item | |
374 | long InsertItem(long index, const wxString& label); | |
375 | ||
376 | // Insert an image item | |
377 | long InsertItem(long index, int imageIndex); | |
378 | ||
379 | // Insert an image/string item | |
380 | long InsertItem(long index, const wxString& label, int imageIndex); | |
381 | ||
382 | // For list view mode (only), inserts a column. | |
383 | long InsertColumn(long col, wxListItem& info); | |
384 | ||
385 | long InsertColumn(long col, const wxString& heading, int format = wxLIST_FORMAT_LEFT, | |
386 | int width = -1); | |
387 | ||
388 | // Scrolls the list control. If in icon, small icon or report view mode, | |
389 | // x specifies the number of pixels to scroll. If in list view mode, x | |
390 | // specifies the number of columns to scroll. | |
391 | // If in icon, small icon or list view mode, y specifies the number of pixels | |
392 | // to scroll. If in report view mode, y specifies the number of lines to scroll. | |
393 | bool ScrollList(int dx, int dy); | |
394 | ||
395 | // Sort items. | |
396 | ||
397 | // fn is a function which takes 3 long arguments: item1, item2, data. | |
398 | // item1 is the long data associated with a first item (NOT the index). | |
399 | // item2 is the long data associated with a second item (NOT the index). | |
400 | // data is the same value as passed to SortItems. | |
401 | // The return value is a negative number if the first item should precede the second | |
402 | // item, a positive number of the second item should precede the first, | |
403 | // or zero if the two items are equivalent. | |
404 | ||
405 | // data is arbitrary data to be passed to the sort function. | |
406 | bool SortItems(wxListCtrlCompare fn, long data); | |
407 | ||
408 | // IMPLEMENTATION | |
409 | virtual bool MSWCommand(WXUINT param, WXWORD id); | |
410 | virtual bool MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result); | |
411 | ||
412 | // bring the control in sync with current m_windowStyle value | |
413 | void UpdateStyle(); | |
414 | ||
415 | // Add to pool: necessary because Windows needs to have a string | |
416 | // still exist across 3 callbacks. | |
417 | wxChar *AddPool(const wxString& str); | |
418 | ||
419 | protected: | |
420 | wxTextCtrl* m_textCtrl; // The control used for editing a label | |
421 | wxImageList * m_imageListNormal; // The image list for normal icons | |
422 | wxImageList * m_imageListSmall; // The image list for small icons | |
423 | wxImageList * m_imageListState; // The image list state icons (not implemented yet) | |
424 | ||
425 | long m_baseStyle; // Basic Windows style flags, for recreation purposes | |
426 | wxStringList m_stringPool; // Pool of 3 strings to satisfy Windows callback | |
427 | // requirements | |
428 | int m_colCount; // Windows doesn't have GetColumnCount so must | |
429 | // keep track of inserted/deleted columns | |
430 | ||
431 | private: | |
432 | bool DoCreateControl(int x, int y, int w, int h); | |
433 | }; | |
434 | ||
435 | #endif | |
436 | // _WX_LISTCTRL_H_ |