Use const

[wxWidgets.git] / docs / latex / wx / listctrl.tex

diff --git a/docs/latex/wx/listctrl.tex b/docs/latex/wx/listctrl.tex
index ed071edc70afc2d9522003daea5810bc8803afbd..4e1b969eb9879e699f53ca7e422d52e287af93fe 100644 (file)
--- a/docs/latex/wx/listctrl.tex
+++ b/docs/latex/wx/listctrl.tex
@@ -1,3 +1,14 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% 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,
 \section{\class{wxListCtrl}}\label{wxlistctrl}
 
 A list control presents lists in a number of formats: list view, report view,


@@ -12,7 +23,7 @@ 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
 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
 \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


@@ -27,6 +38,12 @@ Using many of wxListCtrl features is shown in the
 To intercept events from a list control, use the event table macros described
 in \helpref{wxListEvent}{wxlistevent}.
 
 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}\\
 \wxheading{Derived from}
 
 \helpref{wxControl}{wxcontrol}\\


@@ -38,6 +55,10 @@ in \helpref{wxListEvent}{wxlistevent}.
 
 <wx/listctrl.h>
 
 
 <wx/listctrl.h>
 

+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+

 \wxheading{Window styles}
 
 \twocolwidtha{7cm}
 \wxheading{Window styles}
 
 \twocolwidtha{7cm}


@@ -96,8 +117,8 @@ functions that take a \helpref{wxListEvent}{wxlistevent} argument.
 
 \wxheading{See also}
 
 
 \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}}}
 \helpref{wxListItem}{wxlistitem}
 
 \latexignore{\rtfignore{\wxheading{Members}}}


@@ -193,7 +214,7 @@ Creates the list control. See \helpref{wxListCtrl::wxListCtrl}{wxlistctrlctor} f
 
 \func{bool}{DeleteAllItems}{}
 
 
 \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
 
 {\bf NB:} This function does {\it not} send the
 {\tt wxEVT\_COMMAND\_LIST\_DELETE\_ITEM} event because deleting many items


@@ -239,10 +260,12 @@ Ensures this item is visible.
 
 \membersection{wxListCtrl::FindItem}\label{wxlistctrlfinditem}
 
 
 \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
 
 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}}
 
 
 \func{long}{FindItem}{\param{long }{start}, \param{long }{data}}
 


@@ -315,7 +338,8 @@ or small icon view).
 Returns the edit control being currently used to edit a label. Returns {\tt NULL}
 if no label is being edited.
 
 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::GetImageList}\label{wxlistctrlgetimagelist}


@@ -377,6 +401,13 @@ Returns the number of items in the list control.
 Gets the application-defined data associated with this item.
 
 
 Gets the application-defined data associated with this item.
 
 

+\membersection{wxListCtrl::GetItemFont}\label{wxlistctrlgetitemfont}
+
+\constfunc{wxFont}{GetItemFont}{\param{long }{item}}
+
+Returns the item's font.
+
+

 \membersection{wxListCtrl::GetItemPosition}\label{wxlistctrlgetitemposition}
 
 \constfunc{bool}{GetItemPosition}{\param{long }{item}, \param{wxPoint\& }{pos}}
 \membersection{wxListCtrl::GetItemPosition}\label{wxlistctrlgetitemposition}
 
 \constfunc{bool}{GetItemPosition}{\param{long }{item}, \param{wxPoint\& }{pos}}


@@ -394,7 +425,8 @@ returns a Wx::Point ( or undef ).}
 
 \constfunc{bool}{GetItemRect}{\param{long }{item}, \param{wxRect\& }{rect}, \param{int }{code = wxLIST\_RECT\_BOUNDS}}
 
 
 \constfunc{bool}{GetItemRect}{\param{long }{item}, \param{wxRect\& }{rect}, \param{int }{code = wxLIST\_RECT\_BOUNDS}}
 

-Returns the rectangle representing the item's size and position, in client coordinates.
+Returns the rectangle representing the item's size and position, in physical
+coordinates.

 
 {\it code} is one of wxLIST\_RECT\_BOUNDS, wxLIST\_RECT\_ICON, wxLIST\_RECT\_LABEL.
 
 
 {\it code} is one of wxLIST\_RECT\_BOUNDS, wxLIST\_RECT\_ICON, wxLIST\_RECT\_LABEL.
 


@@ -406,6 +438,25 @@ returns a Wx::Rect ( or undef ).}
 
 
 
 
 
 

+\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}
 \membersection{wxListCtrl::GetItemSpacing}\label{wxlistctrlgetitemspacing}
 
 \constfunc{wxSize}{GetItemSpacing}{\void}


