wx.dataview.DataViewCtrl¶

wx.dataview.DataViewCtrl 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 wx.TreeCtrl class, then the specialized wx.dataview.DataViewTreeCtrl can be used. Likewise, if you only want to display simple table structure you can use the specialized wx.dataview.DataViewListCtrl class. Both wx.dataview.DataViewTreeCtrl and wx.dataview.DataViewListCtrl can be used without defining your own wx.dataview.DataViewModel.

A wx.dataview.DataViewItem is used to represent a (visible) item in the control.

Unlike wx.ListCtrl, wx.dataview.DataViewCtrl doesn’t get its data from the user through virtual functions or by setting it directly. Instead you need to write your own wx.dataview.DataViewModel and associate it with this control. Then you need to add a number of wx.dataview.DataViewColumn to this control to define what each column shall display. Each wx.dataview.DataViewColumn in turn owns 1 instance of a wx.dataview.DataViewRenderer 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 renderers deriving from wx.dataview.DataViewCustomRenderer for displaying anything.

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

Window Styles¶

This class supports the following styles:

wx.dataview.DV_SINGLE: Single selection mode. This is the default.
wx.dataview.DV_MULTIPLE: Multiple selection mode.
wx.dataview.DV_ROW_LINES: Use alternating colours for rows if supported by platform and theme. Currently only supported by the native GTK and OS X implementations but not by the generic one.
wx.dataview.DV_HORIZ_RULES: Display the separator lines between rows.
wx.dataview.DV_VERT_RULES: Display the separator lines between columns.
wx.dataview.DV_VARIABLE_LINE_HEIGHT: Allow variable line heights. This can be inefficient when displaying large number of items.
wx.dataview.DV_NO_HEADER: Do not show column headers (which are shown by default).

Events Emitted by this Class¶

Handlers bound for the following event types will receive a wx.dataview.DataViewEvent parameter.

EVT_DATAVIEW_SELECTION_CHANGED: Process a wxEVT_DATAVIEW_SELECTION_CHANGED event.
EVT_DATAVIEW_ITEM_ACTIVATED: Process a wxEVT_DATAVIEW_ITEM_ACTIVATED event. This event is triggered by double clicking an item or pressing some special key (usually “Enter”) when it is focused.
EVT_DATAVIEW_ITEM_START_EDITING: Process a wxEVT_DATAVIEW_ITEM_START_EDITING event. This event can be vetoed in order to prevent editing on an item by item basis.
EVT_DATAVIEW_ITEM_EDITING_STARTED: Process a wxEVT_DATAVIEW_ITEM_EDITING_STARTED event.
EVT_DATAVIEW_ITEM_EDITING_DONE: Process a wxEVT_DATAVIEW_ITEM_EDITING_DONE event.
EVT_DATAVIEW_ITEM_COLLAPSING: Process a wxEVT_DATAVIEW_ITEM_COLLAPSING event.
EVT_DATAVIEW_ITEM_COLLAPSED: Process a wxEVT_DATAVIEW_ITEM_COLLAPSED event.
EVT_DATAVIEW_ITEM_EXPANDING: Process a wxEVT_DATAVIEW_ITEM_EXPANDING event.
EVT_DATAVIEW_ITEM_EXPANDED: Process a wxEVT_DATAVIEW_ITEM_EXPANDED event.
EVT_DATAVIEW_ITEM_VALUE_CHANGED: Process a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED event.
EVT_DATAVIEW_ITEM_CONTEXT_MENU: Process a wxEVT_DATAVIEW_ITEM_CONTEXT_MENU event generated when the user right clicks inside the control. Notice that this menu is generated even if the click didn’t occur on any valid item, in this case wx.dataview.DataViewEvent.GetItem simply returns an invalid item.
EVT_DATAVIEW_COLUMN_HEADER_CLICK: Process a wxEVT_DATAVIEW_COLUMN_HEADER_CLICK event.
EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK: Process a wxEVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK event. Notice that currently this event is not generated in the native OS X versions of the control.
EVT_DATAVIEW_COLUMN_SORTED: Process a wxEVT_DATAVIEW_COLUMN_SORTED event.
EVT_DATAVIEW_COLUMN_REORDERED: Process a wxEVT_DATAVIEW_COLUMN_REORDERED event.
EVT_DATAVIEW_ITEM_BEGIN_DRAG: Process a wxEVT_DATAVIEW_ITEM_BEGIN_DRAG event.
EVT_DATAVIEW_ITEM_DROP_POSSIBLE: Process a wxEVT_DATAVIEW_ITEM_DROP_POSSIBLE event.
EVT_DATAVIEW_ITEM_DROP: Process a wxEVT_DATAVIEW_ITEM_DROP event.

