1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/msw/listctrl.h
3 // Purpose: wxListCtrl class
4 // Author: Julian Smart
8 // Copyright: (c) Julian Smart
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_LISTCTRL_H_
13 #define _WX_LISTCTRL_H_
16 #pragma interface "listctrl.h"
19 #include "wx/control.h"
21 #include "wx/imaglist.h"
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
33 You can change the style dynamically, either with SetSingleStyle or
36 Further window styles:
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)
49 Items are referred to by their index (position in the list starting from zero).
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).
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.
60 Notifications are passed via the wxWindows 2.0 event system, or using virtual
61 functions in wxWindows 1.66.
63 See the sample wxListCtrl app for API usage.
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.
77 class WXDLLEXPORT wxListCtrl
: public wxControl
84 wxListCtrl() { Init(); }
86 wxListCtrl(wxWindow
*parent
,
88 const wxPoint
& pos
= wxDefaultPosition
,
89 const wxSize
& size
= wxDefaultSize
,
90 long style
= wxLC_ICON
,
91 const wxValidator
& validator
= wxDefaultValidator
,
92 const wxString
& name
= _T("wxListCtrl"))
96 Create(parent
, id
, pos
, size
, style
, validator
, name
);
99 virtual ~wxListCtrl();
101 bool Create(wxWindow
*parent
,
103 const wxPoint
& pos
= wxDefaultPosition
,
104 const wxSize
& size
= wxDefaultSize
,
105 long style
= wxLC_ICON
,
106 const wxValidator
& validator
= wxDefaultValidator
,
107 const wxString
& name
= _T("wxListCtrl"));
111 ////////////////////////////////////////////////////////////////////////////
113 // Sets the background colour (GetBackgroundColour already implicit in
115 bool SetBackgroundColour(const wxColour
& col
);
117 // Gets information about this column
118 bool GetColumn(int col
, wxListItem
& item
) const;
120 // Sets information about this column
121 bool SetColumn(int col
, wxListItem
& item
) ;
123 // Gets the column width
124 int GetColumnWidth(int col
) const;
126 // Sets the column width
127 bool SetColumnWidth(int col
, int width
) ;
129 // Gets the number of items that can fit vertically in the
130 // visible area of the list control (list or report view)
131 // or the total number of items in the list control (icon
132 // or small icon view)
133 int GetCountPerPage() const;
135 // Gets the edit control for editing labels.
136 wxTextCtrl
* GetEditControl() const;
138 // Gets information about the item
139 bool GetItem(wxListItem
& info
) const ;
141 // Sets information about the item
142 bool SetItem(wxListItem
& info
) ;
144 // Sets a string field at a particular column
145 long SetItem(long index
, int col
, const wxString
& label
, int imageId
= -1);
147 // Gets the item state
148 int GetItemState(long item
, long stateMask
) const ;
150 // Sets the item state
151 bool SetItemState(long item
, long state
, long stateMask
) ;
153 // Sets the item image
154 bool SetItemImage(long item
, int image
, int selImage
) ;
156 // Gets the item text
157 wxString
GetItemText(long item
) const ;
159 // Sets the item text
160 void SetItemText(long item
, const wxString
& str
) ;
162 // Gets the item data
163 long GetItemData(long item
) const ;
165 // Sets the item data
166 bool SetItemData(long item
, long data
) ;
168 // Gets the item rectangle
169 bool GetItemRect(long item
, wxRect
& rect
, int code
= wxLIST_RECT_BOUNDS
) const ;
171 // Gets the item position
172 bool GetItemPosition(long item
, wxPoint
& pos
) const ;
174 // Sets the item position
175 bool SetItemPosition(long item
, const wxPoint
& pos
) ;
177 // Gets the number of items in the list control
178 int GetItemCount() const;
180 // Gets the number of columns in the list control
181 int GetColumnCount() const { return m_colCount
; }
183 // Retrieves the spacing between icons in pixels.
184 // If small is TRUE, gets the spacing for the small icon
185 // view, otherwise the large icon view.
186 int GetItemSpacing(bool isSmall
) const;
188 // Gets the number of selected items in the list control
189 int GetSelectedItemCount() const;
191 // Gets the text colour of the listview
192 wxColour
GetTextColour() const;
194 // Sets the text colour of the listview
195 void SetTextColour(const wxColour
& col
);
197 // Gets the index of the topmost visible item when in
198 // list or report view
199 long GetTopItem() const ;
201 // Add or remove a single window style
202 void SetSingleStyle(long style
, bool add
= TRUE
) ;
204 // Set the whole window style
205 void SetWindowStyleFlag(long style
) ;
207 // Searches for an item, starting from 'item'.
208 // item can be -1 to find the first item that matches the
210 // Returns the item or -1 if unsuccessful.
211 long GetNextItem(long item
, int geometry
= wxLIST_NEXT_ALL
, int state
= wxLIST_STATE_DONTCARE
) const ;
213 // Implementation: converts wxWindows style to MSW style.
214 // Can be a single style flag or a bit list.
215 // oldStyle is 'normalised' so that it doesn't contain
216 // conflicting styles.
217 long ConvertToMSWStyle(long& oldStyle
, long style
) const;
219 // Gets one of the three image lists
220 wxImageList
*GetImageList(int which
) const ;
222 // Sets the image list
223 // N.B. There's a quirk in the Win95 list view implementation.
224 // If in wxLC_LIST mode, it'll *still* display images by the labels if
225 // there's a small-icon image list set for the control - even though you
226 // haven't specified wxLIST_MASK_IMAGE when inserting.
227 // So you have to set a NULL small-icon image list to be sure that
228 // the wxLC_LIST mode works without icons. Of course, you may want icons...
229 void SetImageList(wxImageList
*imageList
, int which
) ;
232 ////////////////////////////////////////////////////////////////////////////
234 // Arranges the items
235 bool Arrange(int flag
= wxLIST_ALIGN_DEFAULT
);
238 bool DeleteItem(long item
);
241 bool DeleteAllItems() ;
244 bool DeleteColumn(int col
);
246 // Deletes all columns
247 bool DeleteAllColumns();
249 // Clears items, and columns if there are any.
253 wxTextCtrl
* EditLabel(long item
, wxClassInfo
* textControlClass
= CLASSINFO(wxTextCtrl
));
255 // End label editing, optionally cancelling the edit
256 bool EndEditLabel(bool cancel
);
258 // Ensures this item is visible
259 bool EnsureVisible(long item
) ;
261 // Find an item whose label matches this string, starting from the item after 'start'
262 // or the beginning if 'start' is -1.
263 long FindItem(long start
, const wxString
& str
, bool partial
= FALSE
);
265 // Find an item whose data matches this data, starting from the item after 'start'
266 // or the beginning if 'start' is -1.
267 long FindItem(long start
, long data
);
269 // Find an item nearest this position in the specified direction, starting from
270 // the item after 'start' or the beginning if 'start' is -1.
271 long FindItem(long start
, const wxPoint
& pt
, int direction
);
273 // Determines which item (if any) is at the specified point,
274 // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
275 long HitTest(const wxPoint
& point
, int& flags
);
277 // Inserts an item, returning the index of the new item if successful,
279 long InsertItem(wxListItem
& info
);
281 // Insert a string item
282 long InsertItem(long index
, const wxString
& label
);
284 // Insert an image item
285 long InsertItem(long index
, int imageIndex
);
287 // Insert an image/string item
288 long InsertItem(long index
, const wxString
& label
, int imageIndex
);
290 // For list view mode (only), inserts a column.
291 long InsertColumn(long col
, wxListItem
& info
);
293 long InsertColumn(long col
,
294 const wxString
& heading
,
295 int format
= wxLIST_FORMAT_LEFT
,
298 // Scrolls the list control. If in icon, small icon or report view mode,
299 // x specifies the number of pixels to scroll. If in list view mode, x
300 // specifies the number of columns to scroll.
301 // If in icon, small icon or list view mode, y specifies the number of pixels
302 // to scroll. If in report view mode, y specifies the number of lines to scroll.
303 bool ScrollList(int dx
, int dy
);
307 // fn is a function which takes 3 long arguments: item1, item2, data.
308 // item1 is the long data associated with a first item (NOT the index).
309 // item2 is the long data associated with a second item (NOT the index).
310 // data is the same value as passed to SortItems.
311 // The return value is a negative number if the first item should precede the second
312 // item, a positive number of the second item should precede the first,
313 // or zero if the two items are equivalent.
315 // data is arbitrary data to be passed to the sort function.
316 bool SortItems(wxListCtrlCompare fn
, long data
);
319 virtual bool MSWCommand(WXUINT param
, WXWORD id
);
320 virtual bool MSWOnNotify(int idCtrl
, WXLPARAM lParam
, WXLPARAM
*result
);
322 // bring the control in sync with current m_windowStyle value
325 // Add to pool: necessary because Windows needs to have a string
326 // still exist across 3 callbacks.
327 wxChar
*AddPool(const wxString
& str
);
330 // common part of all ctors
333 wxTextCtrl
* m_textCtrl
; // The control used for editing a label
334 wxImageList
* m_imageListNormal
; // The image list for normal icons
335 wxImageList
* m_imageListSmall
; // The image list for small icons
336 wxImageList
* m_imageListState
; // The image list state icons (not implemented yet)
338 long m_baseStyle
; // Basic Windows style flags, for recreation purposes
339 wxStringList m_stringPool
; // Pool of 3 strings to satisfy Windows callback requirements
340 int m_colCount
; // Windows doesn't have GetColumnCount so must
341 // keep track of inserted/deleted columns
343 // TRUE fi we have any items with custom attributes
347 bool DoCreateControl(int x
, int y
, int w
, int h
);
349 DECLARE_DYNAMIC_CLASS(wxListCtrl
)