@@ -467,7 +518,7 @@ This function may be used to find all selected items in the control like this:
             break;
 
         // this item is selected - do whatever is needed with it
             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}
 
     }
 \end{verbatim}
 


@@ -482,7 +533,7 @@ This function may be used to find all selected items in the control like this:
 \twocolitem{wxLIST\_NEXT\_RIGHT}{Searches for an item to the right of the specified item.}
 \end{twocollist}
 
 \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:
 other platforms.
 
 {\it state} can be a bitlist of the following:


@@ -535,7 +586,7 @@ list or report views (this is a limitation of the native Win32 control).
 
 \membersection{wxListCtrl::HitTest}\label{wxlistctrlhittest}
 
 
 \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}
 
 Determines which item (if any) is at the specified point,
 giving details in {\it flags}. Returns index of the item or {\tt wxNOT\_FOUND}


@@ -557,6 +608,14 @@ if no item is at the specified point.
 wxLIST\_HITTEST\_ONITEMSTATEICON.}
 \end{twocollist}
 
 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.}
 \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.}


@@ -579,8 +638,8 @@ implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
 \twocolitem{{\bf InsertColumn(col, heading, format=wxLIST\_FORMAT\_LEFT,
 width=-1)}}{Creates a column using a header string only.}
 \indented{2cm}{\begin{twocollist}
 \twocolitem{{\bf InsertColumn(col, heading, format=wxLIST\_FORMAT\_LEFT,
 width=-1)}}{Creates a column using a header string only.}

-\twocolitem{{\bf InsertColumnInfo(col, item)}}{Creates a column using a
-wxListInfo.}
+\twocolitem{{\bf InsertColumnItem(col, item)}}{Creates a column using a
+wxListItem.}

 \end{twocollist}}
 }
 
 \end{twocollist}}
 }
 


@@ -638,38 +697,61 @@ method:\par
 
 \membersection{wxListCtrl::OnGetItemAttr}\label{wxlistctrlongetitemattr}
 
 
 \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.
 
 
 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},\\
 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}
 
 \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.
 
 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},\\
 
 The base class version always returns $-1$.
 
 \wxheading{See also}
 
 \helpref{OnGetItemText}{wxlistctrlongetitemtext},\\

+\helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\

 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
 
 \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}
 
 
 \membersection{wxListCtrl::OnGetItemText}\label{wxlistctrlongetitemtext}
 


@@ -683,6 +765,7 @@ the given {\it column} for the specified {\tt item}.
 
 \helpref{SetItemCount}{wxlistctrlsetitemcount},\\
 \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
 
 \helpref{SetItemCount}{wxlistctrlsetitemcount},\\
 \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\

+\helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\

 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
 
 
 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
 
 


@@ -864,13 +947,24 @@ from $0$ to {\it count}.
 
 Associates application-defined data with this item.
 
 
 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{void}{SetItemFont}{\param{long }{item}, \param{const wxFont\& }{font}}
+
+Sets the item's font.
+

 
 \membersection{wxListCtrl::SetItemImage}\label{wxlistctrlsetitemimage}
 
 \func{bool}{SetItemImage}{\param{long }{item}, \param{int }{image}}
 
 Sets the image associated with the item. The image is an index into the
 
 \membersection{wxListCtrl::SetItemImage}\label{wxlistctrlsetitemimage}
 
 \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}}
 
 
 \func{bool}{SetItemImage}{\param{long }{item}, \param{int }{image}, \param{int }{selImage}}
 


@@ -879,6 +973,14 @@ image list associated with the list control. This form is deprecated: {\it selIm
 used.
 
 
 used.
 
 

+\membersection{wxListCtrl::SetItemColumnImage}\label{wxlistctrlsetitemcolumnimage}
+
+\func{bool}{SetItemImage}{\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}}
 \membersection{wxListCtrl::SetItemPosition}\label{wxlistctrlsetitemposition}
 
 \func{bool}{SetItemPosition}{\param{long }{item}, \param{const wxPoint\& }{pos}}


@@ -886,6 +988,18 @@ used.
 Sets the position of the item, in icon or small icon view. Windows only.
 
 
 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::SetItemState}\label{wxlistctrlsetitemstate}
 
 \func{bool}{SetItemState}{\param{long }{item}, \param{long }{state}, \param{long }{stateMask}}


@@ -914,7 +1028,7 @@ The colour can be retrieved using
 
 \membersection{wxListCtrl::SetSingleStyle}\label{wxlistctrlsetsinglestyle}
 
 
 \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.
 
 
 Adds or removes a single window style.
 


@@ -970,6 +1084,6 @@ SortItems with a reference to a callable object that expects two
 parameters.}
 
 \perlnote{In wxPerl the comparison function must take just two parameters;
 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.}