Notice that this control doesn’t allow to process generic mouse events such as: wxEVT_LEFT_DOWN in all ports (notably it doesn’t work in wxGTK). If you need to handle any mouse events not covered by the ones above, consider using a custom renderer for the cells that must handle them.

Class Hierarchy¶

Inheritance diagram for class DataViewCtrl:

Control Appearance¶

wxMSW¶

wxMAC¶

wxGTK¶

Known Subclasses¶

wx.dataview.DataViewListCtrl, wx.dataview.DataViewTreeCtrl

Methods Summary¶

`__init__`	Default Constructor.
`AppendBitmapColumn`	Appends a column for rendering a bitmap.
`AppendColumn`	Appends a wx.dataview.DataViewColumn to the control.
`AppendDateColumn`	Appends a column for rendering a date.
`AppendIconTextColumn`	Appends a column for rendering text with an icon.
`AppendProgressColumn`	Appends a column for rendering a progress indicator.
`AppendTextColumn`	Appends a column for rendering text.
`AppendToggleColumn`	Appends a column for rendering a toggle.
`_AssociateModel`	Associates a wx.dataview.DataViewModel with the control.
`AssociateModel`	Associates a `DataViewModel` with the control.
`ClearColumns`	Removes all columns.
`Collapse`	Collapses the item.
`Create`	Create the control.
`DeleteColumn`	Deletes given column.
`EditItem`	Programmatically starts editing given cell of item.
`EnableDragSource`	Enable drag operations using the given format.
`EnableDropTarget`	Enable drop operations using the given format.
`EnsureVisible`	Call this to ensure that the given item is visible.
`Expand`	Expands the item.
`ExpandAncestors`	Expands all ancestors of the item.
`GetClassDefaultAttributes`
`GetColumn`	Returns pointer to the column.
`GetColumnCount`	Returns the number of columns.
`GetColumnPosition`	Returns the position of the column or -1 if not found in the control.
`GetColumns`	Returns a list of column objects.
`GetCurrentColumn`	Returns the column that currently has focus.
`GetCurrentItem`	Returns the currently focused item.
`GetExpanderColumn`	Returns column containing the expanders.
`GetIndent`	Returns indentation.
`GetItemRect`	Returns item rectangle.
`GetModel`	Returns pointer to the data model associated with the control (if any).
`GetSelectedItemsCount`	Returns the number of currently selected items.
`GetSelection`	Returns first selected item or an invalid item if none is selected.
`GetSelections`	Returns a list of the currently selected items.
`GetSortingColumn`	Returns the wx.dataview.DataViewColumn currently responsible for sorting or `None` if none has been selected.
`HasSelection`	Returns `True` if any items are currently selected.
`HitTest`	HitTest(point) . (item, col)
`InsertColumn`	Inserts a wx.dataview.DataViewColumn to the control.
`IsExpanded`	Return `True` if the item is expanded.
`IsSelected`	Return `True` if the item is selected.
`PrependBitmapColumn`	Prepends a column for rendering a bitmap.
`PrependColumn`	Prepends a wx.dataview.DataViewColumn to the control.
`PrependDateColumn`	Prepends a column for rendering a date.
`PrependIconTextColumn`	Prepends a column for rendering text with an icon.
`PrependProgressColumn`	Prepends a column for rendering a progress indicator.
`PrependTextColumn`	Prepends a column for rendering text.
`PrependToggleColumn`	Prepends a column for rendering a toggle.
`Select`	Select the given item.
`SelectAll`	Select all items.
`SetCurrentItem`	Changes the currently focused item.
`SetExpanderColumn`	Set which column shall contain the tree-like expanders.
`SetIndent`	Sets the indentation.
`SetRowHeight`	Sets the row height.
`SetSelections`	Sets the selection to the array of DataViewItems.
`Unselect`	Unselect the given item.
`UnselectAll`	Unselect all item.

