\section{\class{wxListCtrl}}\label{wxlistctrl}
-A list control presents lists in a number of formats: list view, report view, icon view
-and small icon view. Elements are numbered from zero.
+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.
-To intercept events from a list control, use the event table macros described in \helpref{wxListEvent}{wxlistevent}.
+Using many of wxListCtrl is shown in the
+\helpref{corresponding sample}{samplelistctrl}.
+
+To intercept events from a list control, use the event table macros described
+in \helpref{wxListEvent}{wxlistevent}.
\wxheading{Derived from}
\membersection{wxListCtrl::SortItems}\label{wxlistctrlsortitems}
-\func{bool}{SortItems}{\param{wxListCtrlCompare }{fn}, \param{long }{data}}
-
-Sorts the items in the list control.
+\func{bool}{SortItems}{\param{wxListCtrlCompare }{fnSortCallBack}, \param{long }{data}}
-fn is a function which takes 3 long arguments: item1, item2, data.
+Call this function to sorts the items in the list control. Sorting is done
+using the specified {\it fnSortCallBack} function. This function must have the
+following prototype:
-item1 is the long data associated with a first item (NOT the index).
+\begin{verbatim}
+int wxCALLBACK wxListCompareFunction(long item1, long item2, long sortData)
+\end{verbatim}
-item2 is the long data associated with a second item (NOT the index).
+It is called each time when the two items must be compared and should return 0
+if the items are equal, negative value if the first item is less than the
+second one and positive value if the first one is greater than the second one
+(the same convention as used by {\tt qsort(3)}).
-data is the same value as passed to SortItems.
+\wxheading{Parameters}
-The return value is a negative number if the first item should precede the second
-item, a positive number of the second item should precede the first,
-or zero if the two items are equivalent.
+\docparam{item1}{client data associated with the first item ({\bf NOT} the index).
+\docparam{item2}{client data associated with the second item ({\bf NOT} the index).
+\docparam{data}{the value passed to SortItems() itself.}
-data is arbitrary data to be passed to the sort function.
+Notice that the control may only be sorted on client data associated with the
+items, so you {\bf must} use \helpref{SetItemData}{wxlistctrlsetitemdata} if
+you want to be able to sort the items in the control.
+Please see the \helpref{listctrl sample}{samplelistctrl} for an example of
+using this function.
%% Licence: wxWindows licence
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% NB: please keep the subsections in alphabetic order!
+
\section{wxWindows samples}\label{samples}
Probably the best way to learn wxWindows is by reading the source of some 50+
features of wxWindows are they supposed to test.
There are currently more than 50 different samples as part of wxWindows and
-this list is not complete.
+this list is not complete. You should start your tour of wxWindows with the
+\helpref{minimal sample}{sampleminimal} which is the wxWindows version of
+"Hello, world!". It shows the basic structure of wxWindows program and is the
+most commented sample of all - looking at its source code is recommended.
+
+The next most useful sample is probably the \helpref{controls}{samplecontrols}
+one which shows many of wxWindows standard controls, such as buttons,
+listboxes, checkboxes, comboboxes e.t.c.
+
+Other, more complicated controls, have their own samples. In this category you
+may find the following samples showing the corresponding controls:
+
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\helpref{wxCalendarCtrl}{samplecalendar}}{Calendar a.k.a. date picker control}
+\twocolitem{\helpref{wxListCtrl}{samplelistctrl}}{List view control}
+\twocolitem{\helpref{wxTreeCtrl}{sampletreectrl}}{Tree view control}
+\twocolitem{\helpref{wxGrid}{samplegrid}}{Grid control}
+\end{twocollist}
+
+Finally, it might be helpful to do a search in the entire sample directory if
+you can't find the sample you showing the control you are interested in by
+name. Most of wxWindows classes, occur in at least one of the samples.
\subsection{Minimal sample}\label{sampleminimal}
Take a look at DnDShapeDataObject class to see how you may use
\helpref{wxDataObject}{wxdataobject} to achieve this.
+\subsection{Grid sample}\label{samplegrid}
+
+TODO.
+
\subsection{HTML samples}\label{samplehtml}
Eight HTML samples (you can find them in directory {\tt samples/html})
while {\it Helpview} is simple tool that only pops up help window and
displays help books given at command line.
+\subsection{Image sample}\label{sampleimage}
+
+The image sample demonstrates the use of the \helpref{wxImage}{wximage} class
+and shows how to download images in a variety of formats, currently PNG, GIF,
+TIFF, JPEG, BMP, PNM and PCX. The top of the sample shows to rectangles, one
+of which is drawn directly in the window, the other one is drawn into a
+\helpref{wxBitmap}{wxbitmap}, converted to a wxImage, saved as a PNG image
+and then reloaded from the PNG file again so that conversions between wxImage
+and wxBitmap as well as loading and save PNG files are tested.
+
+At the bottom of the main frame is a test for using a mono-chrome bitmap by
+drawing into a \helpref{wxMemoryDC}{wxmemorydc}. The bitmap is then drawn
+specifying the foreground and background colours with
+\helpref{wxDC::SetTextForeground}{wxdcsettextforeground} and
+\helpref{wxDC::SetTextBackground}{wxdcsettextbackground} (on the left). The
+bitmap is then converted to a wxImage and the foreground colour (black) is
+replaced with red using \helpref{wxImage::Replace}{wximagereplace}.
+
\subsection{Layout sample}\label{samplelayout}
The layout sample demonstrates the two different layout systems offered
class. See also \helpref{wxNotebookSizer}{wxnotebooksizer} and
\helpref{wxSizer}{wxsizer}.
-\subsection{Image sample}\label{sampleimage}
+\subsection{Listctrl sample}\label{samplelistctrl}
-The image sample demonstrates the use of the \helpref{wxImage}{wximage} class
-and shows how to download images in a variety of formats, currently PNG, GIF,
-TIFF, JPEG, BMP, PNM and PCX. The top of the sample shows to rectangles, one
-of which is drawn directly in the window, the other one is drawn into a
-\helpref{wxBitmap}{wxbitmap}, converted to a wxImage, saved as a PNG image
-and then reloaded from the PNG file again so that conversions between wxImage
-and wxBitmap as well as loading and save PNG files are tested.
+This sample shows \helpref{wxListCtrl}{wxlistctrl} control. Different modes
+supported by the control (list, icons, small icons, report) may be chosen from
+the menu.
-At the bottom of the main frame is a test for using a mono-chrome bitmap by
-drawing into a \helpref{wxMemoryDC}{wxmemorydc}. The bitmap is then drawn
-specifying the foreground and background colours with
-\helpref{wxDC::SetTextForeground}{wxdcsettextforeground} and
-\helpref{wxDC::SetTextBackground}{wxdcsettextbackground} (on the left). The
-bitmap is then converted to a wxImage and the foreground colour (black) is
-replaced with red using \helpref{wxImage::Replace}{wximagereplace}.
+The sample also provides some timings for adding/deleting/sorting a lot of
+(several thousands) controls into the control.
\subsection{Sockets sample}\label{samplesockets}
toolbar.
\end{itemize}
+
+\subsection{Treectrl sample}\label{sampletreectrl}
+
+This sample demonstrates using \helpref{wxTreeCtrl}{wxtreectrl} class. Here
+you may see how to process various notification messages sent by this control
+and also when they occur (by looking at the messages in the text control in
+the bottom part of the frame).
+
+Adding, inserting and deleting items and branches from the tree as well as
+sorting (in default alphabetical order as well as in custom one) is
+demonstrated here as well - try the corresponding menu entries.