listctrl.tex

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        listctrl.tex
%% Purpose:     wxListCtrl docs
%% Author:
%% Modified by:
%% Created:
%% RCS-ID:      $Id: listctrl.tex,v 1.79 2006/12/09 13:42:29 RR Exp $
%% 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,
icon view and small icon view. In any case, elements are numbered from zero.
For all these modes, the items are stored in the control and must be added to
it using \helpref{InsertItem}{wxlistctrlinsertitem} method.

A special case of report view quite different from the other modes of the list
control is a virtual control in which the items data (including text, images
and attributes) is managed by the main program and is requested by the control
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
\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
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}.

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}\\
\helpref{wxWindow}{wxwindow}\\
\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/listctrl.h>

\wxheading{Window styles}

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\windowstyle{wxLC\_LIST}}{Multicolumn list view, with optional small icons.
Columns are computed automatically, i.e. you don't set columns as in wxLC\_REPORT. In other words,
the list wraps, unlike a wxListBox.}
\twocolitem{\windowstyle{wxLC\_REPORT}}{Single or multicolumn report view, with optional header.}
\twocolitem{\windowstyle{wxLC\_VIRTUAL}}{The application provides items text on demand. May only be used with wxLC\_REPORT.}
\twocolitem{\windowstyle{wxLC\_ICON}}{Large icon view, with optional labels.}
\twocolitem{\windowstyle{wxLC\_SMALL\_ICON}}{Small icon view, with optional labels.}
\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\_EDIT\_LABELS}}{Labels are editable: the application will be notified when editing starts.}
\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\_VRULES}}{Draws light vertical rules between columns in report mode.}
\end{twocollist}

See also \helpref{window styles overview}{windowstyles}.

\wxheading{Event handling}

To process input from a list control, use these event handler macros to direct input to member
functions that take a \helpref{wxListEvent}{wxlistevent} argument.

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf EVT\_LIST\_BEGIN\_DRAG(id, func)}}{Begin dragging with the left mouse button.}
\twocolitem{{\bf EVT\_LIST\_BEGIN\_RDRAG(id, func)}}{Begin dragging with the right mouse button.}
\twocolitem{{\bf EVT\_LIST\_BEGIN\_LABEL\_EDIT(id, func)}}{Begin editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
\twocolitem{{\bf EVT\_LIST\_END\_LABEL\_EDIT(id, func)}}{Finish editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
\twocolitem{{\bf EVT\_LIST\_DELETE\_ITEM(id, func)}}{Delete an item.}
\twocolitem{{\bf EVT\_LIST\_DELETE\_ALL\_ITEMS(id, func)}}{Delete all items.}
%\twocolitem{{\bf EVT\_LIST\_GET\_INFO(id, func)}}{Request information from the application, usually the item text.}
%\twocolitem{{\bf EVT\_LIST\_SET\_INFO(id, func)}}{Information is being supplied (not implemented).}
\twocolitem{{\bf EVT\_LIST\_ITEM\_SELECTED(id, func)}}{The item has been selected.}
\twocolitem{{\bf EVT\_LIST\_ITEM\_DESELECTED(id, func)}}{The item has been deselected.}
\twocolitem{{\bf EVT\_LIST\_ITEM\_ACTIVATED(id, func)}}{The item has been activated (ENTER or double click).}
\twocolitem{{\bf EVT\_LIST\_ITEM\_FOCUSED(id, func)}}{The currently focused item has changed.}
\twocolitem{{\bf EVT\_LIST\_ITEM\_MIDDLE\_CLICK(id, func)}}{The middle mouse button has been clicked on an item.}
\twocolitem{{\bf EVT\_LIST\_ITEM\_RIGHT\_CLICK(id, func)}}{The right mouse button has been clicked on an item.}
\twocolitem{{\bf EVT\_LIST\_KEY\_DOWN(id, func)}}{A key has been pressed.}
\twocolitem{{\bf EVT\_LIST\_INSERT\_ITEM(id, func)}}{An item has been inserted.}
\twocolitem{{\bf EVT\_LIST\_COL\_CLICK(id, func)}}{A column ({\bf m\_col}) has been left-clicked.}
\twocolitem{{\bf EVT\_LIST\_COL\_RIGHT\_CLICK(id, func)}}{A column ({\bf m\_col}) has been right-clicked.}
\twocolitem{{\bf EVT\_LIST\_COL\_BEGIN\_DRAG(id, func)}}{The user started resizing a column - can be vetoed.}
\twocolitem{{\bf EVT\_LIST\_COL\_DRAGGING(id, func)}}{The divider between columns is being dragged.}
\twocolitem{{\bf EVT\_LIST\_COL\_END\_DRAG(id, func)}}{A column has been resized by the user.}
\twocolitem{{\bf EVT\_LIST\_CACHE\_HINT(id, func)}}{Prepare cache for a virtual list control}
\end{twocollist}%

\wxheading{See also}

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


\membersection{wxListCtrl::wxListCtrl}\label{wxlistctrlctor}

\func{}{wxListCtrl}{\void}

Default constructor.

\func{}{wxListCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
\param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
\param{long}{ style = wxLC\_ICON}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = wxListCtrlNameStr}}

Constructor, creating and showing a list control.

\wxheading{Parameters}

\docparam{parent}{Parent window. Must not be NULL.}

\docparam{id}{Window identifier. A value of -1 indicates a default value.}

\docparam{pos}{Window position.}

\docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
appropriately.}

\docparam{style}{Window style. See \helpref{wxListCtrl}{wxlistctrl}.}

\docparam{validator}{Window validator.}

\docparam{name}{Window name.}