Properties Summary¶

`ColumnCount`	See `GetColumnCount`
`Columns`	See `GetColumns`
`CurrentColumn`	See `GetCurrentColumn`
`CurrentItem`	See `GetCurrentItem` and `SetCurrentItem`
`ExpanderColumn`	See `GetExpanderColumn` and `SetExpanderColumn`
`Indent`	See `GetIndent` and `SetIndent`
`Model`	See `GetModel`
`SelectedItemsCount`	See `GetSelectedItemsCount`
`Selection`	See `GetSelection`
`Selections`	See `GetSelections` and `SetSelections`
`SortingColumn`	See `GetSortingColumn`

Class API¶

class wx.dataview.DataViewCtrl(Control)¶

Possible constructors:

DataViewCtrl()

DataViewCtrl(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize,
             style=0, validator=DefaultValidator, name=DataViewCtrlNameStr)

DataViewCtrl is a control to display data either in a tree like fashion or in a tabular form or both.

Methods¶

__init__(self, *args, **kw)¶

Overloaded Implementations:

__init__ (self)

Default Constructor.

__init__ (self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=DataViewCtrlNameStr)

Constructor.

Calls Create .

Parameters

parent (wx.Window) –
id (wx.WindowID) –
pos (wx.Point) –
size (wx.Size) –
style (long) –
validator (wx.Validator) –
name (string) –

AppendBitmapColumn(self, *args, **kw)¶

Appends a column for rendering a bitmap.

Returns the wx.dataview.DataViewColumn created in the function or None on failure.

Overloaded Implementations:

AppendBitmapColumn (self, label, model_column, mode=DATAVIEW_CELL_INERT, width=-1, align=ALIGN_CENTER, flags=DATAVIEW_COL_RESIZABLE)

Parameters

label (string) –
model_column (int) –
mode (DataViewCellMode) –
width (int) –
align (Alignment) –
flags (int) –

Return type

wx.dataview.DataViewColumn

AppendBitmapColumn (self, label, model_column, mode=DATAVIEW_CELL_INERT, width=-1, align=ALIGN_CENTER, flags=DATAVIEW_COL_RESIZABLE)

Parameters

label (wx.Bitmap) –
model_column (int) –
mode (DataViewCellMode) –
width (int) –
align (Alignment) –
flags (int) –

Return type

wx.dataview.DataViewColumn

AppendColumn(self, col)¶

Appends a wx.dataview.DataViewColumn to the control.

Returns True on success.

Note that there is a number of short cut methods which implicitly create a wx.dataview.DataViewColumn and a wx.dataview.DataViewRenderer for it (see below).

Parameters: col (wx.dataview.DataViewColumn) –
Return type: bool

AppendDateColumn(self, *args, **kw)¶

Appends a column for rendering a date.

Returns the wx.dataview.DataViewColumn created in the function or None on failure.

Note

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

Overloaded Implementations:

AppendDateColumn (self, label, model_column, mode=DATAVIEW_CELL_ACTIVATABLE, width=-1, align=ALIGN_NOT, flags=DATAVIEW_COL_RESIZABLE)

Parameters

label (string) –
model_column (int) –
mode (DataViewCellMode) –
width (int) –
align (Alignment) –
flags (int) –

Return type

wx.dataview.DataViewColumn

AppendDateColumn (self, label, model_column, mode=DATAVIEW_CELL_ACTIVATABLE, width=-1, align=ALIGN_NOT, flags=DATAVIEW_COL_RESIZABLE)

