added EVT_LIST_COMMAND_CACHE_HINT, implemented it for MSW and test in the sample; briefly documented virtual list control fucntionality

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@11114 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/changes.txt

@@ -1,15 +1,16 @@
 wxWindows 2 Change Log
 ----------------------
 
-2.3.3
+2.3.2
 -----
 
 wxBase:
 
 - wxRegEx class added
 
-2.3.2
+All (GUI):
------
+
+- support for virtual list control added
 
 2.3.1
 -----

docs/latex/wx/listctrl.tex

@@ -2,8 +2,21 @@
 
 A list control presents lists in a number of formats: list view, report view,
 icon view and small icon view. In any case, elements are numbered from zero.
+For all these modes, the items are stored in the control and must be added to
+it using \helpref{InsertItem}{wxlistctrlinsertitem} method.
 
-Using many of wxListCtrl is shown in the
+A special case of report view quite different from the other modes of the list
+control is a virtual control in which the items data (including text, images
+and attributes) is managed by the main program and is requested by the control
+itself only when needed which allows to have controls with millions of items
+without consuming much memory. To use virtual list control you must use 
+\helpref{SetItemCount}{wxlistctrlsetitemcount} first and overload at least 
+\helpref{OnGetItemText}{wxlistctrlongetitemtext} (and optionally 
+\helpref{OnGetItemImage}{wxlistctrlongetitemimage} and 
+\helpref{OnGetItemAttr}{wxlistctrlongetitemattr}) to return the information
+about the items when the control requests it.
+
+Using many of wxListCtrl features is shown in the
 \helpref{corresponding sample}{samplelistctrl}.
 
 To intercept events from a list control, use the event table macros described
@@ -28,6 +41,7 @@ in \helpref{wxListEvent}{wxlistevent}.
 Columns are computed automatically, i.e. you don't set columns as in wxLC\_REPORT. In other words,
 the list wraps, unlike a wxListBox.}
 \twocolitem{\windowstyle{wxLC\_REPORT}}{single or multicolumn report view, with optional header.}
+\twocolitem{\windowstyle{wxLC\_VIRTUAL}}{virtual control, may only be used with wxLC\_REPORT}
 \twocolitem{\windowstyle{wxLC\_ICON}}{Large icon view, with optional labels.}
 \twocolitem{\windowstyle{wxLC\_SMALL\_ICON}}{Small icon view, with optional labels.}
 \twocolitem{\windowstyle{wxLC\_ALIGN\_TOP}}{Icons align to the top. Win32 default, Win32 only. }
@@ -67,6 +81,7 @@ functions that take a \helpref{wxListEvent}{wxlistevent} argument.
 \twocolitem{{\bf EVT\_LIST\_INSERT\_ITEM(id, func)}}{An item has been inserted.}
 \twocolitem{{\bf EVT\_LIST\_COL\_CLICK(id, func)}}{A column ({\bf m\_col}) has been left-clicked.}
 \twocolitem{{\bf EVT\_LIST\_ITEM\_RIGHT\_CLICK(id, func)}}{An item has been right-clicked.}
+\twocolitem{{\bf EVT\_LIST\_CACHE\_HINT(id, func)}}{Prepare cache for a virtual list control}
 \end{twocollist}%
 
 \wxheading{See also}
@@ -527,6 +542,51 @@ method:\par
 \end{twocollist}
 }}
 
+\membersection{wxListCtrl::OnGetItemAttr}\label{wxlistctrlongetitemattr}
+
+\func{virtual wxString}{OnGetItemAttr}{\param{long }{item}}
+
+This function may be overloaded in the derived class for a control with 
+{\tt wxLC\_VIRTUAL} style. It should return the attribute for the
+for the specified {\tt item} or {\tt NULL} to use the default appearance
+parameters.
+
+The base class version always returns {\tt NULL}.
+
+\wxheading{See also}
+
+\helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
+\helpref{OnGetItemText}{wxlistctrlongetitemtext}
+
+\membersection{wxListCtrl::OnGetItemImage}\label{wxlistctrlongetitemimage}
+
+\func{virtual wxString}{OnGetItemImage}{\param{long }{item}}
+
+This function may be overloaded in the derived class for a control with 
+{\tt wxLC\_VIRTUAL} style. It should return the index of the items image in the
+controls image list or $-1$ for no image.
+
+The base class version always returns $-1$.
+
+\wxheading{See also}
+
+\helpref{OnGetItemText}{wxlistctrlongetitemtext},\\
+\helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
+
+\membersection{wxListCtrl::OnGetItemText}\label{wxlistctrlongetitemtext}
+
+\func{virtual wxString}{OnGetItemText}{\param{long }{item}, \param{long }{column}}
+
+This function {\bf must} be overloaded in the derived class for a control with 
+{\tt wxLC\_VIRTUAL} style. It should return the string containing the text of
+the given {\it column} for the specified {\tt item}.
+
+\wxheading{See also}
+
+\helpref{SetItemCount}{wxlistctrlsetitemcount},\\
+\helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
+\helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
+
 \membersection{wxListCtrl::ScrollList}\label{wxlistctrlscrolllist}
 
 \func{bool}{ScrollList}{\param{int }{dx}, \param{int }{dy}}
