listctrl.tex

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

Gets information about the item. See \helpref{wxListCtrl::SetItem}{wxlistctrlsetitem} for more
information.

You must call {\it info.SetId()} to the ID of item you're interested in
before calling this method.

\pythonnote{The wxPython version of this method takes an integer parameter
for the item ID, an optional integer for the column number, and
returns the wxListItem object.}

\perlnote{In wxPerl this method takes as parameter the {\bf ID} of the item
and ( optionally ) the column, and returns a Wx::ListItem object.}


\membersection{wxListCtrl::GetItemBackgroundColour}\label{wxlistctrlgetitembackgroundcolour}

\constfunc{wxColour}{GetItemBackgroundColour}{\param{long }{item}}

Returns the colour for this item. If the item has no specific colour, returns
an invalid colour (and not the default background control of the control
itself).

\wxheading{See also}

\helpref{GetItemTextColour}{wxlistctrlgetitemtextcolour}


\membersection{wxListCtrl::GetItemCount}\label{wxlistctrlgetitemcount}

\constfunc{int}{GetItemCount}{\void}

Returns the number of items in the list control.


\membersection{wxListCtrl::GetItemData}\label{wxlistctrlgetitemdata}

\constfunc{long}{GetItemData}{\param{long }{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}}

Returns the position of the item, in icon or small icon view.

\pythonnote{The wxPython version of this method accepts only the item
ID and returns the wxPoint.}

\perlnote{In wxPerl this method takes only the {\bf item} parameter and
returns a Wx::Point ( or undef ).}


\membersection{wxListCtrl::GetItemRect}\label{wxlistctrlgetitemrect}

\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 physical
coordinates.

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

\pythonnote{The wxPython version of this method accepts only the item
ID and code and returns the wxRect.}

\perlnote{In wxPerl this method takes only the {\bf item} parameter and
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}

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.



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

\constfunc{int}{GetItemState}{\param{long }{item}, \param{long }{stateMask}}

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

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


\membersection{wxListCtrl::GetItemText}\label{wxlistctrlgetitemtext}

\constfunc{wxString}{GetItemText}{\param{long }{item}}

Gets the item text for this item.


\membersection{wxListCtrl::GetItemTextColour}\label{wxlistctrlgetitemtextcolour}

\constfunc{wxColour}{GetItemTextColour}{\param{long }{item}}

Returns the colour for this item. If the item has no specific colour, returns
an invalid colour (and not the default foreground control of the control itself
as this wouldn't allow distinguishing between items having the same colour as
the current control foreground and items with default colour which, hence, have
always the same colour as the control).


\membersection{wxListCtrl::GetNextItem}\label{wxlistctrlgetnextitem}

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

Returns the first item with given state following {\it item} or -1 if
no such item found.

This function may be used to find all selected items in the control like this:

\begin{verbatim}
    long item = -1;
    for ( ;; )
    {
        item = listctrl->GetNextItem(item,
                                     wxLIST_NEXT_ALL,
                                     wxLIST_STATE_SELECTED);
        if ( item == -1 )
            break;

        // this item is selected - do whatever is needed with it
        wxLogMessage("Item %ld is selected.", item);
    }
\end{verbatim}

{\it geometry} can be one of:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{wxLIST\_NEXT\_ABOVE}{Searches for an item above the specified item.}
\twocolitem{wxLIST\_NEXT\_ALL}{Searches for subsequent item by index.}
\twocolitem{wxLIST\_NEXT\_BELOW}{Searches for an item below the specified item.}
\twocolitem{wxLIST\_NEXT\_LEFT}{Searches for an item to the left of the specified item.}
\twocolitem{wxLIST\_NEXT\_RIGHT}{Searches for an item to the right of the specified item.}
\end{twocollist}

{\bf NB:} this parameter is only supported by wxMSW currently and ignored on
other platforms.

