Patches-1851591 ] dataview sample is crashing (under MSW)

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

diff --git a/docs/latex/wx/dataviewctrl.tex b/docs/latex/wx/dataviewctrl.tex
index 31e1cc289e3d9f60a104a8ff27b56d0efaba47eb..e960313f5f25048161f0c4e91a7b59d8bfe3a4ec 100644 (file)
--- a/docs/latex/wx/dataviewctrl.tex
+++ b/docs/latex/wx/dataviewctrl.tex
@@ -1,8 +1,11 @@
-
 \section{\class{wxDataViewCtrl}}\label{wxdataviewctrl}
 
 wxDataViewCtrl is a control to display data either
-in a tree like fashion or in a tabular form or both. 
+in a tree like fashion or in a tabular form or both.
+If you only need to display a simple tree structure
+with an API more like the older wxTreeCtrl class,
+then the specialized \helpref{wxDataViewTreeCtrl}{wxdataviewtreectrl}
+can be used.
 
 A \helpref{wxDataViewItem}{wxdataviewitem} is used
 to represent a (visible) item in the control.
@@ -34,6 +37,9 @@ from \helpref{wxVariant::GetType}{wxvariantgettype}.
 \begin{twocollist}\itemsep=0pt
 \twocolitem{\windowstyle{wxDV\_SINGLE}}{Single selection mode. This is the default.}
 \twocolitem{\windowstyle{wxDV\_MULTIPLE}}{Multiple selection mode.}
+\twocolitem{\windowstyle{wxDV\_ROW\_LINES}}{Use alternating colours for rows if supported by platform and theme.}
+\twocolitem{\windowstyle{wxDV\_HORIZ\_RULES}}{Display fine rules between row if supported.}
+\twocolitem{\windowstyle{wxDV\_VERT\_RULES}}{Display fine rules between columns is supported.}
 \end{twocollist}
 
 
@@ -46,8 +52,15 @@ macros to direct input to member functions that take a
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
 
-\twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_SELECTED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_SELECTED event.}
+\twocolitem{{\bf EVT\_DATAVIEW\_SELECTION\_CHANGED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_SELECTION\_CHANGED event.}
 \twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_ACTIVATED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_ACTIVATED event.}
