X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/095e0f9148b3df0daee2adc84ba5b44d8f9d06ae..78cb09ec439962b53ba75fef814b9a3871412287:/docs/latex/wx/listctrl.tex diff --git a/docs/latex/wx/listctrl.tex b/docs/latex/wx/listctrl.tex index 1bc8a71a79..ac0fdfb739 100644 --- a/docs/latex/wx/listctrl.tex +++ b/docs/latex/wx/listctrl.tex @@ -38,6 +38,12 @@ Using many of wxListCtrl features is shown in the 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}\\ @@ -49,6 +55,10 @@ in \helpref{wxListEvent}{wxlistevent}. +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + \wxheading{Window styles} \twocolwidtha{7cm} @@ -105,6 +115,22 @@ functions that take a \helpref{wxListEvent}{wxlistevent} argument. \twocolitem{{\bf EVT\_LIST\_CACHE\_HINT(id, func)}}{Prepare cache for a virtual list control} \end{twocollist}% +\wxheading{Column ordering} + +In report view, the control has several columns which are identified by their +internal indices. By default, these indices correspond to their order on +screen, i.e. the column $0$ appears first (in the left-to-right or maybe +right-to-left if the current language uses this writing direction), the column +$1$ next and so on. However it is possible to reorder the columns visual order +using \helpref{SetColumnsOrder}{wxlistctrlsetcolumnsorder} method and the +user can also rearrange the columns interactively by dragging them. In this +case, the index of the column is not the same as its order and the functions +\helpref{GetColumnOrder}{wxlistctrlgetcolumnorder} and +\helpref{GetColumnIndexFromOrder}{wxlistctrlgetcolumnindexfromorder} should be +used to translate between them. + +Please notice that current column reordering is implemented only in wxMSW. + \wxheading{See also} \helpref{wxListCtrl overview}{wxlistctrloverview}, \helpref{wxListView}{wxlistview}, \helpref{wxListBox}{wxlistbox},\rtfsp @@ -204,7 +230,7 @@ Creates the list control. See \helpref{wxListCtrl::wxListCtrl}{wxlistctrlctor} f \func{bool}{DeleteAllItems}{} -Deletes all the items in the list control. +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 @@ -250,10 +276,12 @@ 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}} +\func{long}{FindItem}{\param{long }{start}, \param{const wxString\& }{str}, \param{bool }{partial = false}} Find an item whose label matches this string, starting from {\it start} or -the beginning if {\it start} is -1. +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}} @@ -309,6 +337,28 @@ Returns the number of columns. Gets the column width (report view only). +\membersection{wxListCtrl::GetColumnIndexFromOrder}\label{wxlistctrlgetcolumnindexfromorder} + +\constfunc{int}{GetColumnIndexFromOrder}{\param{int }{order}} + +Gets the column number by visual order index (report view only). + + +\membersection{wxListCtrl::GetColumnOrder}\label{wxlistctrlgetcolumnorder} + +\constfunc{int}{GetColumnOrder}{\param{int }{col}} + +Gets the column visual order index (valid in report view only). + + +\membersection{wxListCtrl::GetColumnsOrder}\label{wxlistctrlgetcolumnsorder} + +\constfunc{wxArrayInt}{GetColumnsOrder}{\void} + +Returns the array containing the orders of all columns. On error, an empty +array is returned. + + \membersection{wxListCtrl::GetCountPerPage}\label{wxlistctrlgetcountperpage} \constfunc{int}{GetCountPerPage}{\void} @@ -326,7 +376,8 @@ or small icon view). 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. +{\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} @@ -425,6 +476,25 @@ 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} @@ -554,7 +624,7 @@ 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}} +\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} @@ -576,6 +646,14 @@ if no item is at the specified point. 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.} @@ -796,6 +874,17 @@ will resize the column to the length of the header (Win32) or 80 pixels (other p In small or normal icon view, {\it col} must be -1, and the column width is set for all columns. +\membersection{wxListCtrl::SetColumnsOrder}\label{wxlistctrlsetcolumnsorder} + +\constfunc{bool}{SetColumnOrder}{\param{const wxArrayInt\& }{orders}} + +Sets the order of all columns at once. The \arg{orders} array must have the +same number elements as the number of columns and contain each position exactly +once. + +This function is valid in report view only. + + \membersection{wxListCtrl::SetImageList}\label{wxlistctrlsetimagelist} \func{void}{SetImageList}{\param{wxImageList*}{ imageList}, \param{int }{which}} @@ -907,6 +996,9 @@ from $0$ to {\it count}. Associates application-defined data with this item. +Notice that this function cannot be used to associate pointers with the control +items, use \helpref{SetItemPtrData}{wxlistctrlsetitemptrdata} instead. + \membersection{wxListCtrl::SetItemFont}\label{wxlistctrlsetitemfont} @@ -920,7 +1012,8 @@ Sets the item's font. \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. +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}} @@ -929,6 +1022,14 @@ image list associated with the list control. This form is deprecated: {\it selIm used. +\membersection{wxListCtrl::SetItemColumnImage}\label{wxlistctrlsetitemcolumnimage} + +\func{bool}{SetItemColumnImage}{\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}} @@ -936,6 +1037,18 @@ used. Sets the position of the item, in icon or small icon view. Windows only. +\membersection{wxListCtrl::SetItemPtrData}\label{wxlistctrlsetitemptrdata} + +\func{bool}{SetItemPtrData}{\param{long }{item}, \param{wxUIntPtr }{data}} + +Associates application-defined data with this item. The \arg{data} parameter may +be either an integer or a pointer cast to the \texttt{wxUIntPtr} type which is +guaranteed to be large enough to be able to contain all integer types and +pointers. + +\newsince{2.8.4} + + \membersection{wxListCtrl::SetItemState}\label{wxlistctrlsetitemstate} \func{bool}{SetItemState}{\param{long }{item}, \param{long }{state}, \param{long }{stateMask}} @@ -964,7 +1077,7 @@ The colour can be retrieved using \membersection{wxListCtrl::SetSingleStyle}\label{wxlistctrlsetsinglestyle} -\func{void}{SetSingleStyle}{\param{long }{style}, \param{const bool }{add = true}} +\func{void}{SetSingleStyle}{\param{long }{style}, \param{bool }{add = true}} Adds or removes a single window style.