\wxheading{See also}

\helpref{wxListCtrl::Create}{wxlistctrlcreate}, \helpref{wxValidator}{wxvalidator}


\membersection{wxListCtrl::\destruct{wxListCtrl}}\label{wxlistctrldtor}

\func{void}{\destruct{wxListCtrl}}{\void}

Destructor, destroying the list control.


\membersection{wxListCtrl::Arrange}\label{wxlistctrlarrange}

\func{bool}{Arrange}{\param{int }{flag = wxLIST\_ALIGN\_DEFAULT}}

Arranges the items in icon or small icon view. This only has effect on Win32. {\it flag} is one of:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{wxLIST\_ALIGN\_DEFAULT}{Default alignment.}
\twocolitem{wxLIST\_ALIGN\_LEFT}{Align to the left side of the control.}
\twocolitem{wxLIST\_ALIGN\_TOP}{Align to the top side of the control.}
\twocolitem{wxLIST\_ALIGN\_SNAP\_TO\_GRID}{Snap to grid.}
\end{twocollist}


\membersection{wxListCtrl::AssignImageList}\label{wxlistctrlassignimagelist}

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

Sets the image list associated with the control and
takes ownership of it (i.e. the control will, unlike when using
SetImageList, delete the list when destroyed). {\it which} is one of
wxIMAGE\_LIST\_NORMAL, wxIMAGE\_LIST\_SMALL, wxIMAGE\_LIST\_STATE (the last is unimplemented).

\wxheading{See also}

\helpref{wxListCtrl::SetImageList}{wxlistctrlsetimagelist}


\membersection{wxListCtrl::ClearAll}\label{wxlistctrlclearall}

\func{void}{ClearAll}{}

Deletes all items and all columns.


\membersection{wxListCtrl::Create}\label{wxlistctrlcreate}

\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
\param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
\param{long}{ style = wxLC\_ICON}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = wxListCtrlNameStr}}

Creates the list control. See \helpref{wxListCtrl::wxListCtrl}{wxlistctrlctor} for further details.


\membersection{wxListCtrl::DeleteAllItems}\label{wxlistctrldeleteallitems}

\func{bool}{DeleteAllItems}{}

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
from the control would be too slow then (unlike \helpref{DeleteItem}{wxlistctrldeleteitem}).


\membersection{wxListCtrl::DeleteColumn}\label{wxlistctrldeletecolumn}

\func{bool}{DeleteColumn}{\param{int }{col}}

Deletes a column.


\membersection{wxListCtrl::DeleteItem}\label{wxlistctrldeleteitem}

\func{bool}{DeleteItem}{\param{long }{item}}

Deletes the specified item. This function sends the
{\tt wxEVT\_COMMAND\_LIST\_DELETE\_ITEM} event for the item being deleted.

See also: \helpref{DeleteAllItems}{wxlistctrldeleteallitems}


\membersection{wxListCtrl::EditLabel}\label{wxlistctrledit}

\func{void}{EditLabel}{\param{long }{item}}

Starts editing the label of the given item. This function generates a
EVT\_LIST\_BEGIN\_LABEL\_EDIT event which can be vetoed so that no
text control will appear for in-place editing.

If the user changed the label (i.e. s/he does not press ESC or leave
the text control without changes, a EVT\_LIST\_END\_LABEL\_EDIT event
will be sent which can be vetoed as well.


\membersection{wxListCtrl::EnsureVisible}\label{wxlistctrlensurevisible}

\func{bool}{EnsureVisible}{\param{long }{item}}

Ensures this item is visible.


\membersection{wxListCtrl::FindItem}\label{wxlistctrlfinditem}

\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 {\it start} or
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}}

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

\func{long}{FindItem}{\param{long }{start}, \param{const wxPoint\& }{pt}, \param{int }{direction}}

Find an item nearest this position in the specified direction, starting from
{\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}
\twocolitem{{\bf FindItem(start, str, partial=false)}}{}
\twocolitem{{\bf FindItemData(start, data)}}{}
\twocolitem{{\bf FindItemAtPos(start, point, direction)}}{}
\end{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 FindItemData( start, data ) }}{}
\twocolitem{{\bf FindItemAtPos( start, point, direction )}}{}
\end{twocollist}
}}


\membersection{wxListCtrl::GetColumn}\label{wxlistctrlgetcolumn}

\constfunc{bool}{GetColumn}{\param{int }{col}, \param{wxListItem\& }{item}}

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

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

Gets the column width (report view only).


\membersection{wxListCtrl::GetCountPerPage}\label{wxlistctrlgetcountperpage}

\constfunc{int}{GetCountPerPage}{\void}

Gets the number of items that can fit vertically in the
visible area of the list control (list or report view)
or the total number of items in the list control (icon
or small icon view).


\membersection{wxListCtrl::GetEditControl}\label{wxlistctrlgeteditcontrol}

\constfunc{wxTextCtrl *}{GetEditControl}{\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 and the generic version,
not for the native Mac OS X version.


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

\constfunc{wxImageList*}{GetImageList}{\param{int }{which}}

Returns the specified image list. {\it which} may be one of:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\windowstyle{wxIMAGE\_LIST\_NORMAL}}{The normal (large icon) image list.}
\twocolitem{\windowstyle{wxIMAGE\_LIST\_SMALL}}{The small icon image list.}
\twocolitem{\windowstyle{wxIMAGE\_LIST\_STATE}}{The user-defined state image list (unimplemented).}
\end{twocollist}


\membersection{wxListCtrl::GetItem}\label{wxlistctrlgetitem}

\constfunc{bool}{GetItem}{\param{wxListItem\& }{info}}