]> git.saurik.com Git - wxWidgets.git/blob - include/wx/msw/listctrl.h
First pass at adding MicroWindows support
[wxWidgets.git] / include / wx / msw / listctrl.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/msw/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 #if wxUSE_LISTCTRL
20
21 #include "wx/control.h"
22 #include "wx/event.h"
23 #include "wx/hash.h"
24
25 class WXDLLEXPORT wxTextCtrl;
26 class WXDLLEXPORT wxImageList;
27
28 /*
29 The wxListCtrl can show lists of items in four different modes:
30 wxLC_LIST: multicolumn list view, with optional small icons (icons could be
31 optional for some platforms). Columns are computed automatically,
32 i.e. you don't set columns as in wxLC_REPORT. In other words,
33 the list wraps, unlike a wxListBox.
34 wxLC_REPORT: single or multicolumn report view (with optional header)
35 wxLC_ICON: large icon view, with optional labels
36 wxLC_SMALL_ICON: small icon view, with optional labels
37
38 You can change the style dynamically, either with SetSingleStyle or
39 SetWindowStyleFlag.
40
41 Further window styles:
42
43 wxLC_ALIGN_TOP icons align to the top (default)
44 wxLC_ALIGN_LEFT icons align to the left
45 wxLC_AUTOARRANGE icons arrange themselves
46 wxLC_USER_TEXT the app provides label text on demand, except for column headers
47 wxLC_EDIT_LABELS labels are editable: app will be notified.
48 wxLC_NO_HEADER no header in report mode
49 wxLC_NO_SORT_HEADER can't click on header
50 wxLC_SINGLE_SEL single selection
51 wxLC_SORT_ASCENDING sort ascending (must still supply a comparison callback in SortItems)
52 wxLC_SORT_DESCENDING sort descending (ditto)
53
54 Items are referred to by their index (position in the list starting from zero).
55
56 Label text is supplied via insertion/setting functions and is stored by the
57 control, unless the wxLC_USER_TEXT style has been specified, in which case
58 the app will be notified when text is required (see sample).
59
60 Images are dealt with by (optionally) associating 3 image lists with the control.
61 Zero-based indexes into these image lists indicate which image is to be used for
62 which item. Each image in an image list can contain a mask, and can be made out
63 of either a bitmap, two bitmaps or an icon. See ImagList.h for more details.
64
65 Notifications are passed via the wxWindows 2.0 event system, or using virtual
66 functions in wxWindows 1.66.
67
68 See the sample wxListCtrl app for API usage.
69
70 TODO:
71 - addition of further convenience functions
72 to avoid use of wxListItem in some functions
73 - state/overlay images: probably not needed.
74 - in Win95, you can be called back to supply other information
75 besides text, such as state information. This saves no memory
76 and is probably superfluous to requirements.
77 - testing of whole API, extending current sample.
78
79
80 */
81
82 class WXDLLEXPORT wxListCtrl: public wxControl
83 {
84 public:
85 /*
86 * Public interface
87 */
88
89 wxListCtrl() { Init(); }
90
91 wxListCtrl(wxWindow *parent,
92 wxWindowID id = -1,
93 const wxPoint& pos = wxDefaultPosition,
94 const wxSize& size = wxDefaultSize,
95 long style = wxLC_ICON,
96 const wxValidator& validator = wxDefaultValidator,
97 const wxString& name = _T("wxListCtrl"))
98 {
99 Init();
100
101 Create(parent, id, pos, size, style, validator, name);
102 }
103
104 virtual ~wxListCtrl();
105
106 bool Create(wxWindow *parent,
107 wxWindowID id = -1,
108 const wxPoint& pos = wxDefaultPosition,
109 const wxSize& size = wxDefaultSize,
110 long style = wxLC_ICON,
111 const wxValidator& validator = wxDefaultValidator,
112 const wxString& name = _T("wxListCtrl"));
113
114
115 // Attributes
116 ////////////////////////////////////////////////////////////////////////////
117
118 // Set the control colours
119 bool SetForegroundColour(const wxColour& col);
120 bool SetBackgroundColour(const wxColour& col);
121
122 // Gets information about this column
123 bool GetColumn(int col, wxListItem& item) const;
124
125 // Sets information about this column
126 bool SetColumn(int col, wxListItem& item) ;
127
128 // Gets the column width
129 int GetColumnWidth(int col) const;
130
131 // Sets the column width
132 bool SetColumnWidth(int col, int width) ;
133
134 // Gets the number of items that can fit vertically in the
135 // visible area of the list control (list or report view)
136 // or the total number of items in the list control (icon
137 // or small icon view)
138 int GetCountPerPage() const;
139
140 // Gets the edit control for editing labels.
141 wxTextCtrl* GetEditControl() const;
142
143 // Gets information about the item
144 bool GetItem(wxListItem& info) const ;
145
146 // Sets information about the item
147 bool SetItem(wxListItem& info) ;
148
149 // Sets a string field at a particular column
150 long SetItem(long index, int col, const wxString& label, int imageId = -1);
151
152 // Gets the item state
153 int GetItemState(long item, long stateMask) const ;
154
155 // Sets the item state
156 bool SetItemState(long item, long state, long stateMask) ;
157
158 // Sets the item image
159 bool SetItemImage(long item, int image, int selImage) ;
160
161 // Gets the item text
162 wxString GetItemText(long item) const ;
163
164 // Sets the item text
165 void SetItemText(long item, const wxString& str) ;
166
167 // Gets the item data
168 long GetItemData(long item) const ;
169
170 // Sets the item data
171 bool SetItemData(long item, long data) ;
172
173 // Gets the item rectangle
174 bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ;
175
176 // Gets the item position
177 bool GetItemPosition(long item, wxPoint& pos) const ;
178
179 // Sets the item position
180 bool SetItemPosition(long item, const wxPoint& pos) ;
181
182 // Gets the number of items in the list control
183 int GetItemCount() const;
184
185 // Gets the number of columns in the list control
186 int GetColumnCount() const { return m_colCount; }
187
188 // Retrieves the spacing between icons in pixels.
189 // If small is TRUE, gets the spacing for the small icon
190 // view, otherwise the large icon view.
191 int GetItemSpacing(bool isSmall) const;
192
193 // Gets the number of selected items in the list control
194 int GetSelectedItemCount() const;
195
196 // Gets the text colour of the listview
197 wxColour GetTextColour() const;
198
199 // Sets the text colour of the listview
200 void SetTextColour(const wxColour& col);
201
202 // Gets the index of the topmost visible item when in
203 // list or report view
204 long GetTopItem() const ;
205
206 // Add or remove a single window style
207 void SetSingleStyle(long style, bool add = TRUE) ;
208
209 // Set the whole window style
210 void SetWindowStyleFlag(long style) ;
211
212 // Searches for an item, starting from 'item'.
213 // item can be -1 to find the first item that matches the
214 // specified flags.
215 // Returns the item or -1 if unsuccessful.
216 long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const ;
217
218 // Implementation: converts wxWindows style to MSW style.
219 // Can be a single style flag or a bit list.
220 // oldStyle is 'normalised' so that it doesn't contain
221 // conflicting styles.
222 long ConvertToMSWStyle(long& oldStyle, long style) const;
223
224 // Gets one of the three image lists
225 wxImageList *GetImageList(int which) const ;
226
227 // Sets the image list
228 // N.B. There's a quirk in the Win95 list view implementation.
229 // If in wxLC_LIST mode, it'll *still* display images by the labels if
230 // there's a small-icon image list set for the control - even though you
231 // haven't specified wxLIST_MASK_IMAGE when inserting.
232 // So you have to set a NULL small-icon image list to be sure that
233 // the wxLC_LIST mode works without icons. Of course, you may want icons...
234 void SetImageList(wxImageList *imageList, int which) ;
235 void AssignImageList(wxImageList *imageList, int which) ;
236
237 // Operations
238 ////////////////////////////////////////////////////////////////////////////
239
240 // Arranges the items
241 bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
242
243 // Deletes an item
244 bool DeleteItem(long item);
245
246 // Deletes all items
247 bool DeleteAllItems() ;
248
249 // Deletes a column
250 bool DeleteColumn(int col);
251
252 // Deletes all columns
253 bool DeleteAllColumns();
254
255 // Clears items, and columns if there are any.
256 void ClearAll();
257
258 // Edit the label
259 wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl));
260
261 // End label editing, optionally cancelling the edit
262 bool EndEditLabel(bool cancel);
263
264 // Ensures this item is visible
265 bool EnsureVisible(long item) ;
266
267 // Find an item whose label matches this string, starting from the item after 'start'
268 // or the beginning if 'start' is -1.
269 long FindItem(long start, const wxString& str, bool partial = FALSE);
270
271 // Find an item whose data matches this data, starting from the item after 'start'
272 // or the beginning if 'start' is -1.
273 long FindItem(long start, long data);
274
275 // Find an item nearest this position in the specified direction, starting from
276 // the item after 'start' or the beginning if 'start' is -1.
277 long FindItem(long start, const wxPoint& pt, int direction);
278
279 // Determines which item (if any) is at the specified point,
280 // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
281 long HitTest(const wxPoint& point, int& flags);
282
283 // Inserts an item, returning the index of the new item if successful,
284 // -1 otherwise.
285 long InsertItem(wxListItem& info);
286
287 // Insert a string item
288 long InsertItem(long index, const wxString& label);
289
290 // Insert an image item
291 long InsertItem(long index, int imageIndex);
292
293 // Insert an image/string item
294 long InsertItem(long index, const wxString& label, int imageIndex);
295
296 // For list view mode (only), inserts a column.
297 long InsertColumn(long col, wxListItem& info);
298
299 long InsertColumn(long col,
300 const wxString& heading,
301 int format = wxLIST_FORMAT_LEFT,
302 int width = -1);
303
304 // Scrolls the list control. If in icon, small icon or report view mode,
305 // x specifies the number of pixels to scroll. If in list view mode, x
306 // specifies the number of columns to scroll.
307 // If in icon, small icon or list view mode, y specifies the number of pixels
308 // to scroll. If in report view mode, y specifies the number of lines to scroll.
309 bool ScrollList(int dx, int dy);
310
311 // Sort items.
312
313 // fn is a function which takes 3 long arguments: item1, item2, data.
314 // item1 is the long data associated with a first item (NOT the index).
315 // item2 is the long data associated with a second item (NOT the index).
316 // data is the same value as passed to SortItems.
317 // The return value is a negative number if the first item should precede the second
318 // item, a positive number of the second item should precede the first,
319 // or zero if the two items are equivalent.
320
321 // data is arbitrary data to be passed to the sort function.
322 bool SortItems(wxListCtrlCompare fn, long data);
323
324 // IMPLEMENTATION
325 virtual bool MSWCommand(WXUINT param, WXWORD id);
326 virtual bool MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result);
327
328 // bring the control in sync with current m_windowStyle value
329 void UpdateStyle();
330
331 // Add to pool: necessary because Windows needs to have a string
332 // still exist across 3 callbacks.
333 wxChar *AddPool(const wxString& str);
334
335 // Event handlers
336 ////////////////////////////////////////////////////////////////////////////
337 // Necessary for drawing hrules and vrules, if specified
338 void OnPaint(wxPaintEvent& event);
339
340 protected:
341 // common part of all ctors
342 void Init();
343
344 // free memory taken by all attributes and recreate the hash table
345 void FreeAllAttrs(bool dontRecreate = FALSE);
346
347 wxTextCtrl* m_textCtrl; // The control used for editing a label
348 wxImageList * m_imageListNormal; // The image list for normal icons
349 wxImageList * m_imageListSmall; // The image list for small icons
350 wxImageList * m_imageListState; // The image list state icons (not implemented yet)
351 bool m_ownsImageListNormal,
352 m_ownsImageListSmall,
353 m_ownsImageListState;
354
355 long m_baseStyle; // Basic Windows style flags, for recreation purposes
356 wxStringList m_stringPool; // Pool of 3 strings to satisfy Windows callback requirements
357 int m_colCount; // Windows doesn't have GetColumnCount so must
358 // keep track of inserted/deleted columns
359
360 // the hash table we use for storing pointers to the items attributes
361 wxHashTable m_attrs;
362
363 // TRUE if we have any items with custom attributes
364 bool m_hasAnyAttr;
365
366 private:
367 bool DoCreateControl(int x, int y, int w, int h);
368
369 DECLARE_DYNAMIC_CLASS(wxListCtrl)
370 DECLARE_EVENT_TABLE()
371 };
372
373 #endif // wxUSE_LISTCTRL
374
375 #endif
376 // _WX_LISTCTRL_H_