include/wx/palmos/listctrl.h

   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$
   8 // Copyright:   (c) William Osborne
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_LISTCTRL_H_
  13 #define _WX_LISTCTRL_H_
  14
  15 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
  16     #pragma interface "listctrl.h"
  17 #endif
  18
  19 #if wxUSE_LISTCTRL
  20
  21 #include "wx/control.h"
  22 #include "wx/event.h"
  23 #include "wx/hash.h"
  24 #include "wx/textctrl.h"
  25
  26
  27 class WXDLLEXPORT wxImageList;
  28
  29 /*
  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
  38
  39     You can change the style dynamically, either with SetSingleStyle or
  40     SetWindowStyleFlag.
  41
  42     Further window styles:
  43
  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)
  54
  55     Items are referred to by their index (position in the list starting from zero).
  56
  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).
  60
  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.
  65
  66     Notifications are passed via the wxWidgets 2.0 event system, or using virtual
  67     functions in wxWidgets 1.66.
  68
  69     See the sample wxListCtrl app for API usage.
  70
  71     TODO:
  72      - addition of further convenience functions
  73        to avoid use of wxListItem in some functions
  74      - state/overlay images: probably not needed.
  75      - testing of whole API, extending current sample.
  76
  77
  78  */
  79
  80 class WXDLLEXPORT wxListCtrl: public wxControl
  81 {
  82 public:
  83     /*
  84      * Public interface
  85      */
  86
  87     wxListCtrl() { Init(); }
  88
  89     wxListCtrl(wxWindow *parent,
  90                wxWindowID id = wxID_ANY,
  91                const wxPoint& pos = wxDefaultPosition,
  92                const wxSize& size = wxDefaultSize,
  93                long style = wxLC_ICON,
  94                const wxValidator& validator = wxDefaultValidator,
  95                const wxString& name = wxListCtrlNameStr)
  96     {
  97         Init();
  98
  99         Create(parent, id, pos, size, style, validator, name);
 100     }
 101
 102     virtual ~wxListCtrl();
 103
 104     bool Create(wxWindow *parent,
 105                 wxWindowID id = wxID_ANY,
 106                 const wxPoint& pos = wxDefaultPosition,
 107                 const wxSize& size = wxDefaultSize,
 108                 long style = wxLC_ICON,
 109                 const wxValidator& validator = wxDefaultValidator,
 110                 const wxString& name = wxListCtrlNameStr);
 111
 112
 113     // Attributes
 114     ////////////////////////////////////////////////////////////////////////////
 115
 116     // Set the control colours
 117     bool SetForegroundColour(const wxColour& col);
 118     bool SetBackgroundColour(const wxColour& col);
 119
 120     // Gets information about this column
 121     bool GetColumn(int col, wxListItem& item) const;
 122
 123     // Sets information about this column
 124     bool SetColumn(int col, wxListItem& item) ;
 125
 126     // Gets the column width
 127     int GetColumnWidth(int col) const;
 128
 129     // Sets the column width
 130     bool SetColumnWidth(int col, int width) ;
 131
 132     // Gets the number of items that can fit vertically in the
 133     // visible area of the list control (list or report view)
 134     // or the total number of items in the list control (icon
 135     // or small icon view)
 136     int GetCountPerPage() const;
 137
 138     // return the total area occupied by all the items (icon/small icon only)
 139     wxRect GetViewRect() const;
 140
 141     // Gets the edit control for editing labels.
 142     wxTextCtrl* GetEditControl() const;
 143
 144     // Gets information about the item
 145     bool GetItem(wxListItem& info) const ;
 146
 147     // Sets information about the item
 148     bool SetItem(wxListItem& info) ;
 149
 150     // Sets a string field at a particular column
 151     long SetItem(long index, int col, const wxString& label, int imageId = -1);
 152
 153     // Gets the item state
 154     int  GetItemState(long item, long stateMask) const ;
 155
 156     // Sets the item state
 157     bool SetItemState(long item, long state, long stateMask) ;
 158
 159     // Sets the item image
 160     bool SetItemImage(long item, int image, int selImage) ;
 161
 162     // Gets the item text
 163     wxString GetItemText(long item) const ;
 164
 165     // Sets the item text
 166     void SetItemText(long item, const wxString& str) ;
 167
 168     // Gets the item data
 169     long GetItemData(long item) const ;
 170
 171     // Sets the item data
 172     bool SetItemData(long item, long data) ;
 173
 174     // Gets the item rectangle
 175     bool GetItemRect(long item, 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
 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     // Gets the number of selected items in the list control
 201     int GetSelectedItemCount() const;
 202
 203     // Gets the text colour of the listview
 204     wxColour GetTextColour() const;
 205
 206     // Sets the text colour of the listview
 207     void SetTextColour(const wxColour& col);
 208
 209     // Gets the index of the topmost visible item when in
 210     // list or report view
 211     long GetTopItem() const ;
 212
 213     // Add or remove a single window style
 214     void SetSingleStyle(long style, bool add = true) ;
 215
 216     // Set the whole window style
 217     void SetWindowStyleFlag(long style) ;
 218
 219     // Searches for an item, starting from 'item'.
 220     // item can be -1 to find the first item that matches the
 221     // specified flags.
 222     // Returns the item or -1 if unsuccessful.
 223     long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const ;
 224
 225     // Gets one of the three image lists
 226     wxImageList *GetImageList(int which) const ;
 227
 228     // Sets the image list
 229     void SetImageList(wxImageList *imageList, int which) ;
 230     void AssignImageList(wxImageList *imageList, int which) ;
 231
 232     // are we in report mode?
 233     bool InReportView() const { return HasFlag(wxLC_REPORT); }
 234
 235     // are we in virtual report mode?
 236     bool IsVirtual() const { return HasFlag(wxLC_VIRTUAL); }
 237
 238     // refresh items selectively (only useful for virtual list controls)
 239     void RefreshItem(long item);
 240     void RefreshItems(long itemFrom, long itemTo);
 241
 242     // Operations
 243     ////////////////////////////////////////////////////////////////////////////
 244
 245     // Arranges the items
 246     bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
 247
 248     // Deletes an item
 249     bool DeleteItem(long item);
 250
 251     // Deletes all items
 252     bool DeleteAllItems() ;
 253
 254     // Deletes a column
 255     bool DeleteColumn(int col);
 256
 257     // Deletes all columns
 258     bool DeleteAllColumns();
 259
 260     // Clears items, and columns if there are any.
 261     void ClearAll();
 262
 263     // Edit the label
 264     wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl));
 265
 266     // End label editing, optionally cancelling the edit
 267     bool EndEditLabel(bool cancel);
 268
 269     // Ensures this item is visible
 270     bool EnsureVisible(long item) ;
 271
 272     // Find an item whose label matches this string, starting from the item after 'start'
 273     // or the beginning if 'start' is -1.
 274     long FindItem(long start, const wxString& str, bool partial = false);
 275
 276     // Find an item whose data matches this data, starting from the item after 'start'
 277     // or the beginning if 'start' is -1.
 278     long FindItem(long start, long data);
 279
 280     // Find an item nearest this position in the specified direction, starting from
 281     // the item after 'start' or the beginning if 'start' is -1.
 282     long FindItem(long start, const wxPoint& pt, int direction);
 283
 284     // Determines which item (if any) is at the specified point,
 285     // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
 286     long HitTest(const wxPoint& point, int& flags);
 287
 288     // Inserts an item, returning the index of the new item if successful,
 289     // -1 otherwise.
 290     long InsertItem(wxListItem& info);
 291
 292     // Insert a string item
 293     long InsertItem(long index, const wxString& label);
 294
 295     // Insert an image item
 296     long InsertItem(long index, int imageIndex);
 297
 298     // Insert an image/string item
 299     long InsertItem(long index, const wxString& label, int imageIndex);
 300
 301     // For list view mode (only), inserts a column.
 302     long InsertColumn(long col, wxListItem& info);
 303
 304     long InsertColumn(long col,
 305                       const wxString& heading,
 306                       int format = wxLIST_FORMAT_LEFT,
 307                       int width = -1);
 308
 309     // set the number of items in a virtual list control
 310     void SetItemCount(long count);
 311
 312     // Scrolls the list control. If in icon, small icon or report view mode,
 313     // x specifies the number of pixels to scroll. If in list view mode, x
 314     // specifies the number of columns to scroll.
 315     // If in icon, small icon or list view mode, y specifies the number of pixels
 316     // to scroll. If in report view mode, y specifies the number of lines to scroll.
 317     bool ScrollList(int dx, int dy);
 318
 319     // Sort items.
 320
 321     // fn is a function which takes 3 long arguments: item1, item2, data.
 322     // item1 is the long data associated with a first item (NOT the index).
 323     // item2 is the long data associated with a second item (NOT the index).
 324     // data is the same value as passed to SortItems.
 325     // The return value is a negative number if the first item should precede the second
 326     // item, a positive number of the second item should precede the first,
 327     // or zero if the two items are equivalent.
 328
 329     // data is arbitrary data to be passed to the sort function.
 330     bool SortItems(wxListCtrlCompare fn, long data);
 331
 332     // bring the control in sync with current m_windowStyle value
 333     void UpdateStyle();
 334
 335     // Event handlers
 336     ////////////////////////////////////////////////////////////////////////////
 337     // Necessary for drawing hrules and vrules, if specified
 338     void OnPaint(wxPaintEvent& event);
 339
 340
 341     virtual bool ShouldInheritColours() const { return false; }
 342
 343     virtual wxVisualAttributes GetDefaultAttributes() const
 344     {
 345         return GetClassDefaultAttributes(GetWindowVariant());
 346     }
 347
 348     static wxVisualAttributes
 349     GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
 350
 351
 352     // obsolete stuff, for compatibility only -- don't use
 353     wxDEPRECATED( int GetItemSpacing(bool isSmall) const);
 354
 355 protected:
 356     // common part of all ctors
 357     void Init();
 358
 359     // free memory taken by all internal data
 360     void FreeAllInternalData();
 361
 362     wxTextCtrl*       m_textCtrl;        // The control used for editing a label
 363     wxImageList *     m_imageListNormal; // The image list for normal icons
 364     wxImageList *     m_imageListSmall;  // The image list for small icons
 365     wxImageList *     m_imageListState;  // The image list state icons (not implemented yet)
 366     bool              m_ownsImageListNormal,
 367                       m_ownsImageListSmall,
 368                       m_ownsImageListState;
 369
 370     int               m_colCount;   // Windows doesn't have GetColumnCount so must
 371                                     // keep track of inserted/deleted columns
 372     long              m_count;      // Keep track of item count to save calls to
 373                                     // ListView_GetItemCount
 374     bool              m_ignoreChangeMessages;
 375
 376     // true if we have any internal data (user data & attributes)
 377     bool m_AnyInternalData;
 378
 379     // true if we have any items with custom attributes
 380     bool m_hasAnyAttr;
 381
 382     // these functions are only used for virtual list view controls, i.e. the
 383     // ones with wxLC_VIRTUAL style
 384
 385     // return the text for the given column of the given item
 386     virtual wxString OnGetItemText(long item, long column) const;
 387
 388     // return the icon for the given item
 389     virtual int OnGetItemImage(long item) const;
 390
 391     // return the attribute for the item (may return NULL if none)
 392     virtual wxListItemAttr *OnGetItemAttr(long item) const;
 393
 394 private:
 395
 396     DECLARE_DYNAMIC_CLASS(wxListCtrl)
 397     DECLARE_EVENT_TABLE()
 398     DECLARE_NO_COPY_CLASS(wxListCtrl)
 399 };
 400
 401 #endif // wxUSE_LISTCTRL
 402
 403 #endif // _WX_LISTCTRL_H_