]>
git.saurik.com Git - wxWidgets.git/blob - include/wx/msw/listctrl.h
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"
21 #include "wx/control.h"
25 class WXDLLEXPORT wxTextCtrl
;
26 class WXDLLEXPORT wxImageList
;
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
38 You can change the style dynamically, either with SetSingleStyle or
41 Further window styles:
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)
54 Items are referred to by their index (position in the list starting from zero).
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).
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.
65 Notifications are passed via the wxWindows 2.0 event system, or using virtual
66 functions in wxWindows 1.66.
68 See the sample wxListCtrl app for API usage.
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.
82 class WXDLLEXPORT wxListCtrl
: public wxControl
89 wxListCtrl() { Init(); }
91 wxListCtrl(wxWindow
*parent
,
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"))
101 Create(parent
, id
, pos
, size
, style
, validator
, name
);
104 virtual ~wxListCtrl();
106 bool Create(wxWindow
*parent
,
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"));
116 ////////////////////////////////////////////////////////////////////////////
118 // Set the control colours
119 bool SetForegroundColour(const wxColour
& col
);
120 bool SetBackgroundColour(const wxColour
& col
);
122 // Gets information about this column
123 bool GetColumn(int col
, wxListItem
& item
) const;
125 // Sets information about this column
126 bool SetColumn(int col
, wxListItem
& item
) ;
128 // Gets the column width
129 int GetColumnWidth(int col
) const;
131 // Sets the column width
132 bool SetColumnWidth(int col
, int width
) ;
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;
140 // Gets the edit control for editing labels.
141 wxTextCtrl
* GetEditControl() const;
143 // Gets information about the item
144 bool GetItem(wxListItem
& info
) const ;
146 // Sets information about the item
147 bool SetItem(wxListItem
& info
) ;
149 // Sets a string field at a particular column
150 long SetItem(long index
, int col
, const wxString
& label
, int imageId
= -1);
152 // Gets the item state
153 int GetItemState(long item
, long stateMask
) const ;
155 // Sets the item state
156 bool SetItemState(long item
, long state
, long stateMask
) ;
158 // Sets the item image
159 bool SetItemImage(long item
, int image
, int selImage
) ;
161 // Gets the item text
162 wxString
GetItemText(long item
) const ;
164 // Sets the item text
165 void SetItemText(long item
, const wxString
& str
) ;
167 // Gets the item data
168 long GetItemData(long item
) const ;
170 // Sets the item data
171 bool SetItemData(long item
, long data
) ;
173 // Gets the item rectangle
174 bool GetItemRect(long item
, wxRect
& rect
, int code
= wxLIST_RECT_BOUNDS
) const ;
176 // Gets the item position
177 bool GetItemPosition(long item
, wxPoint
& pos
) const ;
179 // Sets the item position
180 bool SetItemPosition(long item
, const wxPoint
& pos
) ;
182 // Gets the number of items in the list control
183 int GetItemCount() const;
185 // Gets the number of columns in the list control
186 int GetColumnCount() const { return m_colCount
; }
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;
193 // Gets the number of selected items in the list control
194 int GetSelectedItemCount() const;
196 // Gets the text colour of the listview
197 wxColour
GetTextColour() const;
199 // Sets the text colour of the listview
200 void SetTextColour(const wxColour
& col
);
202 // Gets the index of the topmost visible item when in
203 // list or report view
204 long GetTopItem() const ;
206 // Add or remove a single window style
207 void SetSingleStyle(long style
, bool add
= TRUE
) ;
209 // Set the whole window style
210 void SetWindowStyleFlag(long style
) ;
212 // Searches for an item, starting from 'item'.
213 // item can be -1 to find the first item that matches the
215 // Returns the item or -1 if unsuccessful.
216 long GetNextItem(long item
, int geometry
= wxLIST_NEXT_ALL
, int state
= wxLIST_STATE_DONTCARE
) const ;
218 // Gets one of the three image lists
219 wxImageList
*GetImageList(int which
) const ;
221 // Sets the image list
222 // N.B. There's a quirk in the Win95 list view implementation.
223 // If in wxLC_LIST mode, it'll *still* display images by the labels if
224 // there's a small-icon image list set for the control - even though you
225 // haven't specified wxLIST_MASK_IMAGE when inserting.
226 // So you have to set a NULL small-icon image list to be sure that
227 // the wxLC_LIST mode works without icons. Of course, you may want icons...
228 void SetImageList(wxImageList
*imageList
, int which
) ;
229 void AssignImageList(wxImageList
*imageList
, int which
) ;
231 // returns true if it is a virtual list control
232 bool IsVirtual() const { return (GetWindowStyle() & wxLC_VIRTUAL
) != 0; }
235 ////////////////////////////////////////////////////////////////////////////
237 // Arranges the items
238 bool Arrange(int flag
= wxLIST_ALIGN_DEFAULT
);
241 bool DeleteItem(long item
);
244 bool DeleteAllItems() ;
247 bool DeleteColumn(int col
);
249 // Deletes all columns
250 bool DeleteAllColumns();
252 // Clears items, and columns if there are any.
256 wxTextCtrl
* EditLabel(long item
, wxClassInfo
* textControlClass
= CLASSINFO(wxTextCtrl
));
258 // End label editing, optionally cancelling the edit
259 bool EndEditLabel(bool cancel
);
261 // Ensures this item is visible
262 bool EnsureVisible(long item
) ;
264 // Find an item whose label matches this string, starting from the item after 'start'
265 // or the beginning if 'start' is -1.
266 long FindItem(long start
, const wxString
& str
, bool partial
= FALSE
);
268 // Find an item whose data matches this data, starting from the item after 'start'
269 // or the beginning if 'start' is -1.
270 long FindItem(long start
, long data
);
272 // Find an item nearest this position in the specified direction, starting from
273 // the item after 'start' or the beginning if 'start' is -1.
274 long FindItem(long start
, const wxPoint
& pt
, int direction
);
276 // Determines which item (if any) is at the specified point,
277 // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
278 long HitTest(const wxPoint
& point
, int& flags
);
280 // Inserts an item, returning the index of the new item if successful,
282 long InsertItem(wxListItem
& info
);
284 // Insert a string item
285 long InsertItem(long index
, const wxString
& label
);
287 // Insert an image item
288 long InsertItem(long index
, int imageIndex
);
290 // Insert an image/string item
291 long InsertItem(long index
, const wxString
& label
, int imageIndex
);
293 // For list view mode (only), inserts a column.
294 long InsertColumn(long col
, wxListItem
& info
);
296 long InsertColumn(long col
,
297 const wxString
& heading
,
298 int format
= wxLIST_FORMAT_LEFT
,
301 // set the number of items in a virtual list control
302 void SetItemCount(long count
);
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
);
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.
321 // data is arbitrary data to be passed to the sort function.
322 bool SortItems(wxListCtrlCompare fn
, long data
);
325 virtual bool MSWCommand(WXUINT param
, WXWORD id
);
326 virtual bool MSWOnNotify(int idCtrl
, WXLPARAM lParam
, WXLPARAM
*result
);
328 // bring the control in sync with current m_windowStyle value
331 // Implementation: converts wxWindows style to MSW style.
332 // Can be a single style flag or a bit list.
333 // oldStyle is 'normalised' so that it doesn't contain
334 // conflicting styles.
335 long ConvertToMSWStyle(long& oldStyle
, long style
) const;
338 ////////////////////////////////////////////////////////////////////////////
339 // Necessary for drawing hrules and vrules, if specified
340 void OnPaint(wxPaintEvent
& event
);
343 // common part of all ctors
346 // free memory taken by all attributes and recreate the hash table
347 void FreeAllAttrs(bool dontRecreate
= FALSE
);
349 wxTextCtrl
* m_textCtrl
; // The control used for editing a label
350 wxImageList
* m_imageListNormal
; // The image list for normal icons
351 wxImageList
* m_imageListSmall
; // The image list for small icons
352 wxImageList
* m_imageListState
; // The image list state icons (not implemented yet)
353 bool m_ownsImageListNormal
,
354 m_ownsImageListSmall
,
355 m_ownsImageListState
;
357 long m_baseStyle
; // Basic Windows style flags, for recreation purposes
358 int m_colCount
; // Windows doesn't have GetColumnCount so must
359 // keep track of inserted/deleted columns
361 // the hash table we use for storing pointers to the items attributes
364 // TRUE if we have any items with custom attributes
367 // these functions are only used for virtual list view controls, i.e. the
368 // ones with wxLC_VIRTUAL style
370 // return the text for the given column of the given item
371 virtual wxString
OnGetItemText(long item
, long column
) const;
373 // return the icon for the given item
374 virtual int OnGetItemImage(long item
) const;
376 // return the attribute for the item (may return NULL if none)
377 virtual wxListItemAttr
*OnGetItemAttr(long item
) const;
380 bool DoCreateControl(int x
, int y
, int w
, int h
);
382 DECLARE_DYNAMIC_CLASS(wxListCtrl
)
383 DECLARE_EVENT_TABLE()
386 #endif // wxUSE_LISTCTRL