1///////////////////////////////////////////////////////////////////////////// 2// Name: wx/palmos/listctrl.h 3// Purpose: wxListCtrl class 4// Author: William Osborne - minimal working wxPalmOS port 5// Modified by: 6// Created: 10/13/04 7// RCS-ID: $Id: listctrl.h 37982 2006-03-10 21:26:59Z RD $ 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 23class WXDLLEXPORT 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 76class WXDLLEXPORT wxListCtrl: public wxControl 77{ 78public: 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 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 item position 175 bool GetItemPosition(long item, wxPoint& pos) const ; 176 177 // Sets the item position 178 bool SetItemPosition(long item, const wxPoint& pos) ; 179 180 // Gets the number of items in the list control 181 int GetItemCount() const; 182 183 // Gets the number of columns in the list control 184 int GetColumnCount() const { return m_colCount; } 185 186 // get the horizontal and vertical components of the item spacing 187 wxSize GetItemSpacing() const; 188 189 // Foreground colour of an item. 190 void SetItemTextColour( long item, const wxColour& col); 191 wxColour GetItemTextColour( long item ) const; 192 193 // Background colour of an item. 194 void SetItemBackgroundColour( long item, const wxColour &col); 195 wxColour GetItemBackgroundColour( long item ) const; 196 197 // Gets the number of selected items in the list control 198 int GetSelectedItemCount() const; 199 200 // Gets the text colour of the listview 201 wxColour GetTextColour() const; 202 203 // Sets the text colour of the listview 204 void SetTextColour(const wxColour& col); 205 206 // Gets the index of the topmost visible item when in 207 // list or report view 208 long GetTopItem() const ; 209 210 // Add or remove a single window style 211 void SetSingleStyle(long style, bool add = true) ; 212 213 // Searches for an item, starting from 'item'. 214 // item can be -1 to find the first item that matches the 215 // specified flags. 216 // Returns the item or -1 if unsuccessful. 217 long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const ; 218 219 // Gets one of the three image lists 220 wxImageList *GetImageList(int which) const ; 221 222 // Sets the image list 223 void SetImageList(wxImageList *imageList, int which) ; 224 void AssignImageList(wxImageList *imageList, int which) ; 225 226 // are we in report mode? 227 bool InReportView() const { return HasFlag(wxLC_REPORT); } 228 229 // are we in virtual report mode? 230 bool IsVirtual() const { return HasFlag(wxLC_VIRTUAL); } 231 232 // refresh items selectively (only useful for virtual list controls) 233 void RefreshItem(long item); 234 void RefreshItems(long itemFrom, long itemTo); 235 236 // Operations 237 //////////////////////////////////////////////////////////////////////////// 238 239 // Arranges the items 240 bool Arrange(int flag = wxLIST_ALIGN_DEFAULT); 241 242 // Deletes an item 243 bool DeleteItem(long item); 244 245 // Deletes all items 246 bool DeleteAllItems() ; 247 248 // Deletes a column 249 bool DeleteColumn(int col); 250 251 // Deletes all columns 252 bool DeleteAllColumns(); 253 254 // Clears items, and columns if there are any. 255 void ClearAll(); 256 257 // Edit the label 258 wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl)); 259 260 // End label editing, optionally cancelling the edit 261 bool EndEditLabel(bool cancel); 262 263 // Ensures this item is visible 264 bool EnsureVisible(long item) ; 265 266 // Find an item whose label matches this string, starting from the item after 'start' 267 // or the beginning if 'start' is -1. 268 long FindItem(long start, const wxString& str, bool partial = false); 269 270 // Find an item whose data matches this data, starting from the item after 'start' 271 // or the beginning if 'start' is -1. 272 long FindItem(long start, long data); 273 274 // Find an item nearest this position in the specified direction, starting from 275 // the item after 'start' or the beginning if 'start' is -1. 276 long FindItem(long start, const wxPoint& pt, int direction); 277 278 // Determines which item (if any) is at the specified point, 279 // giving details in 'flags' (see wxLIST_HITTEST_... flags above) 280 long HitTest(const wxPoint& point, int& flags); 281 282 // Inserts an item, returning the index of the new item if successful, 283 // -1 otherwise. 284 long InsertItem(wxListItem& info); 285 286 // Insert a string item 287 long InsertItem(long index, const wxString& label); 288 289 // Insert an image item 290 long InsertItem(long index, int imageIndex); 291 292 // Insert an image/string item 293 long InsertItem(long index, const wxString& label, int imageIndex); 294 295 // For list view mode (only), inserts a column. 296 long InsertColumn(long col, wxListItem& info); 297 298 long InsertColumn(long col, 299 const wxString& heading, 300 int format = wxLIST_FORMAT_LEFT, 301 int width = -1); 302 303 // set the number of items in a virtual list control 304 void SetItemCount(long count); 305 306 // Scrolls the list control. If in icon, small icon or report view mode, 307 // x specifies the number of pixels to scroll. If in list view mode, x 308 // specifies the number of columns to scroll. 309 // If in icon, small icon or list view mode, y specifies the number of pixels 310 // to scroll. If in report view mode, y specifies the number of lines to scroll. 311 bool ScrollList(int dx, int dy); 312 313 // Sort items. 314 315 // fn is a function which takes 3 long arguments: item1, item2, data. 316 // item1 is the long data associated with a first item (NOT the index). 317 // item2 is the long data associated with a second item (NOT the index). 318 // data is the same value as passed to SortItems. 319 // The return value is a negative number if the first item should precede the second 320 // item, a positive number of the second item should precede the first, 321 // or zero if the two items are equivalent. 322 323 // data is arbitrary data to be passed to the sort function. 324 bool SortItems(wxListCtrlCompare fn, long data); 325 326 // bring the control in sync with current m_windowStyle value 327 void UpdateStyle(); 328 329 // Event handlers 330 //////////////////////////////////////////////////////////////////////////// 331 // Necessary for drawing hrules and vrules, if specified 332 void OnPaint(wxPaintEvent& event); 333 334 335 virtual bool ShouldInheritColours() const { return false; } 336 337 virtual wxVisualAttributes GetDefaultAttributes() const 338 { 339 return GetClassDefaultAttributes(GetWindowVariant()); 340 } 341 342 static wxVisualAttributes 343 GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); 344 345protected: 346 // common part of all ctors 347 void Init(); 348 349 // free memory taken by all internal data 350 void FreeAllInternalData(); 351 352 wxTextCtrl* m_textCtrl; // The control used for editing a label 353 wxImageList * m_imageListNormal; // The image list for normal icons 354 wxImageList * m_imageListSmall; // The image list for small icons 355 wxImageList * m_imageListState; // The image list state icons (not implemented yet) 356 bool m_ownsImageListNormal, 357 m_ownsImageListSmall, 358 m_ownsImageListState; 359 360 int m_colCount; // Windows doesn't have GetColumnCount so must 361 // keep track of inserted/deleted columns 362 long m_count; // Keep track of item count to save calls to 363 // ListView_GetItemCount 364 bool m_ignoreChangeMessages; 365 366 // true if we have any internal data (user data & attributes) 367 bool m_AnyInternalData; 368 369 // true if we have any items with custom attributes 370 bool m_hasAnyAttr; 371 372 // these functions are only used for virtual list view controls, i.e. the 373 // ones with wxLC_VIRTUAL style 374 375 // return the text for the given column of the given item 376 virtual wxString OnGetItemText(long item, long column) const; 377 378 // return the text for the given column of the given item 379 virtual wxString OnGetItemText(long item, long column) const; 380 381 // return the icon for the given item. In report view, OnGetItemImage will 382 // only be called for the first column. See OnGetItemColumnImage for 383 // details. 384 virtual int OnGetItemImage(long item) const; 385 386 // return the attribute for the item (may return NULL if none) 387 virtual wxListItemAttr *OnGetItemAttr(long item) const; 388 389private: 390 391 DECLARE_DYNAMIC_CLASS(wxListCtrl) 392 DECLARE_EVENT_TABLE() 393 DECLARE_NO_COPY_CLASS(wxListCtrl) 394}; 395 396#endif // wxUSE_LISTCTRL 397 398#endif // _WX_LISTCTRL_H_ 399