fixed GetItemSpacing() inconsistency by deprecating the old function and adding a...

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

diff --git a/docs/latex/wx/listctrl.tex b/docs/latex/wx/listctrl.tex
index b837842541a6615da1dfa21026cb729c6dbcb450..03cd4fd808a3c863f93c94fdf733fabc0c16b856 100644 (file)
--- a/docs/latex/wx/listctrl.tex
+++ b/docs/latex/wx/listctrl.tex
@@ -14,7 +14,12 @@ without consuming much memory. To use virtual list control you must use
 \helpref{OnGetItemText}{wxlistctrlongetitemtext} (and optionally 
 \helpref{OnGetItemImage}{wxlistctrlongetitemimage} and 
 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}) to return the information
 \helpref{OnGetItemText}{wxlistctrlongetitemtext} (and optionally 
 \helpref{OnGetItemImage}{wxlistctrlongetitemimage} and 
 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}) to return the information

-about the items when the control requests it.
+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
+the number of items in the control happen -- this is required to allow having a
+practically infinite number of items. For example, in a multiple selection
+virtual list control, the selections won't be sent when many items are selected
+at once because this could mean iterating over all the items.

 
 Using many of wxListCtrl features is shown in the
 \helpref{corresponding sample}{samplelistctrl}.
 
 Using many of wxListCtrl features is shown in the
 \helpref{corresponding sample}{samplelistctrl}.


@@ -47,10 +52,10 @@ the list wraps, unlike a wxListBox.}
 \twocolitem{\windowstyle{wxLC\_ALIGN\_TOP}}{Icons align to the top. Win32 default, Win32 only. }
 \twocolitem{\windowstyle{wxLC\_ALIGN\_LEFT}}{Icons align to the left. }
 \twocolitem{\windowstyle{wxLC\_AUTOARRANGE}}{Icons arrange themselves. Win32 only. }
 \twocolitem{\windowstyle{wxLC\_ALIGN\_TOP}}{Icons align to the top. Win32 default, Win32 only. }
 \twocolitem{\windowstyle{wxLC\_ALIGN\_LEFT}}{Icons align to the left. }
 \twocolitem{\windowstyle{wxLC\_AUTOARRANGE}}{Icons arrange themselves. Win32 only. }

-\twocolitem{\windowstyle{wxLC\_USER\_TEXT}}{The application provides label text on demand, except for column headers. Win32 only. }
+\twocolitem{\windowstyle{wxLC\_VIRTUAL}}{The application provides items text on demand.}

 \twocolitem{\windowstyle{wxLC\_EDIT\_LABELS}}{Labels are editable: the application will be notified when editing starts.}
 \twocolitem{\windowstyle{wxLC\_EDIT\_LABELS}}{Labels are editable: the application will be notified when editing starts.}

-\twocolitem{\windowstyle{wxLC\_NO\_HEADER}}{No header in report mode. Win32 only. }
-\twocolitem{\windowstyle{wxLC\_SINGLE\_SEL}}{Single selection.}
+\twocolitem{\windowstyle{wxLC\_NO\_HEADER}}{No header in report mode. }
+\twocolitem{\windowstyle{wxLC\_SINGLE\_SEL}}{Single selection (default is multiple).}

 \twocolitem{\windowstyle{wxLC\_SORT\_ASCENDING}}{Sort in ascending order (must still supply a comparison callback in SortItems.}
 \twocolitem{\windowstyle{wxLC\_SORT\_DESCENDING}}{Sort in descending order (must still supply a comparison callback in SortItems.}
 \twocolitem{\windowstyle{wxLC\_HRULES}}{Draws light horizontal rules between rows in report mode.}
 \twocolitem{\windowstyle{wxLC\_SORT\_ASCENDING}}{Sort in ascending order (must still supply a comparison callback in SortItems.}
 \twocolitem{\windowstyle{wxLC\_SORT\_DESCENDING}}{Sort in descending order (must still supply a comparison callback in SortItems.}
 \twocolitem{\windowstyle{wxLC\_HRULES}}{Draws light horizontal rules between rows in report mode.}


@@ -223,7 +228,7 @@ 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{const bool }{partial = false}}

 
 Find an item whose label matches this string, starting from the item after {\it start} or
 the beginning if {\it start} is -1.
 
 Find an item whose label matches this string, starting from the item after {\it start} or
 the beginning if {\it start} is -1.


@@ -241,7 +246,7 @@ the item after {\it start} or the beginning if {\it start} is -1.
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}

-\twocolitem{{\bf FindItem(start, str, partial=FALSE)}}{}
+\twocolitem{{\bf FindItem(start, str, partial=false)}}{}

 \twocolitem{{\bf FindItemData(start, data)}}{}
 \twocolitem{{\bf FindItemAtPos(start, point, direction)}}{}
 \end{twocollist}}
 \twocolitem{{\bf FindItemData(start, data)}}{}
 \twocolitem{{\bf FindItemAtPos(start, point, direction)}}{}
 \end{twocollist}}


