1///////////////////////////////////////////////////////////////////////////// 2// Name: listctrl.h 3// Purpose: wxListCtrl class 4// Author: Stefan Csomor 5// Modified by: 6// Created: 1998-01-01 7// RCS-ID: $Id: listctrl.h 41020 2006-09-05 20:47:48Z VZ $ 8// Copyright: (c) Stefan Csomor 9// Licence: wxWindows licence 10///////////////////////////////////////////////////////////////////////////// 11 12#ifndef _WX_LISTCTRL_H_ 13#define _WX_LISTCTRL_H_ 14 15#include "wx/control.h" 16#include "wx/event.h" 17#include "wx/imaglist.h" 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. 57 58 See the sample wxListCtrl app for API usage. 59 60 */ 61 62// Mask flags to tell app/GUI what fields of wxListItem are valid 63#define wxLIST_MASK_STATE 0x0001 64#define wxLIST_MASK_TEXT 0x0002 65#define wxLIST_MASK_IMAGE 0x0004 66#define wxLIST_MASK_DATA 0x0008 67#define wxLIST_SET_ITEM 0x0010 68#define wxLIST_MASK_WIDTH 0x0020 69#define wxLIST_MASK_FORMAT 0x0040 70 71// State flags for indicating the state of an item 72#define wxLIST_STATE_DONTCARE 0x0000 73#define wxLIST_STATE_DROPHILITED 0x0001 74#define wxLIST_STATE_FOCUSED 0x0002 75#define wxLIST_STATE_SELECTED 0x0004 76#define wxLIST_STATE_CUT 0x0008 77 78// Hit test flags, used in HitTest 79#define wxLIST_HITTEST_ABOVE 0x0001 // Above the client area. 80#define wxLIST_HITTEST_BELOW 0x0002 // Below the client area. 81#define wxLIST_HITTEST_NOWHERE 0x0004 // In the client area but below the last item. 82#define wxLIST_HITTEST_ONITEMICON 0x0020 // On the bitmap associated with an item. 83#define wxLIST_HITTEST_ONITEMLABEL 0x0080 // On the label (string) associated with an item. 84#define wxLIST_HITTEST_ONITEMRIGHT 0x0100 // In the area to the right of an item. 85#define wxLIST_HITTEST_ONITEMSTATEICON 0x0200 // On the state icon for a tree view item that is in a user-defined state. 86#define wxLIST_HITTEST_TOLEFT 0x0400 // To the left of the client area. 87#define wxLIST_HITTEST_TORIGHT 0x0800 // To the right of the client area. 88 89#define wxLIST_HITTEST_ONITEM (wxLIST_HITTEST_ONITEMICON | wxLIST_HITTEST_ONITEMLABEL wxLIST_HITTEST_ONITEMSTATEICON) 90 91// Flags for GetNextItem 92enum { 93 wxLIST_NEXT_ABOVE, // Searches for an item above the specified item 94 wxLIST_NEXT_ALL, // Searches for subsequent item by index 95 wxLIST_NEXT_BELOW, // Searches for an item below the specified item 96 wxLIST_NEXT_LEFT, // Searches for an item to the left of the specified item 97 wxLIST_NEXT_RIGHT, // Searches for an item to the right of the specified item 98}; 99 100// Alignment flags for Arrange 101enum { 102 wxLIST_ALIGN_DEFAULT, 103 wxLIST_ALIGN_LEFT, 104 wxLIST_ALIGN_TOP, 105 wxLIST_ALIGN_SNAP_TO_GRID 106}; 107 108// Column format 109enum { 110 wxLIST_FORMAT_LEFT, 111 wxLIST_FORMAT_RIGHT, 112 wxLIST_FORMAT_CENTRE, 113 wxLIST_FORMAT_CENTER = wxLIST_FORMAT_CENTRE 114}; 115 116// Autosize values for SetColumnWidth 117enum { 118 wxLIST_AUTOSIZE = -1, 119 wxLIST_AUTOSIZE_USEHEADER = -2 120}; 121 122// Flag values for GetItemRect 123enum { 124 wxLIST_RECT_BOUNDS, 125 wxLIST_RECT_ICON, 126 wxLIST_RECT_LABEL 127}; 128 129// Flag values for FindItem 130enum { 131 wxLIST_FIND_UP, 132 wxLIST_FIND_DOWN, 133 wxLIST_FIND_LEFT, 134 wxLIST_FIND_RIGHT 135}; 136 137// wxListItem: data representing an item, or report field. 138// It also doubles up to represent entire column information 139// when inserting or setting a column. 140class WXDLLEXPORT wxListItem: public wxObject 141{ 142 DECLARE_DYNAMIC_CLASS(wxListItem) 143public: 144 long m_mask; // Indicates what fields are valid 145 long m_itemId; // The zero-based item position 146 int m_col; // Zero-based column, if in report mode 147 long m_state; // The state of the item 148 long m_stateMask; // Which flags of m_state are valid (uses same flags) 149 wxString m_text; // The label/header text 150 int m_image; // The zero-based index into an image list 151 long m_data; // App-defined data 152 153 // For columns only 154 int m_format; // left, right, centre 155 int m_width; // width of column 156 157 wxListItem(); 158}; 159 160// type of compare function for wxListCtrl sort operation 161typedef int (*wxListCtrlCompare)(long item1, long item2, long sortData); 162 163class WXDLLEXPORT wxListCtrl: public wxControl 164{ 165 DECLARE_DYNAMIC_CLASS(wxListCtrl) 166 public: 167 /* 168 * Public interface 169 */ 170 171 wxListCtrl(); 172 173 inline wxListCtrl(wxWindow *parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, 174 long style = wxLC_ICON, const wxValidator& validator = wxDefaultValidator, 175 const wxString& name = wxListCtrlNameStr) 176 { 177 Create(parent, id, pos, size, style, validator, name); 178 } 179 virtual ~wxListCtrl(); 180 181 bool Create(wxWindow *parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, 182 long style = wxLC_ICON, const wxValidator& validator = wxDefaultValidator, const wxString& name = wxListCtrlNameStr); 183 184 185 // Attributes 186 //////////////////////////////////////////////////////////////////////////// 187 188 // Gets information about this column 189 bool GetColumn(int col, wxListItem& item) const; 190 191 // Sets information about this column 192 bool SetColumn(int col, wxListItem& item) ; 193 194 // Gets the column width 195 int GetColumnWidth(int col) const; 196 197 // Sets the column width 198 bool SetColumnWidth(int col, int width) ; 199 200 // Gets the number of items that can fit vertically in the 201 // visible area of the list control (list or report view) 202 // or the total number of items in the list control (icon 203 // or small icon view) 204 int GetCountPerPage() const; 205 206 // Gets the edit control for editing labels. 207 wxTextCtrl* GetEditControl() const; 208 209 // Gets information about the item 210 bool GetItem(wxListItem& info) const ; 211 212 // Sets information about the item 213 bool SetItem(wxListItem& info) ; 214 215 // Sets a string field at a particular column 216 long SetItem(long index, int col, const wxString& label, int imageId = -1); 217 218 // Gets the item state 219 int GetItemState(long item, long stateMask) const ; 220 221 // Sets the item state 222 bool SetItemState(long item, long state, long stateMask) ; 223 224 // Sets the item image 225 bool SetItemImage(long item, int image, int selImage) ; 226 bool SetItemColumnImage(long item, long column, int image); 227 228 // Gets the item text 229 wxString GetItemText(long item) const ; 230 231 // Sets the item text 232 void SetItemText(long item, const wxString& str) ; 233 234 // Gets the item data 235 long GetItemData(long item) const ; 236 237 // Sets the item data 238 bool SetItemData(long item, long data) ; 239 240 // Gets the item rectangle 241 bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ; 242 243 // Gets the item position 244 bool GetItemPosition(long item, wxPoint& pos) const ; 245 246 // Sets the item position 247 bool SetItemPosition(long item, const wxPoint& pos) ; 248 249 // Gets the number of items in the list control 250 int GetItemCount() const; 251 252 // Gets the number of columns in the list control 253 int GetColumnCount() const; 254 255 // Retrieves the spacing between icons in pixels. 256 // If isSmall is true, gets the spacing for the small icon 257 // view, otherwise the large icon view. 258 int GetItemSpacing(bool isSmall) const; 259 260 // Gets the number of selected items in the list control 261 int GetSelectedItemCount() const; 262 263 // Gets the text colour of the listview 264 wxColour GetTextColour() const; 265 266 // Sets the text colour of the listview 267 void SetTextColour(const wxColour& col); 268 269 // Gets the index of the topmost visible item when in 270 // list or report view 271 long GetTopItem() const ; 272 273 // Add or remove a single window style 274 void SetSingleStyle(long style, bool add = true) ; 275 276 // Set the whole window style 277 void SetWindowStyleFlag(long style) ; 278 279 // Searches for an item, starting from 'item'. 280 // item can be -1 to find the first item that matches the 281 // specified flags. 282 // Returns the item or -1 if unsuccessful. 283 long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const ; 284 285 // Implementation: converts wxWidgets style to MSW style. 286 // Can be a single style flag or a bit list. 287 // oldStyle is 'normalised' so that it doesn't contain 288 // conflicting styles. 289 long ConvertToMSWStyle(long& oldStyle, long style) const; 290 291 // Gets one of the three image lists 292 wxImageList *GetImageList(int which) const ; 293 294 // Sets the image list 295 // N.B. There's a quirk in the Win95 list view implementation. 296 // If in wxLC_LIST mode, it'll *still* display images by the labels if 297 // there's a small-icon image list set for the control - even though you 298 // haven't specified wxLIST_MASK_IMAGE when inserting. 299 // So you have to set a NULL small-icon image list to be sure that 300 // the wxLC_LIST mode works without icons. Of course, you may want icons... 301 void SetImageList(wxImageList *imageList, int which) ; 302 303 // Operations 304 //////////////////////////////////////////////////////////////////////////// 305 306 // Arranges the items 307 bool Arrange(int flag = wxLIST_ALIGN_DEFAULT); 308 309 // Deletes an item 310 bool DeleteItem(long item); 311 312 // Deletes all items 313 bool DeleteAllItems() ; 314 315 // Deletes a column 316 bool DeleteColumn(int col); 317 318 // Deletes all columns 319 bool DeleteAllColumns(); 320 321 // Clears items, and columns if there are any. 322 void ClearAll(); 323 324 // Edit the label 325 wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl)); 326 327 // End label editing, optionally cancelling the edit 328 bool EndEditLabel(bool cancel); 329 330 // Ensures this item is visible 331 bool EnsureVisible(long item) ; 332 333 // Find an item whose label matches this string, starting from the item after 'start' 334 // or the beginning if 'start' is -1. 335 long FindItem(long start, const wxString& str, bool partial = false); 336 337 // Find an item whose data matches this data, starting from the item after 'start' 338 // or the beginning if 'start' is -1. 339 long FindItem(long start, long data); 340 341 // Find an item nearest this position in the specified direction, starting from 342 // the item after 'start' or the beginning if 'start' is -1. 343 long FindItem(long start, const wxPoint& pt, int direction); 344 345 // Determines which item (if any) is at the specified point, 346 // giving details in 'flags' (see wxLIST_HITTEST_... flags above) 347 long HitTest(const wxPoint& point, int& flags); 348 349 // Inserts an item, returning the index of the new item if successful, 350 // -1 otherwise. 351 // TOD: Should also have some further convenience functions 352 // which don't require setting a wxListItem object 353 long InsertItem(wxListItem& info); 354 355 // Insert a string item 356 long InsertItem(long index, const wxString& label); 357 358 // Insert an image item 359 long InsertItem(long index, int imageIndex); 360 361 // Insert an image/string item 362 long InsertItem(long index, const wxString& label, int imageIndex); 363 364 // For list view mode (only), inserts a column. 365 long InsertColumn(long col, wxListItem& info); 366 367 long InsertColumn(long col, const wxString& heading, int format = wxLIST_FORMAT_LEFT, 368 int width = -1); 369 370 // Scrolls the list control. If in icon, small icon or report view mode, 371 // x specifies the number of pixels to scroll. If in list view mode, x 372 // specifies the number of columns to scroll. 373 // If in icon, small icon or list view mode, y specifies the number of pixels 374 // to scroll. If in report view mode, y specifies the number of lines to scroll. 375 bool ScrollList(int dx, int dy); 376 377 // Sort items. 378 379 // fn is a function which takes 3 long arguments: item1, item2, data. 380 // item1 is the long data associated with a first item (NOT the index). 381 // item2 is the long data associated with a second item (NOT the index). 382 // data is the same value as passed to SortItems. 383 // The return value is a negative number if the first item should precede the second 384 // item, a positive number of the second item should precede the first, 385 // or zero if the two items are equivalent. 386 387 // data is arbitrary data to be passed to the sort function. 388 bool SortItems(wxListCtrlCompare fn, long data); 389 390/* Why should we need this function? Leave for now. 391 * We might need it because item data may have changed, 392 * but the display needs refreshing (in string callback mode) 393 // Updates an item. If the list control has the wxLI_AUTO_ARRANGE style, 394 // the items will be rearranged. 395 bool Update(long item); 396*/ 397 398 void Command(wxCommandEvent& event) { ProcessCommand(event); }; 399 400protected: 401 wxTextCtrl* m_textCtrl; // The control used for editing a label 402 wxImageList * m_imageListNormal; // The image list for normal icons 403 wxImageList * m_imageListSmall; // The image list for small icons 404 wxImageList * m_imageListState; // The image list state icons (not implemented yet) 405 406 long m_baseStyle; // Basic Windows style flags, for recreation purposes 407 wxStringList m_stringPool; // Pool of 3 strings to satisfy Windows callback 408 // requirements 409 int m_colCount; // Windows doesn't have GetColumnCount so must 410 // keep track of inserted/deleted columns 411 412}; 413 414class WXDLLEXPORT wxListEvent: public wxCommandEvent 415{ 416 DECLARE_DYNAMIC_CLASS(wxListEvent) 417 418 public: 419 wxListEvent(wxEventType commandType = wxEVT_NULL, int id = 0); 420 421 int m_code; 422 long m_itemIndex; 423 long m_oldItemIndex; 424 int m_col; 425 bool m_cancelled; 426 wxPoint m_pointDrag; 427 428 wxListItem m_item; 429}; 430 431typedef void (wxEvtHandler::*wxListEventFunction)(wxListEvent&); 432 433#define EVT_LIST_BEGIN_DRAG(id, fn) { wxEVT_COMMAND_LIST_BEGIN_DRAG, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 434#define EVT_LIST_BEGIN_RDRAG(id, fn) { wxEVT_COMMAND_LIST_BEGIN_RDRAG, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 435#define EVT_LIST_BEGIN_LABEL_EDIT(id, fn) { wxEVT_COMMAND_LIST_BEGIN_LABEL_EDIT, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 436#define EVT_LIST_END_LABEL_EDIT(id, fn) { wxEVT_COMMAND_LIST_END_LABEL_EDIT, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 437#define EVT_LIST_DELETE_ITEM(id, fn) { wxEVT_COMMAND_LIST_DELETE_ITEM, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 438#define EVT_LIST_DELETE_ALL_ITEMS(id, fn) { wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 439#define EVT_LIST_GET_INFO(id, fn) { wxEVT_COMMAND_LIST_GET_INFO, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 440#define EVT_LIST_SET_INFO(id, fn) { wxEVT_COMMAND_LIST_SET_INFO, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 441#define EVT_LIST_ITEM_SELECTED(id, fn) { wxEVT_COMMAND_LIST_ITEM_SELECTED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 442#define EVT_LIST_ITEM_DESELECTED(id, fn) { wxEVT_COMMAND_LIST_ITEM_DESELECTED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 443#define EVT_LIST_KEY_DOWN(id, fn) { wxEVT_COMMAND_LIST_KEY_DOWN, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 444#define EVT_LIST_INSERT_ITEM(id, fn) { wxEVT_COMMAND_LIST_INSERT_ITEM, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 445#define EVT_LIST_COL_CLICK(id, fn) { wxEVT_COMMAND_LIST_COL_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL }, 446 447#endif 448 // _WX_LISTCTRL_H_ 449