+\twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_EDITING\_STARTED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_EDITING\_STARTED event.}
+\twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_EDITING\_DONE(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_EDITING\_DONE event.}
+\twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_COLLAPSING(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_COLLAPSING event.}
+\twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_COLLAPSED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_COLLAPSED event.}
+\twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_EXPANDING(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_EXPANDING event.}
+\twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_EXPANDED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_EXPANDED event.}
+\twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_VALUE\_CHANGED event.}
 \twocolitem{{\bf EVT\_DATAVIEW\_COLUMN\_HEADER\_CLICK(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_COLUMN\_HEADER\_CLICKED event.}
 \twocolitem{{\bf EVT\_DATAVIEW\_COLUMN\_HEADER\_RIGHT\_CLICK(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_COLUMN\_HEADER\_RIGHT\_CLICKED event.}
 \twocolitem{{\bf EVT\_DATAVIEW\_COLUMN\_HEADER\_SORTED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_COLUMN\_HEADER\_SORTED event.}
@@ -100,45 +113,55 @@ a \helpref{wxDataViewColumn}{wxdataviewcolumn} and a
 
 \membersection{wxDataViewCtrl::AppendBitmapColumn}\label{wxdataviewctrlappendbitmapcolumn}
 
-\func{wxDataViewColumn*}{AppendBitmapColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}}
+\func{wxDataViewColumn*}{AppendBitmapColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 
-\func{wxDataViewColumn*}{AppendBitmapColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}}
+\func{wxDataViewColumn*}{AppendBitmapColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 
 Appends a column for rendering a bitmap. Returns the wxDataViewColumn
 created in the function or NULL on failure.
 
 \membersection{wxDataViewCtrl::AppendDateColumn}\label{wxdataviewctrlappenddatecolumn}
 
-\func{wxDataViewColumn*}{AppendDateColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}, \param{int }{width = -1}}
+\func{wxDataViewColumn*}{AppendDateColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 
-\func{wxDataViewColumn*}{AppendDateColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}, \param{int }{width = -1}}
+\func{wxDataViewColumn*}{AppendDateColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 
 Appends a column for rendering a date. Returns the wxDataViewColumn
 created in the function or NULL on failure.
 
 \membersection{wxDataViewCtrl::AppendProgressColumn}\label{wxdataviewctrlappendprogresscolumn}
 
-\func{wxDataViewColumn*}{AppendProgressColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 80}}
+\func{wxDataViewColumn*}{AppendProgressColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 80}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 
-\func{wxDataViewColumn*}{AppendProgressColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 80}}
+\func{wxDataViewColumn*}{AppendProgressColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 80}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 
 Appends a column for rendering a progress indicator. Returns the wxDataViewColumn
 created in the function or NULL on failure.
 
+\membersection{wxDataViewCtrl::AppendIconTextColumn}\label{wxdataviewctrlappendicontextcolumn}
+
+\func{wxDataViewColumn*}{AppendIconTextColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_LEFT}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
+
+\func{wxDataViewColumn*}{AppendIconTextColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_LEFT}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
+
+Appends a column for rendering text with an icon. Returns the wxDataViewColumn
+created in the function or NULL on failure. This uses the 
+\helpref{wxDataViewIconTextRenderer}{wxdataviewicontextrenderer}.
+
 \membersection{wxDataViewCtrl::AppendTextColumn}\label{wxdataviewctrlappendtextcolumn}
 
-\func{wxDataViewColumn*}{AppendTextColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}}
+\func{wxDataViewColumn*}{AppendTextColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_LEFT}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 
-\func{wxDataViewColumn*}{AppendTextColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}}
+\func{wxDataViewColumn*}{AppendTextColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_LEFT}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 
 Appends a column for rendering text. Returns the wxDataViewColumn
 created in the function or NULL on failure.
 
 \membersection{wxDataViewCtrl::AppendToggleColumn}\label{wxdataviewctrlappendtogglecolumn}
 
-\func{wxDataViewColumn*}{AppendToggleColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 30}}
+\func{wxDataViewColumn*}{AppendToggleColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 30}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 
-\func{wxDataViewColumn*}{AppendToggleColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 30}}
+\func{wxDataViewColumn*}{AppendToggleColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 30}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 
 Appends a column for rendering a toggle. Returns the wxDataViewColumn
 created in the function or NULL on failure.
@@ -148,7 +171,7 @@ created in the function or NULL on failure.
 \func{virtual bool}{AssociateModel}{\param{wxDataViewModel* }{model}}
 
 Associates a \helpref{wxDataViewModel}{wxdataviewmodel} with the
-control. 
+control. This increases the reference count of the model by 1.
 
 \membersection{wxDataViewCtrl::Create}\label{wxdataviewctrlcreate}
 
@@ -168,24 +191,31 @@ Removes all columns.
 
 Unselects all rows.
 
+\membersection{wxDataViewCtrl::Collapse}\label{wxdataviewctrlcollapse}   
+
+\func{void}{Collapse}{\param{const wxDataViewItem \& }{item}}
+
+Collapses the item.    
+    
 \membersection{wxDataViewCtrl::DeleteColumn}\label{wxdataviewctrldeletecolumn}
 
-\func{virtual bool}{DeleteColumn}{\param{unsigned int }{pos}}
+\func{virtual bool}{DeleteColumn}{\param{const wxDataViewColumn* }{column}}
 
 Deletes given column.
 
-\membersection{wxDataViewCtrl::GetColumn}\label{wxdataviewctrlgetcolumn}
+\membersection{wxDataViewCtrl::Expand}\label{wxdataviewctrlexpand}   
 