@@ -646,6 +706,16 @@ string or image at a given location.}
 \end{twocollist}}
 }
 
+\membersection{wxListCtrl::SetItemCount}\label{wxlistctrlsetitemcount}
+
+\func{void}{SetItemCount}{\param{long }{count}}
+
+This method can only be used with virtual list controls. It is used to indicate
+to the control the number of items it contains. After calling it, the main
+program should be ready to handle calls to various item callbacks (such as
+\helpref{OnGetItemText}{wxlistctrlongetitemtext}) for all vitems in the range
+from $0$ to {\it count}.
+
 \membersection{wxListCtrl::SetItemData}\label{wxlistctrlsetitemdata}
 
 \func{bool}{SetItemData}{\param{long }{item}, \param{long }{data}}

docs/latex/wx/listevt.tex

@@ -34,6 +34,7 @@ functions that take a wxListEvent argument.
 \twocolitem{{\bf EVT\_LIST\_KEY\_DOWN(id, func)}}{A key has been pressed.}
 \twocolitem{{\bf EVT\_LIST\_INSERT\_ITEM(id, func)}}{An item has been inserted.}
 \twocolitem{{\bf EVT\_LIST\_COL\_CLICK(id, func)}}{A column ({\bf m\_col}) has been left-clicked.}
+\twocolitem{{\bf EVT\_LIST\_CACHE\_HINT(id, func)}}{Prepare cache for a virtual list control}
 \end{twocollist}%
 
 \wxheading{See also}
@@ -48,6 +49,20 @@ functions that take a wxListEvent argument.
 
 Constructor.
 
+\membersection{wxListEvent::GetCacheFrom}\label{wxlisteventgetcachefrom}
+
+\constfunc{long}{GetCacheFrom}{\void}
+
+For {\tt EVT\_LIST\_CACHE\_HINT} event only: return the first item which the
+list control advises us to cache.
+
+\membersection{wxListEvent::GetCacheTo}\label{wxlisteventgetcacheto}
+
+\constfunc{long}{GetCacheTo}{\void}
+
+For {\tt EVT\_LIST\_CACHE\_HINT} event only: return the last item (inclusive)
+which the list control advises us to cache.
+
 \membersection{wxListEvent::GetCode}\label{wxlisteventgetcode}
 
 \constfunc{int}{GetCode}{\void}

include/wx/listctrl.h

@@ -365,6 +365,10 @@ public:
     long GetMask() const { return m_item.m_mask; }
     const wxListItem& GetItem() const { return m_item; }
 
+    // for wxEVT_COMMAND_LIST_CACHE_HINT only
+    long GetCacheFrom() const { return m_oldItemIndex; }
+    long GetCacheTo() const { return m_itemIndex; }
+
     void CopyObject(wxObject& object_dest) const;
 
 private:
@@ -392,6 +396,7 @@ BEGIN_DECLARE_EVENT_TYPES()
     DECLARE_EVENT_TYPE(wxEVT_COMMAND_LIST_ITEM_RIGHT_CLICK, 713)
     DECLARE_EVENT_TYPE(wxEVT_COMMAND_LIST_ITEM_MIDDLE_CLICK, 714)
     DECLARE_EVENT_TYPE(wxEVT_COMMAND_LIST_ITEM_ACTIVATED, 715)
+    DECLARE_EVENT_TYPE(wxEVT_COMMAND_LIST_CACHE_HINT, 716)
 END_DECLARE_EVENT_TYPES()
 
 typedef void (wxEvtHandler::*wxListEventFunction)(wxListEvent&);
@@ -412,6 +417,7 @@ typedef void (wxEvtHandler::*wxListEventFunction)(wxListEvent&);
 #define EVT_LIST_ITEM_RIGHT_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_COMMAND_LIST_ITEM_RIGHT_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, (wxObject *) NULL ),
 #define EVT_LIST_ITEM_MIDDLE_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_COMMAND_LIST_ITEM_MIDDLE_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, (wxObject *) NULL ),
 #define EVT_LIST_ITEM_ACTIVATED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_COMMAND_LIST_ITEM_ACTIVATED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, (wxObject *) NULL ),
