X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b6b9d5562cd4aaa36211831c1875366a4dface18..63779a3de18f273c04247d74cee65f2bc6baa8ba:/docs/latex/wx/dataviewctrl.tex diff --git a/docs/latex/wx/dataviewctrl.tex b/docs/latex/wx/dataviewctrl.tex index 5b357d31ca..e960313f5f 100644 --- a/docs/latex/wx/dataviewctrl.tex +++ b/docs/latex/wx/dataviewctrl.tex @@ -1,15 +1,19 @@ - \section{\class{wxDataViewCtrl}}\label{wxdataviewctrl} -This class and its documentation are work in progress and -certainly subject to change. +wxDataViewCtrl is a control to display data either +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. -wxDataViewCtrl is planned to be a control to display data either -in a tree like fashion or in a tabular form or both. Currently, -only the tabular form is implemented. wxDataViewCtrl doesn't -get its data from the user through virtual functions or events, -instead you need to write your own -\helpref{wxDataViewListModel}{wxdataviewlistmodel} and associate +Unlike \helpref{wxListCtrl}{wxlistctrl} wxDataViewCtrl doesn't +get its data from the user through virtual functions or by +setting it directly. Instead you need to write your own +\helpref{wxDataViewModel}{wxdataviewmodel} and associate it with this control. Then you need to add a number of \helpref{wxDataViewColumn}{wxdataviewcolumn} to this control to define what each column shall display. Each wxDataViewColumn @@ -27,17 +31,15 @@ be extended to support more data formats as necessary. Accordingly, all type information uses the strings returned from \helpref{wxVariant::GetType}{wxvariantgettype}. -So far, this control has only be implemented for GTK+ and -there are only barely working stubs for a generic implementation. -It is planned to implement the control natively under OS X -and use generic code under Windows (and elsewhere). - \wxheading{Window styles} \twocolwidtha{5cm} \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} @@ -50,23 +52,39 @@ macros to direct input to member functions that take a \twocolwidtha{7cm} \begin{twocollist}\itemsep=0pt -\twocolitem{{\bf EVT\_DATAVIEW\_ROW\_SELECTED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ROW\_SELECTED event.} -\twocolitem{{\bf EVT\_DATAVIEW\_ROW\_ACTIVATED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ROW\_ACTIVATED 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.} \end{twocollist} - \wxheading{Derived from} -\helpref{wxControl}{wxcontrol} +\helpref{wxControl}{wxcontrol}\\ +\helpref{wxWindow}{wxwindow}\\ +\helpref{wxEvtHandler}{wxevthandler}\\ +\helpref{wxObject}{wxobject} \wxheading{Include files} +\wxheading{Library} + +\helpref{wxAdv}{librarieslist} + + +\latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxDataViewCtrl::wxDataViewCtrl}\label{wxdataviewctrlwxdataviewctrl} @@ -86,59 +104,74 @@ Destructor. \func{virtual bool}{AppendColumn}{\param{wxDataViewColumn* }{col}} -Add a \helpref{wxDataViewColumn}{wxdataviewcolumn} to the control. Note -that there is a number of short cut methods which implicitly create -a \helpref{wxDataViewColumn}{wxdataviewcolumn} and a -\helpref{wxDataViewRenderer}{wxataviewrenderer} for it (see below). +Add a \helpref{wxDataViewColumn}{wxdataviewcolumn} to the control. Returns +{\it true} on success. +Note that there is a number of short cut methods which implicitly create +a \helpref{wxDataViewColumn}{wxdataviewcolumn} and a +\helpref{wxDataViewRenderer}{wxdataviewrenderer} for it (see below). \membersection{wxDataViewCtrl::AppendBitmapColumn}\label{wxdataviewctrlappendbitmapcolumn} -\func{bool}{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{bool}{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. +Appends a column for rendering a bitmap. Returns the wxDataViewColumn +created in the function or NULL on failure. \membersection{wxDataViewCtrl::AppendDateColumn}\label{wxdataviewctrlappenddatecolumn} -\func{bool}{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{bool}{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. +Appends a column for rendering a date. Returns the wxDataViewColumn +created in the function or NULL on failure. \membersection{wxDataViewCtrl::AppendProgressColumn}\label{wxdataviewctrlappendprogresscolumn} -\func{bool}{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}, \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. -\func{bool}{AppendProgressColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 80}} +\membersection{wxDataViewCtrl::AppendIconTextColumn}\label{wxdataviewctrlappendicontextcolumn} -Appends a column for rendering a progress indicator. +\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{bool}{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{bool}{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. +Appends a column for rendering text. Returns the wxDataViewColumn +created in the function or NULL on failure. \membersection{wxDataViewCtrl::AppendToggleColumn}\label{wxdataviewctrlappendtogglecolumn} -\func{bool}{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{bool}{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. +Appends a column for rendering a toggle. Returns the wxDataViewColumn +created in the function or NULL on failure. \membersection{wxDataViewCtrl::AssociateModel}\label{wxdataviewctrlassociatemodel} -\func{virtual bool}{AssociateModel}{\param{wxDataViewListModel* }{model}} +\func{virtual bool}{AssociateModel}{\param{wxDataViewModel* }{model}} -Associates a \helpref{wxDataViewListModel}{wxdataviewlistmodel} with the -control. In the future this should be changed to supporting any data -model including a to-be-written wxDataViewTreeModel. +Associates a \helpref{wxDataViewModel}{wxdataviewmodel} with the +control. This increases the reference count of the model by 1. \membersection{wxDataViewCtrl::Create}\label{wxdataviewctrlcreate} @@ -158,73 +191,147 @@ 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::Expand}\label{wxdataviewctrlexpand} + +\func{void}{Expand}{\param{const wxDataViewItem \& }{item}} + +Expands the item. + \membersection{wxDataViewCtrl::GetColumn}\label{wxdataviewctrlgetcolumn} -\func{virtual wxDataViewColumn*}{GetColumn}{\param{unsigned int }{pos}} +\constfunc{virtual wxDataViewColumn*}{GetColumn}{\param{unsigned int }{pos}} + +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} + +\constfunc{virtual unsigned int}{GetColumnCount}{\void} + +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{const wxDataViewColumn* }{column = NULL}} -Returns pointer to the column. +Call this to ensure that the given item is visible. + +\membersection{wxDataViewCtrl::GetExpanderColumn}\label{wxdataviewctrlgetexpandercolumn} + +\constfunc{wxDataViewColumn *}{GetExpanderColumn}{\void} + +Returns column containing the expanders. + +\membersection{wxDataViewCtrl::GetIndent}\label{wxdataviewctrlgetindent} + +\constfunc{int}{GetIndent}{\void} + +Returns indentation. + +\membersection{wxDataViewCtrl::GetItemRect}\label{wxdataviewctrlgetitemrect} + +\constfunc{wxRect}{GetItemRect}{\param{const wxDataViewItem\& }{item}, \param{const wxDataViewColumn *}{col = NULL}} + +Returns item rect. \membersection{wxDataViewCtrl::GetModel}\label{wxdataviewctrlgetmodel} -\func{virtual wxDataViewListModel*}{GetModel}{\void} +\constfunc{virtual wxDataViewModel*}{GetModel}{\void} Returns pointer to the data model associated with the control (if any). -\membersection{wxDataViewCtrl::GetNumberOfColumns}\label{wxdataviewctrlgetnumberofcolumns} +\membersection{wxDataViewCtrl::GetSelection}\label{wxdataviewctrlgetselection} -\func{virtual unsigned int}{GetNumberOfColumns}{\void} +\constfunc{wxDataViewItem}{GetSelection}{\void} -Returns the number of columns. +Returns first selected item or an invalid item if none is selected. -\membersection{wxDataViewCtrl::GetSelection}\label{wxdataviewctrlgetselection} +\membersection{wxDataViewCtrl::GetSelections}\label{wxdataviewctrlgetselections} -\constfunc{virtual int}{GetSelection}{\void} +\constfunc{int}{GetSelections}{\param{wxDataViewItemArray \& }{sel}} -Returns the index of the currently selected row. It will -return -1 if no row is selected and the index of the first -selected row if more than one row are selected. +Fills {\it sel} with currently selected items and returns +their number. -\membersection{wxDataViewCtrl::GetSelections}\label{wxdataviewctrlgetselections} +\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{virtual int}{GetSelections}{\param{wxArrayInt\& }{aSelections}} +\constfunc{void}{HitTest}{\param{const wxPoint\& }{point}, \param{wxDataViewItem\& }{item}, \param{wxDataViewColumn *\&}{col}} -Returns the number of selected rows and fills an array of int -with the indeces of the selected rows. +Hittest. \membersection{wxDataViewCtrl::IsSelected}\label{wxdataviewctrlisselected} -\constfunc{virtual bool}{IsSelected}{\param{unsigned int }{row}} +\constfunc{bool}{IsSelected}{\param{const wxDataViewItem \& }{item}} + +Return true if the item is selected. + +\membersection{wxDataViewCtrl::Select}\label{wxdataviewctrlselect} + +\func{void}{Select}{\param{const wxDataViewItem \& }{item}} -Returns {\it true} if the row is selected, {\it false} otherwise. +Select the given item. -\membersection{wxDataViewCtrl::SetSelection}\label{wxdataviewctrlsetselection} +\membersection{wxDataViewCtrl::SelectAll}\label{wxdataviewctrlselectall} -\func{virtual void}{SetSelection}{\param{int }{row}} +\func{void}{SelectAll}{\void} -Sets the selection. Use -1 to unselect all rows. +Select all items. -\membersection{wxDataViewCtrl::SetSelectionRange}\label{wxdataviewctrlsetselectionrange} +\membersection{wxDataViewCtrl::SetExpanderColumn}\label{wxdataviewctrlsetexpandercolumn} -\func{virtual void}{SetSelectionRange}{\param{unsigned int }{from}, \param{unsigned int }{to}} +\func{void}{SetExpanderColumn}{\param{wxDataViewColumn *}{col}} -Set a range of selection. +Set which column shall contain the tree-like expanders. + +\membersection{wxDataViewCtrl::SetIndent}\label{wxdataviewctrlsetindent} + +\func{void}{SetIndent}{\param{int }{indent}} + +Sets the indendation. \membersection{wxDataViewCtrl::SetSelections}\label{wxdataviewctrlsetselections} -\func{virtual void}{SetSelections}{\param{const wxArrayInt\& }{aSelections}} +\func{void}{SetSelections}{\param{const wxDataViewItemArray \& }{sel}} -Set the selection to the array of int. +Sets the selection to the array of wxDataViewItems. \membersection{wxDataViewCtrl::Unselect}\label{wxdataviewctrlunselect} -\func{virtual void}{Unselect}{\param{unsigned int }{row}} +\func{void}{Unselect}{\param{const wxDataViewItem \& }{item}} + +Unselect the given item. + +\membersection{wxDataViewCtrl::UnselectAll}\label{wxdataviewctrlunselectall} + +\func{void}{UnselectAll}{\void} -Unselect a particular row. +Unselect all item. This method only has effect if multiple +selections are allowed.