Parameters

label (wx.Bitmap) –
model_column (int) –
mode (DataViewCellMode) –
width (int) –
align (Alignment) –
flags (int) –

Return type

wx.dataview.DataViewColumn

AppendIconTextColumn(self, *args, **kw)¶

Appends a column for rendering text with an icon.

Returns the wx.dataview.DataViewColumn created in the function or None on failure. This method uses the wx.dataview.DataViewIconTextRenderer class.

Note

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

Overloaded Implementations:

AppendIconTextColumn (self, label, model_column, mode=DATAVIEW_CELL_INERT, width=-1, align=ALIGN_NOT, flags=DATAVIEW_COL_RESIZABLE)

Parameters

label (string) –
model_column (int) –
mode (DataViewCellMode) –
width (int) –
align (Alignment) –
flags (int) –

Return type

wx.dataview.DataViewColumn

AppendIconTextColumn (self, label, model_column, mode=DATAVIEW_CELL_INERT, width=-1, align=ALIGN_NOT, flags=DATAVIEW_COL_RESIZABLE)

Parameters

label (wx.Bitmap) –
model_column (int) –
mode (DataViewCellMode) –
width (int) –
align (Alignment) –
flags (int) –

Return type

wx.dataview.DataViewColumn

AppendProgressColumn(self, *args, **kw)¶

Appends a column for rendering a progress indicator.

Returns the wx.dataview.DataViewColumn created in the function or None on failure.

Note

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

Overloaded Implementations:

AppendProgressColumn (self, label, model_column, mode=DATAVIEW_CELL_INERT, width=80, align=ALIGN_CENTER, flags=DATAVIEW_COL_RESIZABLE)

Parameters

label (string) –
model_column (int) –
mode (DataViewCellMode) –
width (int) –
align (Alignment) –
flags (int) –

Return type

wx.dataview.DataViewColumn

AppendProgressColumn (self, label, model_column, mode=DATAVIEW_CELL_INERT, width=80, align=ALIGN_CENTER, flags=DATAVIEW_COL_RESIZABLE)

Parameters

label (wx.Bitmap) –
model_column (int) –
mode (DataViewCellMode) –
width (int) –
align (Alignment) –
flags (int) –

Return type

wx.dataview.DataViewColumn

AppendTextColumn(self, *args, **kw)¶

Appends a column for rendering text.

Returns the wx.dataview.DataViewColumn created in the function or None on failure.

Note

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

Overloaded Implementations:

AppendTextColumn (self, label, model_column, mode=DATAVIEW_CELL_INERT, width=-1, align=ALIGN_NOT, flags=DATAVIEW_COL_RESIZABLE)

Parameters

label (string) –
model_column (int) –
mode (DataViewCellMode) –
width (int) –
align (Alignment) –
flags (int) –

Return type

wx.dataview.DataViewColumn

AppendTextColumn (self, label, model_column, mode=DATAVIEW_CELL_INERT, width=-1, align=ALIGN_NOT, flags=DATAVIEW_COL_RESIZABLE)

Parameters

label (wx.Bitmap) –
model_column (int) –
mode (DataViewCellMode) –
width (int) –
align (Alignment) –
flags (int) –

Return type

wx.dataview.DataViewColumn

AppendToggleColumn(self, *args, **kw)¶

Appends a column for rendering a toggle.

Returns the wx.dataview.DataViewColumn created in the function or None on failure.

Note

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

Overloaded Implementations:

AppendToggleColumn (self, label, model_column, mode=DATAVIEW_CELL_INERT, width=30, align=ALIGN_CENTER, flags=DATAVIEW_COL_RESIZABLE)

Parameters

label (string) –
model_column (int) –
mode (DataViewCellMode) –
width (int) –
align (Alignment) –
flags (int) –

Return type

wx.dataview.DataViewColumn