@@ -250,7 +255,7 @@ implements the following methods:\par
 \perlnote{In wxPerl there are three methods instead of a single overloaded
 method:\par
 \indented{2cm}{\begin{twocollist}
 \perlnote{In wxPerl there are three methods instead of a single overloaded
 method:\par
 \indented{2cm}{\begin{twocollist}

-\twocolitem{{\bf FindItem( start, str, partial = FALSE ) }}{}
+\twocolitem{{\bf FindItem( start, str, partial = false ) }}{}

 \twocolitem{{\bf FindItemData( start, data ) }}{}
 \twocolitem{{\bf FindItemAtPos( start, point, direction )}}{}
 \end{twocollist}
 \twocolitem{{\bf FindItemData( start, data ) }}{}
 \twocolitem{{\bf FindItemAtPos( start, point, direction )}}{}
 \end{twocollist}


@@ -266,6 +271,12 @@ information.
 \perlnote{In wxPerl this method takes only the {\bf col} parameter and
   returns a Wx::ListItem ( or undef ).}
 
 \perlnote{In wxPerl this method takes only the {\bf col} parameter and
   returns a Wx::ListItem ( or undef ).}
 

+\membersection{wxListCtrl::GetColumnCount}\label{wxlistctrlgetcolumncount}
+
+\constfunc{int}{GetColumnCount}{\void}
+
+Returns the number of columns.
+

 \membersection{wxListCtrl::GetColumnWidth}\label{wxlistctrlgetcolumnwidth}
 
 \constfunc{int}{GetColumnWidth}{\param{int }{col}}
 \membersection{wxListCtrl::GetColumnWidth}\label{wxlistctrlgetcolumnwidth}
 
 \constfunc{int}{GetColumnWidth}{\param{int }{col}}


@@ -283,9 +294,12 @@ or small icon view).
 
 \membersection{wxListCtrl::GetEditControl}\label{wxlistctrlgeteditcontrol}
 
 
 \membersection{wxListCtrl::GetEditControl}\label{wxlistctrlgeteditcontrol}
 

-\constfunc{wxTextCtrl\&}{GetEditControl}{\void}
+\constfunc{wxTextCtrl *}{GetEditControl}{\void}
+
+Returns the edit control being currently used to edit a label. Returns {\tt NULL}
+if no label is being edited.

 
 

-Gets the edit control for editing labels.
+{\bf NB:} It is currently only implemented for wxMSW.

 
 \membersection{wxListCtrl::GetImageList}\label{wxlistctrlgetimagelist}
 
 
 \membersection{wxListCtrl::GetImageList}\label{wxlistctrlgetimagelist}
 


@@ -353,15 +367,17 @@ Returns the rectangle representing the item's size and position, in client coord
 ID and code and returns the wxRect.}
 
 \perlnote{In wxPerl this method takes only the {\bf item} parameter and
 ID and code and returns the wxRect.}
 
 \perlnote{In wxPerl this method takes only the {\bf item} parameter and

-retutrns a Wx::Rect ( or undef ).}
+returns a Wx::Rect ( or undef ).}
+

 
 \membersection{wxListCtrl::GetItemSpacing}\label{wxlistctrlgetitemspacing}
 
 
 \membersection{wxListCtrl::GetItemSpacing}\label{wxlistctrlgetitemspacing}
 

-\constfunc{int}{GetItemSpacing}{\param{bool }{isSmall}}
+\constfunc{wxSize}{GetItemSpacing}{\void}
+
+Retrieves the spacing between icons in pixels: horizontal spacing is returned
+as \texttt{x} component of the \helpref{wxSize}{wxsize} object and the vertical
+spacing as its \texttt{y} component.

 
 

-Retrieves the spacing between icons in pixels.
-If {\it small} is TRUE, gets the spacing for the small icon
-view, otherwise the large icon view.

 
 \membersection{wxListCtrl::GetItemState}\label{wxlistctrlgetitemstate}
 
 
 \membersection{wxListCtrl::GetItemState}\label{wxlistctrlgetitemstate}
 


@@ -381,7 +397,7 @@ Gets the item text for this item.
 
 \constfunc{long}{GetNextItem}{\param{long }{item}, \param{int }{geometry = wxLIST\_NEXT\_ALL}, \param{int }{state = wxLIST\_STATE\_DONTCARE}}
 
 
 \constfunc{long}{GetNextItem}{\param{long }{item}, \param{int }{geometry = wxLIST\_NEXT\_ALL}, \param{int }{state = wxLIST\_STATE\_DONTCARE}}
 

-Searches for an item with the given goemetry or state, starting from
+Searches for an item with the given geometry or state, starting from

 {\it item} but excluding the {\it item} itself. If {\it item} is -1,
 the first item that matches the specified flags will be returned.
 
 {\it item} but excluding the {\it item} itself. If {\it item} is -1,
 the first item that matches the specified flags will be returned.
 


@@ -449,6 +465,19 @@ Gets the text colour of the list control.
 Gets the index of the topmost visible item when in
 list or report view.
 
 Gets the index of the topmost visible item when in
 list or report view.
 

+
+\membersection{wxRect}{wxListCtrl::GetViewRect}\label{wxlistctrlgetviewrect}
+
+\constfunc{wxRect}{GetViewRect}{\void}
+
+Returns the rectangle taken by all items in the control. In other words, if the
+controls client size were equal to the size of this rectangle, no scrollbars
+would be needed and no free space would be left.
+
+Note that this function only works in the icon and small icon views, not in
+list or report views (this is a limitation of the native Win32 control).
+
+

 \membersection{wxListCtrl::HitTest}\label{wxlistctrlhittest}
 
 \func{long}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
 \membersection{wxListCtrl::HitTest}\label{wxlistctrlhittest}
 
 \func{long}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}


