GTK

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

\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. Elements are numbered from zero.

To intercept events from a list control, use the event table macros described in \helpref{wxListEvent}{wxlistevent}.

\wxheading{Derived from}

\helpref{wxControl}{wxcontrol}\\
\helpref{wxWindow}{wxwindow}\\
\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}

\wxheading{Window styles}

\twocolwidtha{5cm}
\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\_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 (default).}
\twocolitem{\windowstyle{wxLC\_ALIGN\_LEFT}}{Icons align to the left.}
\twocolitem{\windowstyle{wxLC\_AUTOARRANGE}}{Icons arrange themselves.}
\twocolitem{\windowstyle{wxLC\_USER\_TEXT}}{The application provides label text on demand, except for column headers.}
\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.}
\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.}
\end{twocollist}

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

\wxheading{See also}

\helpref{wxListCtrl overview}{wxlistctrloverview}, \helpref{wxListBox}{wxlistbox}, \helpref{wxTreeCtrl}{wxtreectrl},\rtfsp
\helpref{wxImageList}{wximagelist}, \helpref{wxListEvent}{wxlistevent}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxListCtrl::wxListCtrl}\label{wxlistctrlconstr}

\func{}{wxListCtrl}{\void}

Default constructor.

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

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

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

Destructor, destroying the list control.

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

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

Arranges the items in icon or small icon view. {\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::Create}\label{wxlistctrlcreate}

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

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

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

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

Deletes the specified item.

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

\func{bool}{DeleteAllItems}{\void}

Deletes all the items in the list control.

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

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

Deletes a column.

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

\func{wxTextCtrl\&}{Edit}{\param{const long }{item}}

Starts editing a label.

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

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

Ensures this item is visible.

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

\func{long}{FindItem}{\param{const 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.

\func{long}{FindItem}{\param{const long }{start}, \param{const long }{data}}

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

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

Find an item nearest this position in the specified direction, starting from
the item after {\it start} or the beginning if {\it start} is -1.

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

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

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

\membersection{wxListCtrl::GetColumnWidth}\label{wxlistctrlgetcolumnwidth}

\constfunc{int}{GetColumnWidth}{\param{const 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}

Gets the edit control for editing labels.

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

\constfunc{wxImageList*}{GetImageList}{\param{const 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}}

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

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

\constfunc{long}{GetItemData}{\param{const long }{item}}

Gets the application-defined data associated with this item.

\membersection{wxListCtrl::GetItemPosition}\label{wxlistctrlgetitemposition}

\constfunc{bool}{GetItemPosition}{\param{const long }{item}, \param{wxPoint\& }{pos}}

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

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

\constfunc{bool}{GetItemRect}{\param{const long }{item}, \param{wxRect\& }{rect}, \param{const int }{code = wxLIST\_RECT\_BOUNDS}}

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

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

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

\constfunc{int}{GetItemState}{\param{const long }{item}, \param{const 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::GetItemCount}\label{wxlistctrlgetitemcount}

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

Returns the number of items in the list control.

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

\constfunc{int}{GetItemSpacing}{\param{bool }{isSmall}}

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::GetItemText}\label{wxlistctrlgetitemtext}

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

Gets the item text for this item.

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

\constfunc{long}{GetNextItem}{\param{const 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 {\it item}. {\it item} can be -1
to find the first item that matches the specified flags.

Returns the item or -1 if unsuccessful.

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

{\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::HitTest}\label{wxlistctrlhittest}

\func{long}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}

Determines which item (if any) is at the specified point,
giving details in {\it flags}. {\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}

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

\func{long}{InsertColumn}{\param{const 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{const long }{col}, \param{const wxString\& }{heading}, \param{const int }{format = wxLIST\_FORMAT\_LEFT},\rtfsp
\param{const int }{width = -1}}

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

\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{const long }{index}, \param{const wxString\& }{label}}

Inserts a string item.

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

Inserts an image item.

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

Insert an image/string item.

\membersection{wxListCtrl::ScrollList}\label{wxlistctrlscrolllist}

\func{bool}{ScrollList}{\param{const int }{dx}, \param{const 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.

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.

\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{const 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{const int }{col}, \param{const int }{width}}

Sets the column width (report view only).

{\it width} can be a width in pixels or wxLIST\_AUTOSIZE (-1) or wxLIST\_AUTOSIZE\_USEHEADER (-2).

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

\func{void}{SetImageList}{\param{wxImageList*}{ imageList}, \param{const 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).

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

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

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.}
\twocolitem{wxLIST\_STATE\_DROPHILITED}{The item is highlighted to receive a drop event.}
\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.}
\end{twocollist}

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

Sets a string field at a particular column.

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

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

Associates application-defined data with this item.

\membersection{wxListCtrl::SetItemImage}\label{wxlistctrlsetitemimage}

\func{bool}{SetItemImage}{\param{const long }{item}, \param{const int }{image}, \param{const 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.

\membersection{wxListCtrl::SetItemPosition}\label{wxlistctrlsetitemposition}

\func{bool}{SetItemPosition}{\param{const long }{item}, \param{const wxPoint\& }{pos}}

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

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

\func{bool}{SetItemState}{\param{const long }{item}, \param{const long }{state}, \param{const 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{const long }{item}, \param{const wxString\& }{text}}

Sets the item text for this item.

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

\func{void}{SetSingleStyle}{\param{const 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{const long }{style}}

Sets the whole window style.

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

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

Sorts the items in the list control.

fn is a function which takes 3 long arguments: item1, item2, data.

item1 is the long data associated with a first item (NOT the index).

item2 is the long data associated with a second item (NOT the index).

data is the same value as passed to SortItems.

The return value is a negative number if the first item should precede the second
item, a positive number of the second item should precede the first,
or zero if the two items are equivalent.

data is arbitrary data to be passed to the sort function.