AppendToggleColumn (self, label, model_column, mode=DATAVIEW_CELL_INERT, width=30, align=ALIGN_CENTER, flags=DATAVIEW_COL_RESIZABLE)

Parameters

label (wx.Bitmap) –
model_column (int) –
mode (DataViewCellMode) –
width (int) –
align (Alignment) –
flags (int) –

Return type

wx.dataview.DataViewColumn

_AssociateModel(self, model)¶

Associates a wx.dataview.DataViewModel with the control.

This increases the reference count of the model by 1.

Parameters: model (wx.dataview.DataViewModel) –
Return type: bool

AssociateModel(self, model)¶: Associates a DataViewModel with the control. Ownership of the model object is passed to C++, however it is reference counted so it can be shared with other views.

ClearColumns(self)¶

Removes all columns.

Return type: bool

Collapse(self, item)¶

Collapses the item.

Parameters: item (wx.dataview.DataViewItem) –

Create(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=DataViewCtrlNameStr)¶

Create the control.

Useful for two step creation.

Parameters

parent (wx.Window) –
id (wx.WindowID) –
pos (wx.Point) –
size (wx.Size) –
style (long) –
validator (wx.Validator) –
name (string) –

Return type

bool

DeleteColumn(self, column)¶

Deletes given column.

Parameters: column (wx.dataview.DataViewColumn) –
Return type: bool

EditItem(self, item, column)¶

Programmatically starts editing given cell of item.

Doesn’t do anything if the item or this column is not editable.

Parameters

item (wx.dataview.DataViewItem) –
column (wx.dataview.DataViewColumn) –

New in version 2.9.4.

Note

Currently not implemented in OSX/Carbon.

EnableDragSource(self, format)¶

Enable drag operations using the given format.

Parameters: format (wx.DataFormat) –
Return type: bool

EnableDropTarget(self, format)¶

Enable drop operations using the given format.

Parameters: format (wx.DataFormat) –
Return type: bool

EnsureVisible(self, item, column=None)¶

Call this to ensure that the given item is visible.

Parameters

item (wx.dataview.DataViewItem) –
column (wx.dataview.DataViewColumn) –

Expand(self, item)¶

Expands the item.

Parameters: item (wx.dataview.DataViewItem) –

ExpandAncestors(self, item)¶

Expands all ancestors of the item.

This method also ensures that the item itself as well as all ancestor items have been read from the model by the control.

Parameters: item (wx.dataview.DataViewItem) –

static GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)¶

Parameters: variant (WindowVariant) –
Return type: VisualAttributes

GetColumn(self, pos)¶

Returns pointer to the column.

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

Parameters: pos (int) –
Return type: wx.dataview.DataViewColumn

GetColumnCount(self)¶

Returns the number of columns.

Return type: int

GetColumnPosition(self, column)¶

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

Parameters: column (wx.dataview.DataViewColumn) –
Return type: int

GetColumns(self)¶: Returns a list of column objects.

GetCurrentColumn(self)¶

Returns the column that currently has focus.

If the focus is set to individual cell within the currently focused item (as opposed to being on the item as a whole), then this is the column that the focus is on.

Returns None if no column currently has focus.

Return type: wx.dataview.DataViewColumn

New in version 2.9.4.

Properties¶

ColumnCount¶: See GetColumnCount

Columns¶: See GetColumns

CurrentColumn¶: See GetCurrentColumn

CurrentItem¶: See GetCurrentItem and SetCurrentItem

ExpanderColumn¶: See GetExpanderColumn and SetExpanderColumn

Indent¶: See GetIndent and SetIndent

Model¶: See GetModel

SelectedItemsCount¶: See GetSelectedItemsCount

Selection¶: See GetSelection

Selections¶: See GetSelections and SetSelections

SortingColumn¶: See GetSortingColumn

Navigation

wx.dataview.DataViewCtrl¶

Window Styles¶

Events Emitted by this Class¶

Class Hierarchy¶

Control Appearance¶

Known Subclasses¶

Methods Summary¶

Properties Summary¶

Class API¶

Methods¶

Properties¶