{\it state} can be a bitlist of the following:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{wxLIST\_STATE\_DONTCARE}{Don't care what the state is.}
\twocolitem{wxLIST\_STATE\_DROPHILITED}{The item indicates it is a drop target.}
\twocolitem{wxLIST\_STATE\_FOCUSED}{The item has the focus.}
\twocolitem{wxLIST\_STATE\_SELECTED}{The item is selected.}
\twocolitem{wxLIST\_STATE\_CUT}{The item is selected as part of a cut and paste operation.}
\end{twocollist}


\membersection{wxListCtrl::GetSelectedItemCount}\label{wxlistctrlgetselecteditemcount}

\constfunc{int}{GetSelectedItemCount}{\void}

Returns the number of selected items in the list control.


\membersection{wxListCtrl::GetTextColour}\label{wxlistctrlgettextcolour}

\constfunc{wxColour}{GetTextColour}{\void}

Gets the text colour of the list control.


\membersection{wxListCtrl::GetTopItem}\label{wxlistctrlgettopitem}

\constfunc{long}{GetTopItem}{\void}

Gets the index of the topmost visible item when in
list or report view.



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

\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}
if no item is at the specified point.
{\it flags} will be a combination of the following flags:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{wxLIST\_HITTEST\_ABOVE}{Above the client area.}
\twocolitem{wxLIST\_HITTEST\_BELOW}{Below the client area.}
\twocolitem{wxLIST\_HITTEST\_NOWHERE}{In the client area but below the last item.}
\twocolitem{wxLIST\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
\twocolitem{wxLIST\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
\twocolitem{wxLIST\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
\twocolitem{wxLIST\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
\twocolitem{wxLIST\_HITTEST\_TOLEFT}{To the right of the client area.}
\twocolitem{wxLIST\_HITTEST\_TORIGHT}{To the left of the client area.}
\twocolitem{wxLIST\_HITTEST\_ONITEM}{Combination of wxLIST\_HITTEST\_ONITEMICON, wxLIST\_HITTEST\_ONITEMLABEL,
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.}

\perlnote{In wxPerl this method only takes the {\bf point} parameter
  and returns a 2-element list {\tt ( item, flags )}.}


\membersection{wxListCtrl::InsertColumn}\label{wxlistctrlinsertcolumn}

\func{long}{InsertColumn}{\param{long }{col}, \param{wxListItem\& }{info}}

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

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
\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 InsertColumnItem(col, item)}}{Creates a column using a
wxListItem.}
\end{twocollist}}
}


\membersection{wxListCtrl::InsertItem}\label{wxlistctrlinsertitem}

\func{long}{InsertItem}{\param{wxListItem\& }{info}}

Inserts an item, returning the index of the new item if successful,
-1 otherwise.

\func{long}{InsertItem}{\param{long }{index}, \param{const wxString\& }{label}}

Inserts a string item.

\func{long}{InsertItem}{\param{long }{index}, \param{int }{imageIndex}}

Inserts an image item.

\func{long}{InsertItem}{\param{long }{index}, \param{const wxString\& }{label}, \param{int }{imageIndex}}

Insert an image/string item.

\wxheading{Parameters}

\docparam{info}{wxListItem object}

\docparam{index}{Index of the new item, supplied by the application}

\docparam{label}{String label}

\docparam{imageIndex}{index into the image list associated with this control and view style}

\pythonnote{In place of a single overloaded method name, wxPython
implements the following methods:\par
\indented{2cm}{\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf InsertItem(item)}}{Inserts an item using a wxListItem.}
\twocolitem{{\bf InsertStringItem(index, label)}}{Inserts a string item.}
\twocolitem{{\bf InsertImageItem(index, imageIndex)}}{Inserts an image item.}
\twocolitem{{\bf InsertImageStringItem(index, label, imageIndex)}}{Insert an image/string item.}
\end{twocollist}}
}

\perlnote{In wxPerl there are four methods instead of a single overloaded
method:\par
\indented{2cm}{\begin{twocollist}
\twocolitem{{\bf InsertItem( item )}}{Inserts a Wx::ListItem}
\twocolitem{{\bf InsertStringItem( index, label )}}{Inserts a string item}
\twocolitem{{\bf InsertImageItem( index, imageIndex )}}{Inserts an image item}
\twocolitem{{\bf InsertImageStringItem( index, label, imageIndex )}}{Inserts
 an item with a string and an image}
\end{twocollist}
}}


\membersection{wxListCtrl::OnGetItemAttr}\label{wxlistctrlongetitemattr}

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