+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: listctrl.tex
+%% Purpose: wxListCtrl docs
+%% Author:
+%% Modified by:
+%% Created:
+%% RCS-ID: $Id$
+%% Copyright: (c) wxWidgets
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\section{\class{wxListCtrl}}\label{wxlistctrl}
A list control presents lists in a number of formats: list view, report view,
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{OnGetItemImage}{wxlistctrlongetitemimage} or \helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage} and
\helpref{OnGetItemAttr}{wxlistctrlongetitemattr}) to return the information
about the items when the control requests it. Virtual list control can be used
as a normal one except that no operations which can take time proportional to
To intercept events from a list control, use the event table macros described
in \helpref{wxListEvent}{wxlistevent}.
+{\bf Mac Note:} Starting with 2.8, wxListCtrl uses a native implementation for
+report mode, and uses a generic implementation for other modes. You can use the
+generic implementation for report mode as well by setting the
+mac.listctrl.always\_use\_generic \helpref{wxSystemOption}{wxsystemoptions} to
+1.
+
\wxheading{Derived from}
\helpref{wxControl}{wxcontrol}\\
<wx/listctrl.h>
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+
\wxheading{Window styles}
\twocolwidtha{7cm}
\twocolitem{{\bf EVT\_LIST\_CACHE\_HINT(id, func)}}{Prepare cache for a virtual list control}
\end{twocollist}%
+\wxheading{Column ordering}
+
+In report view, the control has several columns which are identified by their
+internal indices. By default, these indices correspond to their order on
+screen, i.e. the column $0$ appears first (in the left-to-right or maybe
+right-to-left if the current language uses this writing direction), the column
+$1$ next and so on. However it is possible to reorder the columns visual order
+using \helpref{SetColumnsOrder}{wxlistctrlsetcolumnsorder} method and the
+user can also rearrange the columns interactively by dragging them. In this
+case, the index of the column is not the same as its order and the functions
+\helpref{GetColumnOrder}{wxlistctrlgetcolumnorder} and
+\helpref{GetColumnIndexFromOrder}{wxlistctrlgetcolumnindexfromorder} should be
+used to translate between them.
+
+Please notice that current column reordering is implemented only in wxMSW.
+
\wxheading{See also}
-\helpref{wxListCtrl overview}{wxlistctrloverview}, \helpref{wxListBox}{wxlistbox}, \helpref{wxTreeCtrl}{wxtreectrl},\rtfsp
-\helpref{wxImageList}{wximagelist}, \helpref{wxListEvent}{wxlistevent},
+\helpref{wxListCtrl overview}{wxlistctrloverview}, \helpref{wxListView}{wxlistview}, \helpref{wxListBox}{wxlistbox},\rtfsp
+\helpref{wxTreeCtrl}{wxtreectrl}, \helpref{wxImageList}{wximagelist}, \helpref{wxListEvent}{wxlistevent},
\helpref{wxListItem}{wxlistitem}
\latexignore{\rtfignore{\wxheading{Members}}}
\func{bool}{DeleteAllItems}{}
-Deletes all the items in the list control.
+Deletes all items in the list control.
{\bf NB:} This function does {\it not} send the
{\tt wxEVT\_COMMAND\_LIST\_DELETE\_ITEM} event because deleting many items
\membersection{wxListCtrl::FindItem}\label{wxlistctrlfinditem}
-\func{long}{FindItem}{\param{long }{start}, \param{const wxString\& }{str}, \param{const bool }{partial = false}}
+\func{long}{FindItem}{\param{long }{start}, \param{const wxString\& }{str}, \param{bool }{partial = false}}
Find an item whose label matches this string, starting from {\it start} or
-the beginning if {\it start} is -1.
+the beginning if {\it start} is -1. The string comparison is case
+insensitive. If {\it partial} is true then this method will look for
+items which begin with {\it str}.
\func{long}{FindItem}{\param{long }{start}, \param{long }{data}}
Gets the column width (report view only).
+\membersection{wxListCtrl::GetColumnIndexFromOrder}\label{wxlistctrlgetcolumnindexfromorder}
+
+\constfunc{int}{GetColumnIndexFromOrder}{\param{int }{order}}
+
+Gets the column number by visual order index (report view only).
+
+
+\membersection{wxListCtrl::GetColumnOrder}\label{wxlistctrlgetcolumnorder}
+
+\constfunc{int}{GetColumnOrder}{\param{int }{col}}
+
+Gets the column visual order index (valid in report view only).
+
+
+\membersection{wxListCtrl::GetColumnsOrder}\label{wxlistctrlgetcolumnsorder}
+
+\constfunc{wxArrayInt}{GetColumnsOrder}{\void}
+
+Returns the array containing the orders of all columns. On error, an empty
+array is returned.
+
+
\membersection{wxListCtrl::GetCountPerPage}\label{wxlistctrlgetcountperpage}
\constfunc{int}{GetCountPerPage}{\void}
Returns the edit control being currently used to edit a label. Returns {\tt NULL}
if no label is being edited.
-{\bf NB:} It is currently only implemented for wxMSW.
+{\bf NB:} It is currently only implemented for wxMSW and the generic version,
+not for the native Mac OS X version.
\membersection{wxListCtrl::GetImageList}\label{wxlistctrlgetimagelist}
+\membersection{wxListCtrl::GetSubItemRect}\label{wxlistctrlgetsubitemrect}
+
+\constfunc{bool}{GetSubItemRect}{\param{long }{item}, \param{long }{subItem}, \param{wxRect\& }{rect}, \param{int }{code = wxLIST\_RECT\_BOUNDS}}
+
+Returns the rectangle representing the size and position, in physical
+coordinates, of the given subitem, i.e. the part of the row \arg{item} in the
+column \arg{subItem}.
+
+This method is only meaningfull when the wxListCtrl is in the report mode. If
+\arg{subItem} parameter is equal to the special value
+\texttt{wxLIST\_GETSUBITEMRECT\_WHOLEITEM} the return value is the same as
+for \helpref{GetItemRect}{wxlistctrlgetitemrect}.
+
+\arg{code} can be one of \texttt{wxLIST\_RECT\_BOUNDS},
+\texttt{wxLIST\_RECT\_ICON} or \texttt{wxLIST\_RECT\_LABEL}.
+
+\newsince{2.7.0}
+
+
\membersection{wxListCtrl::GetItemSpacing}\label{wxlistctrlgetitemspacing}
\constfunc{wxSize}{GetItemSpacing}{\void}
break;
// this item is selected - do whatever is needed with it
- wxLogMessage("Item %ld is selected."), item);
+ wxLogMessage("Item %ld is selected.", item);
}
\end{verbatim}
\twocolitem{wxLIST\_NEXT\_RIGHT}{Searches for an item to the right of the specified item.}
\end{twocollist}
-{\bf NB:} this parameters is only supported by wxMSW currently and ignored on
+{\bf NB:} this parameter is only supported by wxMSW currently and ignored on
other platforms.
{\it state} can be a bitlist of the following:
\membersection{wxListCtrl::HitTest}\label{wxlistctrlhittest}
-\func{long}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
+\constfunc{long}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}, \param{long *}{ptrSubItem}}
Determines which item (if any) is at the specified point,
giving details in {\it flags}. Returns index of the item or {\tt wxNOT\_FOUND}
wxLIST\_HITTEST\_ONITEMSTATEICON.}
\end{twocollist}
+If \arg{ptrSubItem} is not \NULL and the wxListCtrl is in the report
+mode the subitem (or column) number will also be provided.
+This feature is only available in version 2.7.0 or higher and is currently only
+implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on
+the host system or the value stored in \arg{ptrSubItem} will be always -1. To
+compile this feature into wxWidgets library you need to have access to
+commctrl.h of version 4.70 that is provided by Microsoft.
+
\pythonnote{A tuple of values is returned in the wxPython version of
this method. The first value is the item id and the second is the
flags value mentioned above.}
\membersection{wxListCtrl::OnGetItemAttr}\label{wxlistctrlongetitemattr}
-\func{virtual wxListItemAttr *}{OnGetItemAttr}{\param{long }{item}}
+\constfunc{virtual wxListItemAttr *}{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.
+wxListCtrl will not delete the pointer or keep a reference of it. You can
+return the same wxListItemAttr pointer for every OnGetItemAttr call.
+
The base class version always returns {\tt NULL}.
\wxheading{See also}
\helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
+\helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\
\helpref{OnGetItemText}{wxlistctrlongetitemtext}
\membersection{wxListCtrl::OnGetItemImage}\label{wxlistctrlongetitemimage}
-\func{virtual int}{OnGetItemImage}{\param{long }{item}}
+\constfunc{virtual int}{OnGetItemImage}{\param{long }{item}}
This function must be overloaded in the derived class for a control with
{\tt wxLC\_VIRTUAL} style having an \helpref{image list}{wxlistctrlsetimagelist}
(if the control doesn't have an image list, it is not necessary to overload
it). It should return the index of the items image in the controls image list
or $-1$ for no image.
+In a control with {\tt wxLC\_REPORT} style, OnGetItemImage only gets called for
+the first column of each line.
The base class version always returns $-1$.
\wxheading{See also}
\helpref{OnGetItemText}{wxlistctrlongetitemtext},\\
+\helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\
\helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
+\membersection{wxListCtrl::OnGetItemColumnImage}\label{wxlistctrlongetitemcolumnimage}
+
+\constfunc{virtual int}{OnGetItemColumnImage}{\param{long }{item}, \param{long }{column}}
+
+Overload this function in the derived class for a control with
+{\tt wxLC\_VIRTUAL} and {\tt wxLC\_REPORT} styles in order to specify the image
+index for the given line and column.
+
+The base class version always calls OnGetItemImage for the first column, else
+it returns $-1$.
+
+\wxheading{See also}
+
+\helpref{OnGetItemText}{wxlistctrlongetitemtext},\\
+\helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
+\helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
\membersection{wxListCtrl::OnGetItemText}\label{wxlistctrlongetitemtext}
\helpref{SetItemCount}{wxlistctrlsetitemcount},\\
\helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
+\helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\
\helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
In small or normal icon view, {\it col} must be -1, and the column width is set for all columns.
+\membersection{wxListCtrl::SetColumnsOrder}\label{wxlistctrlsetcolumnsorder}
+
+\constfunc{bool}{SetColumnOrder}{\param{const wxArrayInt\& }{orders}}
+
+Sets the order of all columns at once. The \arg{orders} array must have the
+same number elements as the number of columns and contain each position exactly
+once.
+
+This function is valid in report view only.
+
+
\membersection{wxListCtrl::SetImageList}\label{wxlistctrlsetimagelist}
\func{void}{SetImageList}{\param{wxImageList*}{ imageList}, \param{int }{which}}
Associates application-defined data with this item.
+Notice that this function cannot be used to associate pointers with the control
+items, use \helpref{SetItemPtrData}{wxlistctrlsetitemptrdata} instead.
+
\membersection{wxListCtrl::SetItemFont}\label{wxlistctrlsetitemfont}
\func{bool}{SetItemImage}{\param{long }{item}, \param{int }{image}}
Sets the image associated with the item. The image is an index into the
-image list associated with the list control.
+image list associated with the list control. In report view, this only sets
+the image for the first column.
\func{bool}{SetItemImage}{\param{long }{item}, \param{int }{image}, \param{int }{selImage}}
used.
+\membersection{wxListCtrl::SetItemColumnImage}\label{wxlistctrlsetitemcolumnimage}
+
+\func{bool}{SetItemColumnImage}{\param{long }{item}, \param{long }{column}, \param{int }{image}}
+
+Sets the image associated with the item. In report view, you can specify the column.
+The image is an index into the image list associated with the list control.
+
+
\membersection{wxListCtrl::SetItemPosition}\label{wxlistctrlsetitemposition}
\func{bool}{SetItemPosition}{\param{long }{item}, \param{const wxPoint\& }{pos}}
Sets the position of the item, in icon or small icon view. Windows only.
+\membersection{wxListCtrl::SetItemPtrData}\label{wxlistctrlsetitemptrdata}
+
+\func{bool}{SetItemPtrData}{\param{long }{item}, \param{wxUIntPtr }{data}}
+
+Associates application-defined data with this item. The \arg{data} parameter may
+be either an integer or a pointer cast to the \texttt{wxUIntPtr} type which is
+guaranteed to be large enough to be able to contain all integer types and
+pointers.
+
+\newsince{2.8.4}
+
+
\membersection{wxListCtrl::SetItemState}\label{wxlistctrlsetitemstate}
\func{bool}{SetItemState}{\param{long }{item}, \param{long }{state}, \param{long }{stateMask}}
\membersection{wxListCtrl::SetSingleStyle}\label{wxlistctrlsetsinglestyle}
-\func{void}{SetSingleStyle}{\param{long }{style}, \param{const bool }{add = true}}
+\func{void}{SetSingleStyle}{\param{long }{style}, \param{bool }{add = true}}
Adds or removes a single window style.
parameters.}
\perlnote{In wxPerl the comparison function must take just two parameters;
- however, you may use a closure to achieve an effect similar to the
- SortItems third parameter.}
+however, you may use a closure to achieve an effect similar to the
+SortItems third parameter.}
projects / wxWidgets.git / blobdiff