]> git.saurik.com Git - wxWidgets.git/blob - include/wx/palmos/listctrl.h
Fix handling of asterisks in wxPrintf() implementation.
[wxWidgets.git] / include / wx / palmos / listctrl.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/palmos/listctrl.h
3 // Purpose: wxListCtrl class
4 // Author: William Osborne - minimal working wxPalmOS port
5 // Modified by: Yunhui Fu
6 // Created: 10/13/04
7 // RCS-ID: $Id$
8 // Copyright: (c) William Osborne
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
11
12 #ifndef _WX_LISTCTRL_H_
13 #define _WX_LISTCTRL_H_
14
15 #if wxUSE_LISTCTRL
16
17 #include "wx/control.h"
18 #include "wx/event.h"
19 #include "wx/hash.h"
20 #include "wx/textctrl.h"
21
22
23 class WXDLLIMPEXP_FWD_CORE wxImageList;
24
25 /*
26 The wxListCtrl can show lists of items in four different modes:
27 wxLC_LIST: multicolumn list view, with optional small icons (icons could be
28 optional for some platforms). Columns are computed automatically,
29 i.e. you don't set columns as in wxLC_REPORT. In other words,
30 the list wraps, unlike a wxListBox.
31 wxLC_REPORT: single or multicolumn report view (with optional header)
32 wxLC_ICON: large icon view, with optional labels
33 wxLC_SMALL_ICON: small icon view, with optional labels
34
35 You can change the style dynamically, either with SetSingleStyle or
36 SetWindowStyleFlag.
37
38 Further window styles:
39
40 wxLC_ALIGN_TOP icons align to the top (default)
41 wxLC_ALIGN_LEFT icons align to the left
42 wxLC_AUTOARRANGE icons arrange themselves
43 wxLC_USER_TEXT the app provides label text on demand, except for column headers
44 wxLC_EDIT_LABELS labels are editable: app will be notified.
45 wxLC_NO_HEADER no header in report mode
46 wxLC_NO_SORT_HEADER can't click on header
47 wxLC_SINGLE_SEL single selection
48 wxLC_SORT_ASCENDING sort ascending (must still supply a comparison callback in SortItems)
49 wxLC_SORT_DESCENDING sort descending (ditto)
50
51 Items are referred to by their index (position in the list starting from zero).
52
53 Label text is supplied via insertion/setting functions and is stored by the
54 control, unless the wxLC_USER_TEXT style has been specified, in which case
55 the app will be notified when text is required (see sample).
56
57 Images are dealt with by (optionally) associating 3 image lists with the control.
58 Zero-based indexes into these image lists indicate which image is to be used for
59 which item. Each image in an image list can contain a mask, and can be made out
60 of either a bitmap, two bitmaps or an icon. See ImagList.h for more details.
61
62 Notifications are passed via the wxWidgets 2.0 event system, or using virtual
63 functions in wxWidgets 1.66.
64
65 See the sample wxListCtrl app for API usage.
66
67 TODO:
68 - addition of further convenience functions
69 to avoid use of wxListItem in some functions
70 - state/overlay images: probably not needed.
71 - testing of whole API, extending current sample.
72
73
74 */
75
76 class WXDLLIMPEXP_CORE wxListCtrl: public wxControl
77 {
78 public:
79 /*
80 * Public interface
81 */
82
83 wxListCtrl() { Init(); }
84
85 wxListCtrl(wxWindow *parent,
86 wxWindowID id = wxID_ANY,
87 const wxPoint& pos = wxDefaultPosition,
88 const wxSize& size = wxDefaultSize,
89 long style = wxLC_ICON,
90 const wxValidator& validator = wxDefaultValidator,
91 const wxString& name = wxListCtrlNameStr)
92 {
93 Init();
94
95 Create(parent, id, pos, size, style, validator, name);
96 }
97
98 virtual ~wxListCtrl();
99
100 bool Create(wxWindow *parent,
101 wxWindowID id = wxID_ANY,
102 const wxPoint& pos = wxDefaultPosition,
103 const wxSize& size = wxDefaultSize,
104 long style = wxLC_ICON,
105 const wxValidator& validator = wxDefaultValidator,
106 const wxString& name = wxListCtrlNameStr);
107
108
109 // Attributes
110 ////////////////////////////////////////////////////////////////////////////
111
112 // Set the control colours
113 bool SetForegroundColour(const wxColour& col);
114 bool SetBackgroundColour(const wxColour& col);
115
116 // Gets information about this column
117 bool GetColumn(int col, wxListItem& item) const;
118
119 // Sets information about this column
120 bool SetColumn(int col, wxListItem& item) ;
121
122 // Gets the column width
123 int GetColumnWidth(int col) const;
124
125 // Sets the column width
126 bool SetColumnWidth(int col, int width) ;
127
128 // Gets the number of items that can fit vertically in the
129 // visible area of the list control (list or report view)
130 // or the total number of items in the list control (icon
131 // or small icon view)
132 int GetCountPerPage() const;
133
134 // return the total area occupied by all the items (icon/small icon only)
135 wxRect GetViewRect() const;
136
137 // Gets the edit control for editing labels.
138 wxTextCtrl* GetEditControl() const;
139
140 // Gets information about the item
141 bool GetItem(wxListItem& info) const ;
142
143 // Sets information about the item
144 bool SetItem(wxListItem& info) ;
145
146 // Sets a string field at a particular column
147 long SetItem(long index, int col, const wxString& label, int imageId = -1);
148
149 // Gets the item state
150 int GetItemState(long item, long stateMask) const ;
151
152 // Sets the item state
153 bool SetItemState(long item, long state, long stateMask) ;
154
155 // Sets the item image
156 bool SetItemImage(long item, int image, int selImage) ;
157 bool SetItemColumnImage(long item, long column, int image);
158
159 // Gets the item text
160 wxString GetItemText(long item) const ;
161
162 // Sets the item text
163 void SetItemText(long item, const wxString& str) ;
164
165 // Gets the item data
166 long GetItemData(long item) const ;
167
168 // Sets the item data
169 bool SetItemPtrData(long item, wxUIntPtr data);
170 bool SetItemData(long item, long data) { return SetItemPtrData(item, data); }
171
172 // Gets the item rectangle
173 bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ;
174
175 // Gets the item position
176 bool GetItemPosition(long item, wxPoint& pos) const ;
177
178 // Sets the item position
179 bool SetItemPosition(long item, const wxPoint& pos) ;
180
181 // Gets the number of items in the list control
182 int GetItemCount() const;
183
184 // Gets the number of columns in the list control
185 int GetColumnCount() const { return m_colCount; }
186
187 // get the horizontal and vertical components of the item spacing
188 wxSize GetItemSpacing() const;
189
190 // Foreground colour of an item.
191 void SetItemTextColour( long item, const wxColour& col);
192 wxColour GetItemTextColour( long item ) const;
193
194 // Background colour of an item.
195 void SetItemBackgroundColour( long item, const wxColour &col);
196 wxColour GetItemBackgroundColour( long item ) const;
197
198 // Gets the number of selected items in the list control
199 int GetSelectedItemCount() const;
200
201 // Gets the text colour of the listview
202 wxColour GetTextColour() const;
203
204 // Sets the text colour of the listview
205 void SetTextColour(const wxColour& col);
206
207 // Gets the index of the topmost visible item when in
208 // list or report view
209 long GetTopItem() const ;
210
211 // Add or remove a single window style
212 void SetSingleStyle(long style, bool add = true) ;
213
214 // Searches for an item, starting from 'item'.
215 // item can be -1 to find the first item that matches the
216 // specified flags.
217 // Returns the item or -1 if unsuccessful.
218 long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const ;
219
220 // Gets one of the three image lists
221 wxImageList *GetImageList(int which) const ;
222
223 // Sets the image list
224 void SetImageList(wxImageList *imageList, int which) ;
225 void AssignImageList(wxImageList *imageList, int which) ;
226
227 // are we in report mode?
228 bool InReportView() const { return HasFlag(wxLC_REPORT); }
229
230 // are we in virtual report mode?
231 bool IsVirtual() const { return HasFlag(wxLC_VIRTUAL); }
232
233 // refresh items selectively (only useful for virtual list controls)
234 void RefreshItem(long item);
235 void RefreshItems(long itemFrom, long itemTo);
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 = wxCLASSINFO(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 // set the number of items in a virtual list control
305 void SetItemCount(long count);
306
307 // Scrolls the list control. If in icon, small icon or report view mode,
308 // x specifies the number of pixels to scroll. If in list view mode, x
309 // specifies the number of columns to scroll.
310 // If in icon, small icon or list view mode, y specifies the number of pixels
311 // to scroll. If in report view mode, y specifies the number of lines to scroll.
312 bool ScrollList(int dx, int dy);
313
314 // Sort items.
315
316 // fn is a function which takes 3 long arguments: item1, item2, data.
317 // item1 is the long data associated with a first item (NOT the index).
318 // item2 is the long data associated with a second item (NOT the index).
319 // data is the same value as passed to SortItems.
320 // The return value is a negative number if the first item should precede the second
321 // item, a positive number of the second item should precede the first,
322 // or zero if the two items are equivalent.
323
324 // data is arbitrary data to be passed to the sort function.
325 bool SortItems(wxListCtrlCompare fn, long data);
326
327 // bring the control in sync with current m_windowStyle value
328 void UpdateStyle();
329
330 // Event handlers
331 ////////////////////////////////////////////////////////////////////////////
332 // Necessary for drawing hrules and vrules, if specified
333 void OnPaint(wxPaintEvent& event);
334
335
336 virtual bool ShouldInheritColours() const { return false; }
337
338 virtual wxVisualAttributes GetDefaultAttributes() const
339 {
340 return GetClassDefaultAttributes(GetWindowVariant());
341 }
342
343 static wxVisualAttributes
344 GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
345
346 protected:
347 // common part of all ctors
348 void Init();
349
350 // free memory taken by all internal data
351 void FreeAllInternalData();
352
353 wxTextCtrl* m_textCtrl; // The control used for editing a label
354 wxImageList * m_imageListNormal; // The image list for normal icons
355 wxImageList * m_imageListSmall; // The image list for small icons
356 wxImageList * m_imageListState; // The image list state icons (not implemented yet)
357 bool m_ownsImageListNormal,
358 m_ownsImageListSmall,
359 m_ownsImageListState;
360
361 int m_colCount; // Windows doesn't have GetColumnCount so must
362 // keep track of inserted/deleted columns
363 long m_count; // Keep track of item count to save calls to
364 // ListView_GetItemCount
365 bool m_ignoreChangeMessages;
366
367 // true if we have any internal data (user data & attributes)
368 bool m_AnyInternalData;
369
370 // true if we have any items with custom attributes
371 bool m_hasAnyAttr;
372
373 // these functions are only used for virtual list view controls, i.e. the
374 // ones with wxLC_VIRTUAL style
375
376 // return the text for the given column of the given item
377 virtual wxString OnGetItemText(long item, long column) const;
378
379 // return the icon for the given item. In report view, OnGetItemImage will
380 // only be called for the first column. See OnGetItemColumnImage for
381 // details.
382 virtual int OnGetItemImage(long item) const;
383
384 // return the attribute for the item (may return NULL if none)
385 virtual wxListItemAttr *OnGetItemAttr(long item) const;
386
387 private:
388
389 DECLARE_DYNAMIC_CLASS(wxListCtrl)
390 DECLARE_EVENT_TABLE()
391 wxDECLARE_NO_COPY_CLASS(wxListCtrl);
392 };
393
394 #endif // wxUSE_LISTCTRL
395
396 #endif // _WX_LISTCTRL_H_