+#define EVT_LIST_CACHE_HINT(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_COMMAND_LIST_CACHE_HINT, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, (wxObject *) NULL ),
 
 #endif // wxUSE_LISTCTRL
 

samples/listctrl/listtest.cpp

@@ -90,6 +90,7 @@ BEGIN_EVENT_TABLE(MyListCtrl, wxListCtrl)
     EVT_LIST_KEY_DOWN(LIST_CTRL, MyListCtrl::OnListKeyDown)
     EVT_LIST_ITEM_ACTIVATED(LIST_CTRL, MyListCtrl::OnActivated)
     EVT_LIST_COL_CLICK(LIST_CTRL, MyListCtrl::OnColClick)
+    EVT_LIST_CACHE_HINT(LIST_CTRL, MyListCtrl::OnCacheHint)
 
     EVT_CHAR(MyListCtrl::OnChar)
 END_EVENT_TABLE()
@@ -551,6 +552,12 @@ void MyFrame::OnDeleteAll(wxCommandEvent& WXUNUSED(event))
 
 // MyListCtrl
 
+void MyListCtrl::OnCacheHint(wxListEvent& event)
+{
+    wxLogMessage( "OnCacheHint: cache items %ld..%ld",
+                  event.GetCacheFrom(), event.GetCacheTo() );
+}
+
 void MyListCtrl::OnColClick(wxListEvent& event)
 {
     wxLogMessage( "OnColumnClick at %d.", event.GetColumn() );

samples/listctrl/listtest.h

@@ -45,6 +45,7 @@ public:
     void OnDeselected(wxListEvent& event);
     void OnListKeyDown(wxListEvent& event);
     void OnActivated(wxListEvent& event);
+    void OnCacheHint(wxListEvent& event);
 
     void OnChar(wxKeyEvent& event);
 

src/generic/listctrl.cpp

@@ -100,6 +100,7 @@ DEFINE_EVENT_TYPE(wxEVT_COMMAND_LIST_COL_CLICK)
 DEFINE_EVENT_TYPE(wxEVT_COMMAND_LIST_ITEM_RIGHT_CLICK)
 DEFINE_EVENT_TYPE(wxEVT_COMMAND_LIST_ITEM_MIDDLE_CLICK)
 DEFINE_EVENT_TYPE(wxEVT_COMMAND_LIST_ITEM_ACTIVATED)
+DEFINE_EVENT_TYPE(wxEVT_COMMAND_LIST_CACHE_HINT)
 
 // ----------------------------------------------------------------------------
 // constants

src/msw/listctrl.cpp

@@ -104,6 +104,7 @@ DEFINE_EVENT_TYPE(wxEVT_COMMAND_LIST_COL_CLICK)
 DEFINE_EVENT_TYPE(wxEVT_COMMAND_LIST_ITEM_RIGHT_CLICK)
 DEFINE_EVENT_TYPE(wxEVT_COMMAND_LIST_ITEM_MIDDLE_CLICK)
 DEFINE_EVENT_TYPE(wxEVT_COMMAND_LIST_ITEM_ACTIVATED)
+DEFINE_EVENT_TYPE(wxEVT_COMMAND_LIST_CACHE_HINT)
 
 IMPLEMENT_DYNAMIC_CLASS(wxListCtrl, wxControl)
 IMPLEMENT_DYNAMIC_CLASS(wxListItem, wxObject)
@@ -1615,6 +1616,16 @@ bool wxListCtrl::MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result)
             return TRUE;
 #endif // _WIN32_IE >= 0x300
 
+        case LVN_ODCACHEHINT:
+            {
+                const NM_CACHEHINT *cacheHint = (NM_CACHEHINT *)lParam;
+
+                eventType = wxEVT_COMMAND_LIST_CACHE_HINT;
+                event.m_oldItemIndex = cacheHint->iFrom;
+                event.m_itemIndex = cacheHint->iTo;
+            }
+            break;
+
         case LVN_GETDISPINFO:
             if ( IsVirtual() )
             {
@@ -1670,11 +1681,11 @@ bool wxListCtrl::MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result)
             return TRUE;
 
         case LVN_ENDLABELEDIT:
-            {
+            // logic here is inversed compared to all the other messages
             *result = event.IsAllowed();
+
             return TRUE;
     }
-    }
 
     *result = !event.IsAllowed();