listctrl.tex

很牛的GUI源码wxWidgets-2.8.0.zip 可在多种平台下运行.

\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}

\constfunc{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{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\
\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}}

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.

{\bf NB:} This method is currently only implemented in the Windows version.


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

\func{void}{SetBackgroundColour}{\param{const wxColour\& }{col}}

Sets the background colour (GetBackgroundColour already implicit in
wxWindow class).


\membersection{wxListCtrl::SetColumn}\label{wxlistctrlsetcolumn}

\func{bool}{SetColumn}{\param{int }{col}, \param{wxListItem\& }{item}}

Sets information about this column. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
information.


\membersection{wxListCtrl::SetColumnWidth}\label{wxlistctrlsetcolumnwidth}

\func{bool}{SetColumnWidth}{\param{int }{col}, \param{int }{width}}

Sets the column width.

{\it width} can be a width in pixels or wxLIST\_AUTOSIZE (-1) or wxLIST\_AUTOSIZE\_USEHEADER (-2).
wxLIST\_AUTOSIZE will resize the column to the length of its longest item. wxLIST\_AUTOSIZE\_USEHEADER
will resize the column to the length of the header (Win32) or 80 pixels (other platforms).

In small or normal icon view, {\it col} must be -1, and the column width is set for all columns.


\membersection{wxListCtrl::SetImageList}\label{wxlistctrlsetimagelist}

\func{void}{SetImageList}{\param{wxImageList*}{ imageList}, \param{int }{which}}

Sets the image list associated with the control. {\it which} is one of
wxIMAGE\_LIST\_NORMAL, wxIMAGE\_LIST\_SMALL, wxIMAGE\_LIST\_STATE (the last is unimplemented).

This method does not take ownership of the image list, you have to
delete it yourself.

\wxheading{See also}

\helpref{wxListCtrl::AssignImageList}{wxlistctrlassignimagelist}



\membersection{wxListCtrl::SetItem}\label{wxlistctrlsetitem}

\func{bool}{SetItem}{\param{wxListItem\& }{info}}

\func{long}{SetItem}{\param{long }{index}, \param{int }{col}, \param{const }{wxString\& label}, \param{int }{imageId = -1}}

Sets information about the item.

wxListItem is a class with the following members:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{long m\_mask}{Indicates which fields are valid. See the list of valid mask flags below.}
\twocolitem{long m\_itemId}{The zero-based item position.}
\twocolitem{int m\_col}{Zero-based column, if in report mode.}
\twocolitem{long m\_state}{The state of the item. See the list of valid state flags below.}
\twocolitem{long m\_stateMask}{A mask indicating which state flags are valid. See the list of valid state flags below.}
\twocolitem{wxString m\_text}{The label/header text.}
\twocolitem{int m\_image}{The zero-based index into an image list.}
\twocolitem{long m\_data}{Application-defined data.}
\twocolitem{int m\_format}{For columns only: the format. Can be wxLIST\_FORMAT\_LEFT, wxLIST\_FORMAT\_RIGHT or
wxLIST\_FORMAT\_CENTRE.}
\twocolitem{int m\_width}{For columns only: the column width.}
\end{twocollist}

The {\bf m\_mask} member contains a bitlist specifying which of the other fields are valid. The flags are:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{wxLIST\_MASK\_STATE}{The {\bf m\_state} field is valid.}
\twocolitem{wxLIST\_MASK\_TEXT}{The {\bf m\_text} field is valid.}
\twocolitem{wxLIST\_MASK\_IMAGE}{The {\bf m\_image} field is valid.}
\twocolitem{wxLIST\_MASK\_DATA}{The {\bf m\_data} field is valid.}
\twocolitem{wxLIST\_MASK\_WIDTH}{The {\bf m\_width} field is valid.}
\twocolitem{wxLIST\_MASK\_FORMAT}{The {\bf m\_format} field is valid.}
\end{twocollist}