-\constfunc{virtual wxDataViewColumn*}{GetColumn}{\param{unsigned int }{pos}}
+\func{void}{Expand}{\param{const wxDataViewItem \& }{item}}
 
-Returns pointer to the column.
+Expands the item.    
+    
+\membersection{wxDataViewCtrl::GetColumn}\label{wxdataviewctrlgetcolumn}
 
-\membersection{wxDataViewCtrl::GetModel}\label{wxdataviewctrlgetmodel}
+\constfunc{virtual wxDataViewColumn*}{GetColumn}{\param{unsigned int }{pos}}
 
-\constfunc{virtual wxDataViewModel*}{GetModel}{\void}
-
-Returns pointer to the data model associated with the
-control (if any).
+Returns pointer to the column. {\it pos} refers to the 
+position in the control which may change after reordering
+columns by the user.
 
 \membersection{wxDataViewCtrl::GetColumnCount}\label{wxdataviewctrlgetcolumncount}
 
@@ -193,15 +223,21 @@ control (if any).
 
 Returns the number of columns.
 
+\membersection{wxDataViewCtrl::GetColumnPosition}\label{wxdataviewctrlgetcolumnposition}
+
+\constfunc{virtual int}{GetColumnPosition}{\param{const wxDataViewColumn* }{column}}
+
+Returns the position of the column or -1 if not found in the control.
+
 \membersection{wxDataViewCtrl::EnsureVisible}\label{wxdataviewctrlensurevisible}
 
-\func{void}{EnsureVisible}{\param{const wxDataViewItem \& }{item}, \param{wxDataViewColumn* }{column = NULL}}
+\func{void}{EnsureVisible}{\param{const wxDataViewItem \& }{item}, \param{const wxDataViewColumn* }{column = NULL}}
 
 Call this to ensure that the given item is visible.
 
 \membersection{wxDataViewCtrl::GetExpanderColumn}\label{wxdataviewctrlgetexpandercolumn}
 
-\constfunc{unsigned int}{GetExpanderColumn}{\void}
+\constfunc{wxDataViewColumn *}{GetExpanderColumn}{\void}
 
 Returns column containing the expanders.
 
@@ -217,6 +253,13 @@ Returns indentation.
 
 Returns item rect.
 
+\membersection{wxDataViewCtrl::GetModel}\label{wxdataviewctrlgetmodel}
+
+\constfunc{virtual wxDataViewModel*}{GetModel}{\void}
+
+Returns pointer to the data model associated with the
+control (if any).
+
 \membersection{wxDataViewCtrl::GetSelection}\label{wxdataviewctrlgetselection}
 
 \constfunc{wxDataViewItem}{GetSelection}{\void}
@@ -230,9 +273,16 @@ Returns first selected item or an invalid item if none is selected.
 Fills {\it sel} with currently selected items and returns
 their number.
 
+\membersection{wxDataViewCtrl::GetSortingColumn}\label{wxdataviewctrlgetsortingcolumn}
+
+\constfunc{virtual wxDataViewColumn*}{GetSortingColumn}{\void}
+
+Returns the wxDataViewColumn currently responsible for sorting
+or NULL if none has been selected.
+
 \membersection{wxDataViewCtrl::HitTest}\label{wxdataviewctrlhittest}
 
-\constfunc{void}{HitTest}{\param{const wxPoint\& }{point}, \param{wxDataViewItem\& }{item}, \param{wxDataViewColumn *}{col}}
+\constfunc{void}{HitTest}{\param{const wxPoint\& }{point}, \param{wxDataViewItem\& }{item}, \param{wxDataViewColumn *\&}{col}}
 
 Hittest.
 
@@ -256,7 +306,7 @@ Select all items.
 
 \membersection{wxDataViewCtrl::SetExpanderColumn}\label{wxdataviewctrlsetexpandercolumn}
 
-\func{void}{SetExpanderColumn}{\param{unsigned int }{col}}
+\func{void}{SetExpanderColumn}{\param{wxDataViewColumn *}{col}}
 
 Set which column shall contain the tree-like expanders.