@@ -482,12 +511,10 @@ flags value mentioned above.}
 
 \func{long}{InsertColumn}{\param{long }{col}, \param{wxListItem\& }{info}}
 
 
 \func{long}{InsertColumn}{\param{long }{col}, \param{wxListItem\& }{info}}
 

-For list view mode (only), inserts a column. For more details, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
-

 \func{long}{InsertColumn}{\param{long }{col}, \param{const wxString\& }{heading}, \param{int }{format = wxLIST\_FORMAT\_LEFT},\rtfsp
 \param{int }{width = -1}}
 
 \func{long}{InsertColumn}{\param{long }{col}, \param{const wxString\& }{heading}, \param{int }{format = wxLIST\_FORMAT\_LEFT},\rtfsp
 \param{int }{width = -1}}
 

-For list view mode (only), inserts a column. For more details, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.
+For report view mode (only), inserts a column. For more details, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.

 
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par


@@ -596,16 +623,40 @@ the given {\it column} for the specified {\tt item}.
 \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
 
 \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\
 \helpref{OnGetItemAttr}{wxlistctrlongetitemattr}
 

+\membersection{wxListCtrl::RefreshItem}\label{wxlistctrlrefreshitem}
+
+\func{void}{RefreshItem}{\param{long }{item}}
+
+Redraws the given {\it item}. This is only useful for the virtual list controls
+as without calling this function the displayed value of the item doesn't change
+even when the underlying data does change.
+
+\wxheading{See also}
+
+\helpref{RefreshItems}{wxlistctrlrefreshitems}
+
+
+\membersection{wxListCtrl::RefreshItems}\label{wxlistctrlrefreshitems}
+
+\func{void}{RefreshItems}{\param{long }{itemFrom}, \param{long }{itemTo}}
+
+Redraws the items between {\it itemFrom} and {\it itemTo}. The starting item
+must be less than or equal to the ending one.
+
+Just as \helpref{RefreshItem}{wxlistctrlrefreshitem} this is only useful for
+virtual list controls.
+
+

 \membersection{wxListCtrl::ScrollList}\label{wxlistctrlscrolllist}
 
 \func{bool}{ScrollList}{\param{int }{dx}, \param{int }{dy}}
 
 \membersection{wxListCtrl::ScrollList}\label{wxlistctrlscrolllist}
 
 \func{bool}{ScrollList}{\param{int }{dx}, \param{int }{dy}}
 

-Scrolls the list control. If in icon, small icon or report view mode,
-dx specifies the number of pixels to scroll. If in list view mode, dx
-specifies the number of columns to scroll.
+Scrolls the list control. If in icon, small icon or report view mode, 
+{\it dx} specifies the number of pixels to scroll. If in list view mode, 
+{\it dx} specifies the number of columns to scroll. {\it dy} always specifies
+the number of pixels to scroll vertically.

 
 

-If in icon, small icon or list view mode, dy specifies the number of pixels
-to scroll. If in report view mode, dy specifies the number of lines to scroll.
+{\bf NB:} This method is currently only implemented in the Windows version.

 
 \membersection{wxListCtrl::SetBackgroundColour}\label{wxlistctrlsetbackgroundcolour}
 
 
 \membersection{wxListCtrl::SetBackgroundColour}\label{wxlistctrlsetbackgroundcolour}
 


@@ -722,7 +773,7 @@ string or image at a given location.}
 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
 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
+\helpref{OnGetItemText}{wxlistctrlongetitemtext}) for all items in the range

 from $0$ to {\it count}.
 
 \membersection{wxListCtrl::SetItemData}\label{wxlistctrlsetitemdata}
 from $0$ to {\it count}.
 
 \membersection{wxListCtrl::SetItemData}\label{wxlistctrlsetitemdata}


@@ -760,7 +811,7 @@ Sets the item text for this item.
 
 \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{const bool }{add = true}}

 
 Adds or removes a single window style.
 
 
 Adds or removes a single window style.