wxDataViewCtrl Class Reference
[Controls, wxDataViewCtrl Related Classes]

#include <wx/dataview.h>

Inheritance diagram for wxDataViewCtrl:

List of all members.

---

Detailed Description

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 wxDataViewTreeCtrl can be used.

A wxDataViewItem is used to represent a (visible) item in the control.

Unlike 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 wxDataViewModel and associate it with this control. Then you need to add a number of wxDataViewColumn to this control to define what each column shall display. Each wxDataViewColumn in turn owns 1 instance of a wxDataViewRenderer to render its cells. A number of standard renderers for rendering text, dates, images, toggle, a progress bar etc. are provided. Additionally, the user can write custom renderes deriving from wxDataViewCustomRenderer for displaying anything.

All data transfer from the control to the model and the user code is done through wxVariant which can be extended to support more data formats as necessary. Accordingly, all type information uses the strings returned from wxVariant::GetType.

Styles:

• wxDV_SINGLE:
  Single selection mode. This is the default.
• wxDV_MULTIPLE:
  Multiple selection mode.
• wxDV_ROW_LINES:
  Use alternating colours for rows if supported by platform and theme.
• wxDV_HORIZ_RULES:
  Display fine rules between row if supported.
• wxDV_VERT_RULES:
  Display fine rules between columns is supported.
• wxDV_VARIABLE_LINE_HEIGHT:
  Allow variable line heights. This can be inefficient when displaying large number of items.

Events:

The following event handler macros redirect the events to member function handlers 'func' with prototypes like:

void handlerFuncName(wxDataViewEvent& event)

Event macros:

• EVT_DATAVIEW_SELECTION_CHANGED(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
• EVT_DATAVIEW_ITEM_ACTIVATED(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
• EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
• EVT_DATAVIEW_ITEM_EDITING_DONE(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
• EVT_DATAVIEW_ITEM_COLLAPSING(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
• EVT_DATAVIEW_ITEM_COLLAPSED(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
• EVT_DATAVIEW_ITEM_EXPANDING(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
• EVT_DATAVIEW_ITEM_EXPANDED(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
• EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
• EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
• EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
• EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
• EVT_DATAVIEW_COLUMN_SORTED(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
• EVT_DATAVIEW_COLUMN_REORDERED(id, func):
  Process a wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.

Library:  wxAdvanced

Category:  Controls, wxDataViewCtrl Related Classes

Public Member Functions
	wxDataViewCtrl ()
	wxDataViewCtrl (wxWindow *parent, wxWindowID id, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=0, const wxValidator &validator=wxDefaultValidator)
virtual	~wxDataViewCtrl ()
virtual bool	AppendColumn (wxDataViewColumn *col)
virtual bool	PrependColumn (wxDataViewColumn *col)
virtual bool	InsertColumn (unsigned int pos, wxDataViewColumn *col)
virtual bool	AssociateModel (wxDataViewModel *model)
virtual bool	ClearColumns ()
void	ClearSelection ()
virtual void	Collapse (const wxDataViewItem &item)
bool	Create (wxWindow *parent, wxWindowID id, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=0, const wxValidator &validator=wxDefaultValidator)
virtual bool	DeleteColumn (const wxDataViewColumn *column)
void	EnsureVisible (const wxDataViewItem &item, const wxDataViewColumn *column=NULL)
virtual void	Expand (const wxDataViewItem &item)
virtual wxDataViewColumn *	GetColumn (unsigned int pos) const
virtual unsigned int	GetColumnCount () const
virtual int	GetColumnPosition (const wxDataViewColumn *column) const
wxDataViewColumn *	GetExpanderColumn () const
int	GetIndent () const
wxRect	GetItemRect (const wxDataViewItem &item, const wxDataViewColumn *col=NULL) const
wxDataViewModel *	GetModel ()
virtual wxDataViewItem	GetSelection () const
virtual int	GetSelections (wxDataViewItemArray &sel) const
virtual wxDataViewColumn *	GetSortingColumn () const
void	HitTest (const wxPoint &point, wxDataViewItem &item, wxDataViewColumn *&col) const
virtual bool	IsSelected (const wxDataViewItem &item) const
virtual void	Select (const wxDataViewItem &item)
virtual void	SelectAll ()
void	SetExpanderColumn (wxDataViewColumn *col)
void	SetIndent (int indent)
virtual void	SetSelections (const wxDataViewItemArray &sel)
virtual void	Unselect (const wxDataViewItem &item)
virtual void	UnselectAll ()
wxDataViewColumn *	AppendBitmapColumn (const wxString &label, unsigned int model_column, wxDataViewCellMode mode=wxDATAVIEW_CELL_INERT, int width=-1, wxAlignment align=wxALIGN_CENTER, int flags=wxDATAVIEW_COL_RESIZABLE)
wxDataViewColumn *	AppendBitmapColumn (const wxBitmap &label, unsigned int model_column, wxDataViewCellMode mode=wxDATAVIEW_CELL_INERT, int width=-1, wxAlignment align=wxALIGN_CENTER, int flags=wxDATAVIEW_COL_RESIZABLE)
wxDataViewColumn *	AppendDateColumn (const wxString &label, unsigned int model_column, wxDataViewCellMode mode=wxDATAVIEW_CELL_ACTIVATABLE, int width=-1, wxAlignment align=wxALIGN_CENTER, int flags=wxDATAVIEW_COL_RESIZABLE)
wxDataViewColumn *	AppendDateColumn (const wxBitmap &label, unsigned int model_column, wxDataViewCellMode mode=wxDATAVIEW_CELL_ACTIVATABLE, int width=-1, wxAlignment align=wxALIGN_CENTER, int flags=wxDATAVIEW_COL_RESIZABLE)
wxDataViewColumn *	AppendIconTextColumn (const wxString &label, unsigned int model_column, wxDataViewCellMode mode=wxDATAVIEW_CELL_INERT, int width=-1, wxAlignment align=wxALIGN_LEFT, int flags=wxDATAVIEW_COL_RESIZABLE)
wxDataViewColumn *	AppendIconTextColumn (const wxBitmap &label, unsigned int model_column, wxDataViewCellMode mode=wxDATAVIEW_CELL_INERT, int width=-1, wxAlignment align=wxALIGN_LEFT, int flags=wxDATAVIEW_COL_RESIZABLE)
wxDataViewColumn *	AppendProgressColumn (const wxString &label, unsigned int model_column, wxDataViewCellMode mode=wxDATAVIEW_CELL_INERT, int width=80, wxAlignment align=wxALIGN_CENTER, int flags=wxDATAVIEW_COL_RESIZABLE)
wxDataViewColumn *	AppendProgressColumn (const wxBitmap &label, unsigned int model_column, wxDataViewCellMode mode=wxDATAVIEW_CELL_INERT, int width=80, wxAlignment align=wxALIGN_CENTER, int flags=wxDATAVIEW_COL_RESIZABLE)
wxDataViewColumn *	AppendTextColumn (const wxString &label, unsigned int model_column, wxDataViewCellMode mode=wxDATAVIEW_CELL_INERT, int width=-1, wxAlignment align=wxALIGN_LEFT, int flags=wxDATAVIEW_COL_RESIZABLE)
wxDataViewColumn *	AppendTextColumn (const wxBitmap &label, unsigned int model_column, wxDataViewCellMode mode=wxDATAVIEW_CELL_INERT, int width=-1, wxAlignment align=wxALIGN_LEFT, int flags=wxDATAVIEW_COL_RESIZABLE)
wxDataViewColumn *	AppendToggleColumn (const wxString &label, unsigned int model_column, wxDataViewCellMode mode=wxDATAVIEW_CELL_INERT, int width=30, wxAlignment align=wxALIGN_CENTER, int flags=wxDATAVIEW_COL_RESIZABLE)
wxDataViewColumn *	AppendToggleColumn (const wxBitmap &label, unsigned int model_column, wxDataViewCellMode mode=wxDATAVIEW_CELL_INERT, int width=30, wxAlignment align=wxALIGN_CENTER, int flags=wxDATAVIEW_COL_RESIZABLE)

---

Constructor & Destructor Documentation

wxDataViewCtrl::wxDataViewCtrl

(

)

Default Constructor.

wxDataViewCtrl::wxDataViewCtrl	(	wxWindow *	parent,
		wxWindowID	id,
		const wxPoint &	pos = wxDefaultPosition,
		const wxSize &	size = wxDefaultSize,
		long	style = 0,
		const wxValidator &	validator = wxDefaultValidator
	)

Constructor. Calls Create().

virtual wxDataViewCtrl::~wxDataViewCtrl

(

)

[virtual]

Destructor.

---

Member Function Documentation

virtual bool wxDataViewCtrl::AppendColumn

(

wxDataViewColumn *

col

)

[virtual]

Appends a wxDataViewColumn to the control. Returns true on success. Note that there is a number of short cut methods which implicitly create a wxDataViewColumn and a wxDataViewRenderer for it (see below).

virtual bool wxDataViewCtrl::PrependColumn

(

wxDataViewColumn *

col

)

[virtual]

Prepends a wxDataViewColumn to the control. Returns true on success. Note that there is a number of short cut methods which implicitly create a wxDataViewColumn and a wxDataViewRenderer for it.

virtual bool wxDataViewCtrl::InsertColumn	(	unsigned int	pos,
		wxDataViewColumn *	col
	)			[virtual]

Inserts a wxDataViewColumn to the control. Returns true on success.

wxDataViewColumn* wxDataViewCtrl::AppendBitmapColumn	(	const wxString &	label,
		unsigned int	model_column,
		wxDataViewCellMode	mode = wxDATAVIEW_CELL_INERT,
		int	width = -1,
		wxAlignment	align = wxALIGN_CENTER,
		int	flags = wxDATAVIEW_COL_RESIZABLE
	)

Appends a column for rendering a bitmap. Returns the wxDataViewColumn created in the function or NULL on failure.

wxDataViewColumn* wxDataViewCtrl::AppendBitmapColumn	(	const wxBitmap &	label,
		unsigned int	model_column,
		wxDataViewCellMode	mode = wxDATAVIEW_CELL_INERT,
		int	width = -1,
		wxAlignment	align = wxALIGN_CENTER,
		int	flags = wxDATAVIEW_COL_RESIZABLE
	)

Appends a column for rendering a bitmap. Returns the wxDataViewColumn created in the function or NULL on failure.

wxDataViewColumn* wxDataViewCtrl::AppendDateColumn	(	const wxString &	label,
		unsigned int	model_column,
		wxDataViewCellMode	mode = wxDATAVIEW_CELL_ACTIVATABLE,
		int	width = -1,
		wxAlignment	align = wxALIGN_CENTER,
		int	flags = wxDATAVIEW_COL_RESIZABLE
	)

Appends a column for rendering a date. Returns the wxDataViewColumn created in the function or NULL on failure.

NB: The align parameter is applied to both the column header and the column renderer.

wxDataViewColumn* wxDataViewCtrl::AppendDateColumn	(	const wxBitmap &	label,
		unsigned int	model_column,
		wxDataViewCellMode	mode = wxDATAVIEW_CELL_ACTIVATABLE,
		int	width = -1,
		wxAlignment	align = wxALIGN_CENTER,
		int	flags = wxDATAVIEW_COL_RESIZABLE
	)

Appends a column for rendering a date. Returns the wxDataViewColumn created in the function or NULL on failure.

NB: The align parameter is applied to both the column header and the column renderer.

wxDataViewColumn* wxDataViewCtrl::AppendIconTextColumn	(	const wxString &	label,
		unsigned int	model_column,
		wxDataViewCellMode	mode = wxDATAVIEW_CELL_INERT,
		int	width = -1,
		wxAlignment	align = wxALIGN_LEFT,
		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 method uses the wxDataViewIconTextRenderer class.

NB: The align parameter is applied to both the column header and the column renderer.

wxDataViewColumn* wxDataViewCtrl::AppendIconTextColumn	(	const wxBitmap &	label,
		unsigned int	model_column,
		wxDataViewCellMode	mode = wxDATAVIEW_CELL_INERT,
		int	width = -1,
		wxAlignment	align = wxALIGN_LEFT,
		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 method uses the wxDataViewIconTextRenderer class.

NB: The align parameter is applied to both the column header and the column renderer.

wxDataViewColumn* wxDataViewCtrl::AppendProgressColumn	(	const wxString &	label,
		unsigned int	model_column,
		wxDataViewCellMode	mode = wxDATAVIEW_CELL_INERT,
		int	width = 80,
		wxAlignment	align = wxALIGN_CENTER,
		int	flags = wxDATAVIEW_COL_RESIZABLE
	)

Appends a column for rendering a progress indicator. Returns the wxDataViewColumn created in the function or NULL on failure.

NB: The align parameter is applied to both the column header and the column renderer.

wxDataViewColumn* wxDataViewCtrl::AppendProgressColumn	(	const wxBitmap &	label,
		unsigned int	model_column,
		wxDataViewCellMode	mode = wxDATAVIEW_CELL_INERT,
		int	width = 80,
		wxAlignment	align = wxALIGN_CENTER,
		int	flags = wxDATAVIEW_COL_RESIZABLE
	)

Appends a column for rendering a progress indicator. Returns the wxDataViewColumn created in the function or NULL on failure.

NB: The align parameter is applied to both the column header and the column renderer.

wxDataViewColumn* wxDataViewCtrl::AppendTextColumn	(	const wxString &	label,
		unsigned int	model_column,
		wxDataViewCellMode	mode = wxDATAVIEW_CELL_INERT,
		int	width = -1,
		wxAlignment	align = wxALIGN_LEFT,
		int	flags = wxDATAVIEW_COL_RESIZABLE
	)

Appends a column for rendering text. Returns the wxDataViewColumn created in the function or NULL on failure.

NB: The align parameter is applied to both the column header and the column renderer.

wxDataViewColumn* wxDataViewCtrl::AppendTextColumn	(	const wxBitmap &	label,
		unsigned int	model_column,
		wxDataViewCellMode	mode = wxDATAVIEW_CELL_INERT,
		int	width = -1,
		wxAlignment	align = wxALIGN_LEFT,
		int	flags = wxDATAVIEW_COL_RESIZABLE
	)

Appends a column for rendering text. Returns the wxDataViewColumn created in the function or NULL on failure.

NB: The align parameter is applied to both the column header and the column renderer.

wxDataViewColumn* wxDataViewCtrl::AppendToggleColumn	(	const wxString &	label,
		unsigned int	model_column,
		wxDataViewCellMode	mode = wxDATAVIEW_CELL_INERT,
		int	width = 30,
		wxAlignment	align = wxALIGN_CENTER,
		int	flags = wxDATAVIEW_COL_RESIZABLE
	)

Appends a column for rendering a toggle. Returns the wxDataViewColumn created in the function or NULL on failure.

NB: The align parameter is applied to both the column header and the column renderer.

wxDataViewColumn* wxDataViewCtrl::AppendToggleColumn	(	const wxBitmap &	label,
		unsigned int	model_column,
		wxDataViewCellMode	mode = wxDATAVIEW_CELL_INERT,
		int	width = 30,
		wxAlignment	align = wxALIGN_CENTER,
		int	flags = wxDATAVIEW_COL_RESIZABLE
	)

Appends a column for rendering a toggle. Returns the wxDataViewColumn created in the function or NULL on failure.

NB: The align parameter is applied to both the column header and the column renderer.

virtual bool wxDataViewCtrl::AssociateModel

(

wxDataViewModel *

model

)

[virtual]

Associates a wxDataViewModel with the control. This increases the reference count of the model by 1.

virtual bool wxDataViewCtrl::ClearColumns

(

)

[virtual]

Removes all columns.

void wxDataViewCtrl::ClearSelection

(

)

Unselects all rows.

virtual void wxDataViewCtrl::Collapse

(

const wxDataViewItem &

item

)

[virtual]

Collapses the item.

bool wxDataViewCtrl::Create	(	wxWindow *	parent,
		wxWindowID	id,
		const wxPoint &	pos = wxDefaultPosition,
		const wxSize &	size = wxDefaultSize,
		long	style = 0,
		const wxValidator &	validator = wxDefaultValidator
	)

Create the control. Useful for two step creation.

Reimplemented in wxDataViewTreeCtrl.

virtual bool wxDataViewCtrl::DeleteColumn

(

const wxDataViewColumn *

column

)

[virtual]

Deletes given column.

void wxDataViewCtrl::EnsureVisible	(	const wxDataViewItem &	item,
		const wxDataViewColumn *	column = NULL
	)

Call this to ensure that the given item is visible.

virtual void wxDataViewCtrl::Expand

(

const wxDataViewItem &

item

)

[virtual]

Expands the item.

virtual wxDataViewColumn* wxDataViewCtrl::GetColumn

(

unsigned int

pos

)

const [virtual]

Returns pointer to the column. pos refers to the position in the control which may change after reordering columns by the user.

virtual unsigned int wxDataViewCtrl::GetColumnCount

(

)

const [virtual]

Returns the number of columns.

virtual int wxDataViewCtrl::GetColumnPosition

(

const wxDataViewColumn *

column

)

const [virtual]

Returns the position of the column or -1 if not found in the control.

wxDataViewColumn* wxDataViewCtrl::GetExpanderColumn

(

)

const

Returns column containing the expanders.

int wxDataViewCtrl::GetIndent

(

)

const

Returns indentation.

wxRect wxDataViewCtrl::GetItemRect	(	const wxDataViewItem &	item,
		const wxDataViewColumn *	col = NULL
	)			const

Returns item rect.

wxDataViewModel* wxDataViewCtrl::GetModel

(

)

Returns pointer to the data model associated with the control (if any).

virtual wxDataViewItem wxDataViewCtrl::GetSelection

(

)

const [virtual]

Returns first selected item or an invalid item if none is selected.

virtual int wxDataViewCtrl::GetSelections

(

wxDataViewItemArray &

sel

)

const [virtual]

Fills sel with currently selected items and returns their number.

virtual wxDataViewColumn* wxDataViewCtrl::GetSortingColumn

(

)

const [virtual]

Returns the wxDataViewColumn currently responsible for sorting or NULL if none has been selected.

void wxDataViewCtrl::HitTest	(	const wxPoint &	point,
		wxDataViewItem &	item,
		wxDataViewColumn *&	col
	)			const

Hittest.

virtual bool wxDataViewCtrl::IsSelected

(

const wxDataViewItem &

item

)

const [virtual]

Return true if the item is selected.

virtual void wxDataViewCtrl::Select

(

const wxDataViewItem &

item

)

[virtual]

Select the given item.

virtual void wxDataViewCtrl::SelectAll

(

)

[virtual]

Select all items.

void wxDataViewCtrl::SetExpanderColumn

(

wxDataViewColumn *

col

)

Set which column shall contain the tree-like expanders.

void wxDataViewCtrl::SetIndent

(

int

indent

)

Sets the indendation.

virtual void wxDataViewCtrl::SetSelections

(

const wxDataViewItemArray &

sel

)

[virtual]

Sets the selection to the array of wxDataViewItems.

virtual void wxDataViewCtrl::Unselect

(

const wxDataViewItem &

item

)

[virtual]

Unselect the given item.

virtual void wxDataViewCtrl::UnselectAll

(

)

[virtual]

Unselect all item. This method only has effect if multiple selections are allowed.