The {\bf m\_stateMask} and {\bf m\_state} members take flags from the following:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{wxLIST\_STATE\_DONTCARE}{Don't care what the state is. Win32 only. }
\twocolitem{wxLIST\_STATE\_DROPHILITED}{The item is highlighted to receive a drop event. Win32 only. }
\twocolitem{wxLIST\_STATE\_FOCUSED}{The item has the focus.}
\twocolitem{wxLIST\_STATE\_SELECTED}{The item is selected.}
\twocolitem{wxLIST\_STATE\_CUT}{The item is in the cut state. Win32 only. }
\end{twocollist}

The wxListItem object can also contain item-specific colour and font
information: for this you need to call one of SetTextColour(),
SetBackgroundColour() or SetFont() functions on it passing it the colour/font
to use. If the colour/font is not specified, the default list control
colour/font is used.

\func{long}{SetItem}{\param{long }{index}, \param{int }{col}, \param{const wxString\& }{label}, \param{int }{imageId = -1}}

Sets a string field at a particular column.

\pythonnote{In place of a single overloaded method name, wxPython
implements the following methods:\par
\indented{2cm}{\begin{twocollist}
\twocolitem{{\bf SetItem(item)}}{Sets information about the given wxListItem.}
\twocolitem{{\bf SetStringItem(index, col, label, imageId)}}{Sets a
string or image at a given location.}
\end{twocollist}}
}

\membersection{wxListCtrl::SetItemBackgroundColour}\label{wxlistctrlsetitembackgroundcolour}

\func{void}{SetItemBackgroundColour}{\param{long }{item}, \param{const wxColour\& }{col}}

Sets the background colour for this item. This function only works in report view.

The colour can be retrieved using
\helpref{GetItemBackgroundColour}{wxlistctrlgetitembackgroundcolour}.



\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 items in the range
from $0$ to {\it count}.


\membersection{wxListCtrl::SetItemData}\label{wxlistctrlsetitemdata}

\func{bool}{SetItemData}{\param{long }{item}, \param{long }{data}}

Associates application-defined data with this item.


\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
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}}

Sets the unselected and selected images associated with the item. The images are indices into the
image list associated with the list control. This form is deprecated: {\it selImage} is not
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}}

Sets the position of the item, in icon or small icon view. Windows only.


\membersection{wxListCtrl::SetItemState}\label{wxlistctrlsetitemstate}

\func{bool}{SetItemState}{\param{long }{item}, \param{long }{state}, \param{long }{stateMask}}

Sets the item state. For a list of state flags, see \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem}.

The {\bf stateMask} indicates which state flags are valid.


\membersection{wxListCtrl::SetItemText}\label{wxlistctrlsetitemtext}

\func{void}{SetItemText}{\param{long }{item}, \param{const wxString\& }{text}}

Sets the item text for this item.


\membersection{wxListCtrl::SetItemTextColour}\label{wxlistctrlsetitemtextcolour}

\func{void}{SetItemTextColour}{\param{long }{item}, \param{const wxColour\& }{col}}

Sets the colour for this item. This function only works in report view.

The colour can be retrieved using
\helpref{GetItemTextColour}{wxlistctrlgetitemtextcolour}.


\membersection{wxListCtrl::SetSingleStyle}\label{wxlistctrlsetsinglestyle}

\func{void}{SetSingleStyle}{\param{long }{style}, \param{const bool }{add = true}}

Adds or removes a single window style.


\membersection{wxListCtrl::SetTextColour}\label{wxlistctrlsettextcolour}

\func{void}{SetTextColour}{\param{const wxColour\& }{col}}

Sets the text colour of the list control.


\membersection{wxListCtrl::SetWindowStyleFlag}\label{wxlistctrlsetwindowstyleflag}

\func{void}{SetWindowStyleFlag}{\param{long }{style}}

Sets the whole window style, deleting all items.

\membersection{wxListCtrl::SortItems}\label{wxlistctrlsortitems}

\func{bool}{SortItems}{\param{wxListCtrlCompare }{fnSortCallBack}, \param{long }{data}}

Call this function to sort the items in the list control. Sorting is done
using the specified {\it fnSortCallBack} function. This function must have the
following prototype:

\begin{verbatim}
int wxCALLBACK wxListCompareFunction(long item1, long item2, long sortData)
\end{verbatim}

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)}).

\wxheading{Parameters}

\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.}

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.

\pythonnote{wxPython uses the sortData parameter to pass the Python
function to call, so it is not available for programmer use.  Call
SortItems with a reference to a callable object that expects two
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.}