1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: wx/msw/listctrl.h 3 // Purpose: wxListCtrl class 4 // Author: Julian Smart 5 // Modified by: Agron Selimaj 6 // Created: 01/02/97 7 // RCS-ID: $Id: listctrl.h 54419 2008-06-29 01:35:24Z VZ $ 8 // Copyright: (c) Julian Smart 9 // Licence: wxWindows licence 10 ///////////////////////////////////////////////////////////////////////////// 11 12 #ifndef _WX_LISTCTRL_H_ 13 #define _WX_LISTCTRL_H_ 14 15 #include "wx/textctrl.h" 16 17 class WXDLLIMPEXP_FWD_CORE wxImageList; 18 19 /* 20 The wxListCtrl can show lists of items in four different modes: 21 wxLC_LIST: multicolumn list view, with optional small icons (icons could be 22 optional for some platforms). Columns are computed automatically, 23 i.e. you don't set columns as in wxLC_REPORT. In other words, 24 the list wraps, unlike a wxListBox. 25 wxLC_REPORT: single or multicolumn report view (with optional header) 26 wxLC_ICON: large icon view, with optional labels 27 wxLC_SMALL_ICON: small icon view, with optional labels 28 29 You can change the style dynamically, either with SetSingleStyle or 30 SetWindowStyleFlag. 31 32 Further window styles: 33 34 wxLC_ALIGN_TOP icons align to the top (default) 35 wxLC_ALIGN_LEFT icons align to the left 36 wxLC_AUTOARRANGE icons arrange themselves 37 wxLC_USER_TEXT the app provides label text on demand, except for column headers 38 wxLC_EDIT_LABELS labels are editable: app will be notified. 39 wxLC_NO_HEADER no header in report mode 40 wxLC_NO_SORT_HEADER can't click on header 41 wxLC_SINGLE_SEL single selection 42 wxLC_SORT_ASCENDING sort ascending (must still supply a comparison callback in SortItems) 43 wxLC_SORT_DESCENDING sort descending (ditto) 44 45 Items are referred to by their index (position in the list starting from zero). 46 47 Label text is supplied via insertion/setting functions and is stored by the 48 control, unless the wxLC_USER_TEXT style has been specified, in which case 49 the app will be notified when text is required (see sample). 50 51 Images are dealt with by (optionally) associating 3 image lists with the control. 52 Zero-based indexes into these image lists indicate which image is to be used for 53 which item. Each image in an image list can contain a mask, and can be made out 54 of either a bitmap, two bitmaps or an icon. See ImagList.h for more details. 55 56 Notifications are passed via the wxWidgets 2.0 event system, or using virtual 57 functions in wxWidgets 1.66. 58 59 See the sample wxListCtrl app for API usage. 60 61 TODO: 62 - addition of further convenience functions 63 to avoid use of wxListItem in some functions 64 - state/overlay images: probably not needed. 65 - in Win95, you can be called back to supply other information 66 besides text, such as state information. This saves no memory 67 and is probably superfluous to requirements. 68 - testing of whole API, extending current sample. 69 70 71 */ 72 73 class WXDLLEXPORT wxListCtrl: public wxControl 74 { 75 public: 76 /* 77 * Public interface 78 */ 79 wxListCtrl()80 wxListCtrl() { Init(); } 81 82 wxListCtrl(wxWindow *parent, 83 wxWindowID id = wxID_ANY, 84 const wxPoint& pos = wxDefaultPosition, 85 const wxSize& size = wxDefaultSize, 86 long style = wxLC_ICON, 87 const wxValidator& validator = wxDefaultValidator, 88 const wxString& name = wxListCtrlNameStr) 89 { 90 Init(); 91 92 Create(parent, id, pos, size, style, validator, name); 93 } 94 95 virtual ~wxListCtrl(); 96 97 bool Create(wxWindow *parent, 98 wxWindowID id = wxID_ANY, 99 const wxPoint& pos = wxDefaultPosition, 100 const wxSize& size = wxDefaultSize, 101 long style = wxLC_ICON, 102 const wxValidator& validator = wxDefaultValidator, 103 const wxString& name = wxListCtrlNameStr); 104 105 106 // Attributes 107 //////////////////////////////////////////////////////////////////////////// 108 109 // Set the control colours 110 bool SetForegroundColour(const wxColour& col); 111 bool SetBackgroundColour(const wxColour& col); 112 113 // Gets information about this column 114 bool GetColumn(int col, wxListItem& item) const; 115 116 // Sets information about this column 117 bool SetColumn(int col, const wxListItem& item) ; 118 119 // Gets the column width 120 int GetColumnWidth(int col) const; 121 122 // Sets the column width 123 bool SetColumnWidth(int col, int width) ; 124 125 // Gets the number of items that can fit vertically in the 126 // visible area of the list control (list or report view) 127 // or the total number of items in the list control (icon 128 // or small icon view) 129 int GetCountPerPage() const; 130 131 // return the total area occupied by all the items (icon/small icon only) 132 wxRect GetViewRect() const; 133 134 // Gets the edit control for editing labels. 135 wxTextCtrl* GetEditControl() const; 136 137 // Gets information about the item 138 bool GetItem(wxListItem& info) const ; 139 140 // Sets information about the item 141 bool SetItem(wxListItem& info) ; 142 143 // Sets a string field at a particular column 144 long SetItem(long index, int col, const wxString& label, int imageId = -1); 145 146 // Gets the item state 147 int GetItemState(long item, long stateMask) const ; 148 149 // Sets the item state 150 bool SetItemState(long item, long state, long stateMask) ; 151 152 // Sets the item image 153 bool SetItemImage(long item, int image, int selImage = -1) ; 154 bool SetItemColumnImage(long item, long column, int image); 155 156 // Gets the item text 157 wxString GetItemText(long item) const ; 158 159 // Sets the item text 160 void SetItemText(long item, const wxString& str) ; 161 162 // Gets the item data 163 wxUIntPtr GetItemData(long item) const ; 164 165 // Sets the item data 166 #if wxABI_VERSION >= 20804 167 bool SetItemPtrData(long item, wxUIntPtr data); 168 #endif // wxABI 2.8.4+ 169 bool SetItemData(long item, long data); 170 171 // Gets the item rectangle 172 bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ; 173 174 // Gets the subitem rectangle in report mode 175 bool GetSubItemRect(long item, long subItem, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ; 176 177 // Gets the item position 178 bool GetItemPosition(long item, wxPoint& pos) const ; 179 180 // Sets the item position 181 bool SetItemPosition(long item, const wxPoint& pos) ; 182 183 // Gets the number of items in the list control 184 int GetItemCount() const; 185 186 // Gets the number of columns in the list control GetColumnCount()187 int GetColumnCount() const { return m_colCount; } 188 189 // get the horizontal and vertical components of the item spacing 190 wxSize GetItemSpacing() const; 191 192 // Foreground colour of an item. 193 void SetItemTextColour( long item, const wxColour& col); 194 wxColour GetItemTextColour( long item ) const; 195 196 // Background colour of an item. 197 void SetItemBackgroundColour( long item, const wxColour &col); 198 wxColour GetItemBackgroundColour( long item ) const; 199 200 // Font of an item. 201 void SetItemFont( long item, const wxFont &f); 202 wxFont GetItemFont( long item ) const; 203 204 // Gets the number of selected items in the list control 205 int GetSelectedItemCount() const; 206 207 // Gets the text colour of the listview 208 wxColour GetTextColour() const; 209 210 // Sets the text colour of the listview 211 void SetTextColour(const wxColour& col); 212 213 // Gets the index of the topmost visible item when in 214 // list or report view 215 long GetTopItem() const ; 216 217 // Add or remove a single window style 218 void SetSingleStyle(long style, bool add = true) ; 219 220 // Set the whole window style 221 void SetWindowStyleFlag(long style) ; 222 223 // Searches for an item, starting from 'item'. 224 // item can be -1 to find the first item that matches the 225 // specified flags. 226 // Returns the item or -1 if unsuccessful. 227 long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const ; 228 229 // Gets one of the three image lists 230 wxImageList *GetImageList(int which) const ; 231 232 // Sets the image list 233 // N.B. There's a quirk in the Win95 list view implementation. 234 // If in wxLC_LIST mode, it'll *still* display images by the labels if 235 // there's a small-icon image list set for the control - even though you 236 // haven't specified wxLIST_MASK_IMAGE when inserting. 237 // So you have to set a NULL small-icon image list to be sure that 238 // the wxLC_LIST mode works without icons. Of course, you may want icons... 239 void SetImageList(wxImageList *imageList, int which) ; 240 void AssignImageList(wxImageList *imageList, int which) ; 241 242 // are we in report mode? InReportView()243 bool InReportView() const { return HasFlag(wxLC_REPORT); } 244 245 // are we in virtual report mode? IsVirtual()246 bool IsVirtual() const { return HasFlag(wxLC_VIRTUAL); } 247 248 // refresh items selectively (only useful for virtual list controls) 249 void RefreshItem(long item); 250 void RefreshItems(long itemFrom, long itemTo); 251 252 // Operations 253 //////////////////////////////////////////////////////////////////////////// 254 255 // Arranges the items 256 bool Arrange(int flag = wxLIST_ALIGN_DEFAULT); 257 258 // Deletes an item 259 bool DeleteItem(long item); 260 261 // Deletes all items 262 bool DeleteAllItems() ; 263 264 // Deletes a column 265 bool DeleteColumn(int col); 266 267 // Deletes all columns 268 bool DeleteAllColumns(); 269 270 // Clears items, and columns if there are any. 271 void ClearAll(); 272 273 // Edit the label 274 wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl)); 275 276 // End label editing, optionally cancelling the edit 277 bool EndEditLabel(bool cancel); 278 279 // Ensures this item is visible 280 bool EnsureVisible(long item) ; 281 282 // Find an item whose label matches this string, starting from the item after 'start' 283 // or the beginning if 'start' is -1. 284 long FindItem(long start, const wxString& str, bool partial = false); 285 286 // Find an item whose data matches this data, starting from the item after 'start' 287 // or the beginning if 'start' is -1. 288 long FindItem(long start, wxUIntPtr data); 289 290 // Find an item nearest this position in the specified direction, starting from 291 // the item after 'start' or the beginning if 'start' is -1. 292 long FindItem(long start, const wxPoint& pt, int direction); 293 294 // Determines which item (if any) is at the specified point, 295 // giving details in 'flags' (see wxLIST_HITTEST_... flags above) 296 // Request the subitem number as well at the given coordinate. 297 long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const; 298 299 // Inserts an item, returning the index of the new item if successful, 300 // -1 otherwise. 301 long InsertItem(const wxListItem& info); 302 303 // Insert a string item 304 long InsertItem(long index, const wxString& label); 305 306 // Insert an image item 307 long InsertItem(long index, int imageIndex); 308 309 // Insert an image/string item 310 long InsertItem(long index, const wxString& label, int imageIndex); 311 312 // For list view mode (only), inserts a column. 313 long InsertColumn(long col, const wxListItem& info); 314 315 long InsertColumn(long col, 316 const wxString& heading, 317 int format = wxLIST_FORMAT_LEFT, 318 int width = -1); 319 320 // set the number of items in a virtual list control 321 void SetItemCount(long count); 322 323 // Scrolls the list control. If in icon, small icon or report view mode, 324 // x specifies the number of pixels to scroll. If in list view mode, x 325 // specifies the number of columns to scroll. 326 // If in icon, small icon or list view mode, y specifies the number of pixels 327 // to scroll. If in report view mode, y specifies the number of lines to scroll. 328 bool ScrollList(int dx, int dy); 329 330 // Sort items. 331 332 // fn is a function which takes 3 long arguments: item1, item2, data. 333 // item1 is the long data associated with a first item (NOT the index). 334 // item2 is the long data associated with a second item (NOT the index). 335 // data is the same value as passed to SortItems. 336 // The return value is a negative number if the first item should precede the second 337 // item, a positive number of the second item should precede the first, 338 // or zero if the two items are equivalent. 339 340 // data is arbitrary data to be passed to the sort function. 341 bool SortItems(wxListCtrlCompare fn, long data); 342 343 // IMPLEMENTATION 344 virtual bool MSWCommand(WXUINT param, WXWORD id); 345 virtual bool MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result); 346 virtual bool MSWShouldPreProcessMessage(WXMSG* msg); 347 348 // bring the control in sync with current m_windowStyle value 349 void UpdateStyle(); 350 351 // Event handlers 352 //////////////////////////////////////////////////////////////////////////// 353 // Necessary for drawing hrules and vrules, if specified 354 void OnPaint(wxPaintEvent& event); 355 356 ShouldInheritColours()357 virtual bool ShouldInheritColours() const { return false; } 358 GetDefaultAttributes()359 virtual wxVisualAttributes GetDefaultAttributes() const 360 { 361 return GetClassDefaultAttributes(GetWindowVariant()); 362 } 363 364 static wxVisualAttributes 365 GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); 366 367 368 #if WXWIN_COMPATIBILITY_2_6 369 // obsolete stuff, for compatibility only -- don't use 370 wxDEPRECATED( int GetItemSpacing(bool isSmall) const); 371 #endif // WXWIN_COMPATIBILITY_2_6 372 373 // convert our styles to Windows 374 virtual WXDWORD MSWGetStyle(long style, WXDWORD *exstyle) const; 375 376 // special Windows message handling 377 virtual WXLRESULT MSWWindowProc(WXUINT nMsg, 378 WXWPARAM wParam, 379 WXLPARAM lParam); 380 381 protected: 382 // common part of all ctors 383 void Init(); 384 385 // free memory taken by all internal data 386 void FreeAllInternalData(); 387 388 // get the item attribute, either by quering it for virtual control, or by 389 // returning the one previously set using setter methods for a normal one 390 wxListItemAttr *DoGetItemAttr(long item) const; 391 392 393 wxTextCtrl* m_textCtrl; // The control used for editing a label 394 wxImageList * m_imageListNormal; // The image list for normal icons 395 wxImageList * m_imageListSmall; // The image list for small icons 396 wxImageList * m_imageListState; // The image list state icons (not implemented yet) 397 bool m_ownsImageListNormal, 398 m_ownsImageListSmall, 399 m_ownsImageListState; 400 401 int m_colCount; // Windows doesn't have GetColumnCount so must 402 // keep track of inserted/deleted columns 403 long m_count; // Keep track of item count to save calls to 404 // ListView_GetItemCount 405 bool m_ignoreChangeMessages; 406 407 // true if we have any internal data (user data & attributes) 408 bool m_AnyInternalData; 409 410 // true if we have any items with custom attributes 411 bool m_hasAnyAttr; 412 413 // these functions are only used for virtual list view controls, i.e. the 414 // ones with wxLC_VIRTUAL style 415 416 // return the text for the given column of the given item 417 virtual wxString OnGetItemText(long item, long column) const; 418 419 // return the icon for the given item. In report view, OnGetItemImage will 420 // only be called for the first column. See OnGetItemColumnImage for 421 // details. 422 virtual int OnGetItemImage(long item) const; 423 424 // return the icon for the given item and column. 425 virtual int OnGetItemColumnImage(long item, long column) const; 426 427 // return the attribute for the item (may return NULL if none) 428 virtual wxListItemAttr *OnGetItemAttr(long item) const; 429 430 private: 431 // process NM_CUSTOMDRAW notification message 432 WXLPARAM OnCustomDraw(WXLPARAM lParam); 433 434 // set the extended styles for the control (used by Create() and 435 // UpdateStyle()), only should be called if InReportView() 436 void MSWSetExListStyles(); 437 438 // initialize the (already created) m_textCtrl with the associated HWND 439 void InitEditControl(WXHWND hWnd); 440 441 // destroy m_textCtrl if it's currently valid and reset it to NULL 442 void DeleteEditControl(); 443 444 DECLARE_DYNAMIC_CLASS(wxListCtrl) 445 DECLARE_EVENT_TABLE() 446 DECLARE_NO_COPY_CLASS(wxListCtrl) 447 }; 448 449 #endif // _WX_LISTCTRL_H_ 450