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