]>
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_
15 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
16 #pragma interface "listctrl.h"
21 #include "wx/control.h"
24 #include "wx/textctrl.h"
27 class WXDLLEXPORT wxImageList
;
30 The wxListCtrl can show lists of items in four different modes:
31 wxLC_LIST: multicolumn list view, with optional small icons (icons could be
32 optional for some platforms). Columns are computed automatically,
33 i.e. you don't set columns as in wxLC_REPORT. In other words,
34 the list wraps, unlike a wxListBox.
35 wxLC_REPORT: single or multicolumn report view (with optional header)
36 wxLC_ICON: large icon view, with optional labels
37 wxLC_SMALL_ICON: small icon view, with optional labels
39 You can change the style dynamically, either with SetSingleStyle or
42 Further window styles:
44 wxLC_ALIGN_TOP icons align to the top (default)
45 wxLC_ALIGN_LEFT icons align to the left
46 wxLC_AUTOARRANGE icons arrange themselves
47 wxLC_USER_TEXT the app provides label text on demand, except for column headers
48 wxLC_EDIT_LABELS labels are editable: app will be notified.
49 wxLC_NO_HEADER no header in report mode
50 wxLC_NO_SORT_HEADER can't click on header
51 wxLC_SINGLE_SEL single selection
52 wxLC_SORT_ASCENDING sort ascending (must still supply a comparison callback in SortItems)
53 wxLC_SORT_DESCENDING sort descending (ditto)
55 Items are referred to by their index (position in the list starting from zero).
57 Label text is supplied via insertion/setting functions and is stored by the
58 control, unless the wxLC_USER_TEXT style has been specified, in which case
59 the app will be notified when text is required (see sample).
61 Images are dealt with by (optionally) associating 3 image lists with the control.
62 Zero-based indexes into these image lists indicate which image is to be used for
63 which item. Each image in an image list can contain a mask, and can be made out
64 of either a bitmap, two bitmaps or an icon. See ImagList.h for more details.
66 Notifications are passed via the wxWidgets 2.0 event system, or using virtual
67 functions in wxWidgets 1.66.
69 See the sample wxListCtrl app for API usage.
72 - addition of further convenience functions
73 to avoid use of wxListItem in some functions
74 - state/overlay images: probably not needed.
75 - in Win95, you can be called back to supply other information
76 besides text, such as state information. This saves no memory
77 and is probably superfluous to requirements.
78 - testing of whole API, extending current sample.
83 class WXDLLEXPORT wxListCtrl
: public wxControl
90 wxListCtrl() { Init(); }
92 wxListCtrl(wxWindow
*parent
,
93 wxWindowID id
= wxID_ANY
,
94 const wxPoint
& pos
= wxDefaultPosition
,
95 const wxSize
& size
= wxDefaultSize
,
96 long style
= wxLC_ICON
,
97 const wxValidator
& validator
= wxDefaultValidator
,
98 const wxString
& name
= _T("wxListCtrl"))
102 Create(parent
, id
, pos
, size
, style
, validator
, name
);
105 virtual ~wxListCtrl();
107 bool Create(wxWindow
*parent
,
108 wxWindowID id
= wxID_ANY
,
109 const wxPoint
& pos
= wxDefaultPosition
,
110 const wxSize
& size
= wxDefaultSize
,
111 long style
= wxLC_ICON
,
112 const wxValidator
& validator
= wxDefaultValidator
,
113 const wxString
& name
= _T("wxListCtrl"));
117 ////////////////////////////////////////////////////////////////////////////
119 // Set the control colours
120 bool SetForegroundColour(const wxColour
& col
);
121 bool SetBackgroundColour(const wxColour
& col
);
123 // Gets information about this column
124 bool GetColumn(int col
, wxListItem
& item
) const;
126 // Sets information about this column
127 bool SetColumn(int col
, wxListItem
& item
) ;
129 // Gets the column width
130 int GetColumnWidth(int col
) const;
132 // Sets the column width
133 bool SetColumnWidth(int col
, int width
) ;
135 // Gets the number of items that can fit vertically in the
136 // visible area of the list control (list or report view)
137 // or the total number of items in the list control (icon
138 // or small icon view)
139 int GetCountPerPage() const;
141 // return the total area occupied by all the items (icon/small icon only)
142 wxRect
GetViewRect() const;
144 // Gets the edit control for editing labels.
145 wxTextCtrl
* GetEditControl() const;
147 // Gets information about the item
148 bool GetItem(wxListItem
& info
) const ;
150 // Sets information about the item
151 bool SetItem(wxListItem
& info
) ;
153 // Sets a string field at a particular column
154 long SetItem(long index
, int col
, const wxString
& label
, int imageId
= -1);
156 // Gets the item state
157 int GetItemState(long item
, long stateMask
) const ;
159 // Sets the item state
160 bool SetItemState(long item
, long state
, long stateMask
) ;
162 // Sets the item image
163 #if WXWIN_COMPATIBILITY_2_4
164 wxDEPRECATED(bool SetItemImage(long item
, int image
, int selImage
)) ;
166 bool SetItemImage(long item
, int image
) ;
168 // Gets the item text
169 wxString
GetItemText(long item
) const ;
171 // Sets the item text
172 void SetItemText(long item
, const wxString
& str
) ;
174 // Gets the item data
175 wxUIntPtr
GetItemData(long item
) const ;
177 // Sets the item data
178 bool SetItemData(long item
, long data
) ;
180 // Gets the item rectangle
181 bool GetItemRect(long item
, wxRect
& rect
, int code
= wxLIST_RECT_BOUNDS
) const ;
183 // Gets the item position
184 bool GetItemPosition(long item
, wxPoint
& pos
) const ;
186 // Sets the item position
187 bool SetItemPosition(long item
, const wxPoint
& pos
) ;
189 // Gets the number of items in the list control
190 int GetItemCount() const;
192 // Gets the number of columns in the list control
193 int GetColumnCount() const { return m_colCount
; }
195 // get the horizontal and vertical components of the item spacing
196 wxSize
GetItemSpacing() const;
198 // Foreground colour of an item.
199 void SetItemTextColour( long item
, const wxColour
& col
);
200 wxColour
GetItemTextColour( long item
) const;
202 // Background colour of an item.
203 void SetItemBackgroundColour( long item
, const wxColour
&col
);
204 wxColour
GetItemBackgroundColour( long item
) const;
206 // Gets the number of selected items in the list control
207 int GetSelectedItemCount() const;
209 // Gets the text colour of the listview
210 wxColour
GetTextColour() const;
212 // Sets the text colour of the listview
213 void SetTextColour(const wxColour
& col
);
215 // Gets the index of the topmost visible item when in
216 // list or report view
217 long GetTopItem() const ;
219 // Add or remove a single window style
220 void SetSingleStyle(long style
, bool add
= true) ;
222 // Set the whole window style
223 void SetWindowStyleFlag(long style
) ;
225 // Searches for an item, starting from 'item'.
226 // item can be -1 to find the first item that matches the
228 // Returns the item or -1 if unsuccessful.
229 long GetNextItem(long item
, int geometry
= wxLIST_NEXT_ALL
, int state
= wxLIST_STATE_DONTCARE
) const ;
231 // Gets one of the three image lists
232 wxImageList
*GetImageList(int which
) const ;
234 // Sets the image list
235 // N.B. There's a quirk in the Win95 list view implementation.
236 // If in wxLC_LIST mode, it'll *still* display images by the labels if
237 // there's a small-icon image list set for the control - even though you
238 // haven't specified wxLIST_MASK_IMAGE when inserting.
239 // So you have to set a NULL small-icon image list to be sure that
240 // the wxLC_LIST mode works without icons. Of course, you may want icons...
241 void SetImageList(wxImageList
*imageList
, int which
) ;
242 void AssignImageList(wxImageList
*imageList
, int which
) ;
244 // are we in report mode?
245 bool InReportView() const { return HasFlag(wxLC_REPORT
); }
247 // are we in virtual report mode?
248 bool IsVirtual() const { return HasFlag(wxLC_VIRTUAL
); }
250 // refresh items selectively (only useful for virtual list controls)
251 void RefreshItem(long item
);
252 void RefreshItems(long itemFrom
, long itemTo
);
255 ////////////////////////////////////////////////////////////////////////////
257 // Arranges the items
258 bool Arrange(int flag
= wxLIST_ALIGN_DEFAULT
);
261 bool DeleteItem(long item
);
264 bool DeleteAllItems() ;
267 bool DeleteColumn(int col
);
269 // Deletes all columns
270 bool DeleteAllColumns();
272 // Clears items, and columns if there are any.
276 wxTextCtrl
* EditLabel(long item
, wxClassInfo
* textControlClass
= CLASSINFO(wxTextCtrl
));
278 // End label editing, optionally cancelling the edit
279 bool EndEditLabel(bool cancel
);
281 // Ensures this item is visible
282 bool EnsureVisible(long item
) ;
284 // Find an item whose label matches this string, starting from the item after 'start'
285 // or the beginning if 'start' is -1.
286 long FindItem(long start
, const wxString
& str
, bool partial
= false);
288 // Find an item whose data matches this data, starting from the item after 'start'
289 // or the beginning if 'start' is -1.
290 long FindItem(long start
, wxUIntPtr data
);
292 // Find an item nearest this position in the specified direction, starting from
293 // the item after 'start' or the beginning if 'start' is -1.
294 long FindItem(long start
, const wxPoint
& pt
, int direction
);
296 // Determines which item (if any) is at the specified point,
297 // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
298 long HitTest(const wxPoint
& point
, int& flags
);
300 // Inserts an item, returning the index of the new item if successful,
302 long InsertItem(wxListItem
& info
);
304 // Insert a string item
305 long InsertItem(long index
, const wxString
& label
);
307 // Insert an image item
308 long InsertItem(long index
, int imageIndex
);
310 // Insert an image/string item
311 long InsertItem(long index
, const wxString
& label
, int imageIndex
);
313 // For list view mode (only), inserts a column.
314 long InsertColumn(long col
, wxListItem
& info
);
316 long InsertColumn(long col
,
317 const wxString
& heading
,
318 int format
= wxLIST_FORMAT_LEFT
,
321 // set the number of items in a virtual list control
322 void SetItemCount(long count
);
324 // Scrolls the list control. If in icon, small icon or report view mode,
325 // x specifies the number of pixels to scroll. If in list view mode, x
326 // specifies the number of columns to scroll.
327 // If in icon, small icon or list view mode, y specifies the number of pixels
328 // to scroll. If in report view mode, y specifies the number of lines to scroll.
329 bool ScrollList(int dx
, int dy
);
333 // fn is a function which takes 3 long arguments: item1, item2, data.
334 // item1 is the long data associated with a first item (NOT the index).
335 // item2 is the long data associated with a second item (NOT the index).
336 // data is the same value as passed to SortItems.
337 // The return value is a negative number if the first item should precede the second
338 // item, a positive number of the second item should precede the first,
339 // or zero if the two items are equivalent.
341 // data is arbitrary data to be passed to the sort function.
342 bool SortItems(wxListCtrlCompare fn
, long data
);
345 virtual bool MSWCommand(WXUINT param
, WXWORD id
);
346 virtual bool MSWOnNotify(int idCtrl
, WXLPARAM lParam
, WXLPARAM
*result
);
348 // bring the control in sync with current m_windowStyle value
352 ////////////////////////////////////////////////////////////////////////////
353 // Necessary for drawing hrules and vrules, if specified
354 void OnPaint(wxPaintEvent
& event
);
357 virtual bool ShouldInheritColours() const { return false; }
359 virtual wxVisualAttributes
GetDefaultAttributes() const
361 return GetClassDefaultAttributes(GetWindowVariant());
364 static wxVisualAttributes
365 GetClassDefaultAttributes(wxWindowVariant variant
= wxWINDOW_VARIANT_NORMAL
);
368 // obsolete stuff, for compatibility only -- don't use
369 wxDEPRECATED( int GetItemSpacing(bool isSmall
) const);
372 // common part of all ctors
375 // free memory taken by all internal data
376 void FreeAllInternalData();
378 // convert our styles to Windows
379 virtual WXDWORD
MSWGetStyle(long style
, WXDWORD
*exstyle
) const;
382 wxTextCtrl
* m_textCtrl
; // The control used for editing a label
383 wxImageList
* m_imageListNormal
; // The image list for normal icons
384 wxImageList
* m_imageListSmall
; // The image list for small icons
385 wxImageList
* m_imageListState
; // The image list state icons (not implemented yet)
386 bool m_ownsImageListNormal
,
387 m_ownsImageListSmall
,
388 m_ownsImageListState
;
390 int m_colCount
; // Windows doesn't have GetColumnCount so must
391 // keep track of inserted/deleted columns
392 long m_count
; // Keep track of item count to save calls to
393 // ListView_GetItemCount
394 bool m_ignoreChangeMessages
;
396 // true if we have any internal data (user data & attributes)
397 bool m_AnyInternalData
;
399 // true if we have any items with custom attributes
402 // these functions are only used for virtual list view controls, i.e. the
403 // ones with wxLC_VIRTUAL style
405 // return the text for the given column of the given item
406 virtual wxString
OnGetItemText(long item
, long column
) const;
408 // return the icon for the given item
409 virtual int OnGetItemImage(long item
) const;
411 // return the attribute for the item (may return NULL if none)
412 virtual wxListItemAttr
*OnGetItemAttr(long item
) const;
415 // process NM_CUSTOMDRAW notification message
416 WXLPARAM
OnCustomDraw(WXLPARAM lParam
);
418 DECLARE_DYNAMIC_CLASS(wxListCtrl
)
419 DECLARE_EVENT_TABLE()
420 DECLARE_NO_COPY_CLASS(wxListCtrl
)
423 #endif // wxUSE_LISTCTRL
425 #endif // _WX_LISTCTRL_H_