X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a376adb6ee04c6f0d08cb4de43aa9d2d7f01daea..78cb09ec439962b53ba75fef814b9a3871412287:/docs/latex/wx/listctrl.tex diff --git a/docs/latex/wx/listctrl.tex b/docs/latex/wx/listctrl.tex index 5c6a4a11ca..ac0fdfb739 100644 --- a/docs/latex/wx/listctrl.tex +++ b/docs/latex/wx/listctrl.tex @@ -23,7 +23,7 @@ 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} and +\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 @@ -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.} @@ -672,6 +750,7 @@ The base class version always returns {\tt NULL}. \wxheading{See also} \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\ +\helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\ \helpref{OnGetItemText}{wxlistctrlongetitemtext} @@ -684,14 +763,33 @@ This function must be overloaded in the derived class for a control with (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} @@ -705,6 +803,7 @@ the given {\it column} for the specified {\tt item}. \helpref{SetItemCount}{wxlistctrlsetitemcount},\\ \helpref{OnGetItemImage}{wxlistctrlongetitemimage},\\ +\helpref{OnGetItemColumnImage}{wxlistctrlongetitemcolumnimage},\\ \helpref{OnGetItemAttr}{wxlistctrlongetitemattr} @@ -775,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}} @@ -886,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} @@ -899,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}} @@ -908,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}} @@ -915,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}} @@ -943,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. @@ -999,5 +1133,6 @@ 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.} +however, you may use a closure to achieve an effect similar to the +SortItems third parameter.} +