// Name: dataview.h
// Purpose: interface of wxDataView* classes
// Author: wxWidgets team
-// RCS-ID: $Id$
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
@return
@true if this item should be enabled, @false otherwise.
- @note Currently disabling items is fully implemented only for the
- native control implementation in wxOSX/Cocoa and wxGTK.
- This feature is only partially supported in the generic
- version (used by wxMSW) and not supported by the wxOSX/Carbon
+ @note Currently disabling items is not supported by the wxOSX/Carbon
implementation.
@since 2.9.2
bool HasValue(const wxDataViewItem& item, unsigned col) const;
/**
- Override this to indicate of @a item is a container, i.e. if
+ Override this to indicate of @a item is a container, i.e.\ if
it can have child items.
*/
virtual bool IsContainer(const wxDataViewItem& item) const = 0;
virtual bool ValueChanged(const wxDataViewItem& item,
unsigned int col);
+
+ virtual bool IsListModel() const;
+ virtual bool IsVirtualListModel() const;
+
protected:
/**
/**
Destructor.
*/
- virtual ~wxDataViewIndexListModel();
+ virtual ~wxDataViewListModel();
/**
Compare method that sorts the items by their index.
*/
int Compare(const wxDataViewItem& item1,
const wxDataViewItem& item2,
- unsigned int column, bool ascending);
+ unsigned int column, bool ascending) const;
/**
Override this to indicate that the row has special font attributes.
/**
Returns the number of items (or rows) in the list.
*/
- unsigned int GetCount() const;
-
- /**
- Returns the wxDataViewItem at the given @e row.
- */
- wxDataViewItem GetItem(unsigned int row) const;
+ unsigned int GetCount() const = 0;
/**
Returns the position of given @e item.
*/
- unsigned int GetRow(const wxDataViewItem& item) const;
+ unsigned int GetRow(const wxDataViewItem& item) const = 0;
/**
Override this to allow getting values from the model.
*/
virtual void GetValueByRow(wxVariant& variant, unsigned int row,
- unsigned int col) const = 0;
+ unsigned int col) const = 0;
+
+ /**
+ Called in order to set a value in the model.
+ */
+ virtual bool SetValueByRow(const wxVariant& variant, unsigned int row,
+ unsigned int col) = 0;
+};
+
+
+/**
+ @class wxDataViewIndexListModel
+
+ wxDataViewIndexListModel is a specialized data model which lets you address
+ an item by its position (row) rather than its wxDataViewItem (which you can
+ obtain from this class).
+ This model also provides its own wxDataViewIndexListModel::Compare
+ method which sorts the model's data by the index.
+
+ This model is not a virtual model since the control stores each wxDataViewItem.
+ Use wxDataViewVirtualListModel if you need to display millions of items or
+ have other reason to use a virtual control.
+
+ @see wxDataViewListModel for the API.
+
+ @library{wxadv}
+ @category{dvc}
+*/
+
+class wxDataViewIndexListModel : public wxDataViewListModel
+{
+public:
+ /**
+ Constructor.
+ */
+ wxDataViewIndexListModel(unsigned int initial_size = 0);
+
+ /**
+ Returns the wxDataViewItem at the given @e row.
+ */
+ wxDataViewItem GetItem(unsigned int row) const;
/**
Call this after if the data has to be read again from the model.
*/
void RowsDeleted(const wxArrayInt& rows);
- /**
- Called in order to set a value in the model.
- */
- virtual bool SetValueByRow(const wxVariant& variant, unsigned int row,
- unsigned int col) = 0;
-};
-
-
-/**
- @class wxDataViewIndexListModel
-
- wxDataViewIndexListModel is a specialized data model which lets you address
- an item by its position (row) rather than its wxDataViewItem (which you can
- obtain from this class).
- This model also provides its own wxDataViewIndexListModel::Compare
- method which sorts the model's data by the index.
-
- This model is not a virtual model since the control stores each wxDataViewItem.
- Use wxDataViewVirtualListModel if you need to display millions of items or
- have other reason to use a virtual control.
-
- @see wxDataViewListModel for the API.
-
- @library{wxadv}
- @category{dvc}
-*/
-
-class wxDataViewIndexListModel : public wxDataViewListModel
-{
-public:
- /**
- Constructor.
- */
- wxDataViewIndexListModel(unsigned int initial_size = 0);
-
};
/**
*/
wxDataViewVirtualListModel(unsigned int initial_size = 0);
+ /**
+ Returns the wxDataViewItem at the given @e row.
+ */
+ wxDataViewItem GetItem(unsigned int row) const;
+
+ /**
+ Call this after if the data has to be read again from the model.
+ This is useful after major changes when calling the methods below
+ (possibly thousands of times) doesn't make sense.
+ */
+ void Reset(unsigned int new_size);
+
+ /**
+ Call this after a row has been appended to the model.
+ */
+ void RowAppended();
+
+ /**
+ Call this after a row has been changed.
+ */
+ void RowChanged(unsigned int row);
+
+ /**
+ Call this after a row has been deleted.
+ */
+ void RowDeleted(unsigned int row);
+
+ /**
+ Call this after a row has been inserted at the given position.
+ */
+ void RowInserted(unsigned int before);
+
+ /**
+ Call this after a row has been prepended to the model.
+ */
+ void RowPrepended();
+
+ /**
+ Call this after a value has been changed.
+ */
+ void RowValueChanged(unsigned int row, unsigned int col);
+
+ /**
+ Call this after rows have been deleted.
+ The array will internally get copied and sorted in descending order so
+ that the rows with the highest position will be deleted first.
+ */
+ void RowsDeleted(const wxArrayInt& rows);
+
};
*/
void SetColour(const wxColour& colour);
+ /**
+ Call this to set the background colour to use.
+
+ Currently this attribute is only supported in the generic version of
+ wxDataViewCtrl and ignored by the native GTK+ and OS X implementations.
+
+ @since 2.9.4
+ */
+ void SetBackgroundColour(const wxColour& colour);
+
/**
Call this to indicate that the item shall be displayed in italic text.
*/
void SetItalic(bool set);
+
+
+ /**
+ Returns true if the colour property has been set.
+ */
+ bool HasColour() const;
+
+ /**
+ Returns this attribute's colour.
+ */
+ const wxColour& GetColour() const;
+
+ /**
+ Returns true if any property affecting the font has been set.
+ */
+ bool HasFont() const;
+
+ /**
+ Returns value of the bold property.
+ */
+ bool GetBold() const;
+
+ /**
+ Returns value of the italics property.
+ */
+ bool GetItalic() const;
+
+ /**
+ Returns true if the background colour property has been set.
+ */
+ bool HasBackgroundColour() const;
+
+ /**
+ Returns the colour to be used for the background.
+ */
+ const wxColour& GetBackgroundColour() const;
+
+ /**
+ Returns true if none of the properties have been set.
+ */
+ bool IsDefault() const;
+
+ /**
+ Return the font based on the given one with this attribute applied to it.
+ */
+ wxFont GetEffectiveFont(const wxFont& font) const;
};
};
+// ----------------------------------------------------------------------------
+// wxDataViewCtrl flags
+// ----------------------------------------------------------------------------
+
+// size of a wxDataViewRenderer without contents:
+#define wxDVC_DEFAULT_RENDERER_SIZE 20
+
+// the default width of new (text) columns:
+#define wxDVC_DEFAULT_WIDTH 80
+
+// the default width of new toggle columns:
+#define wxDVC_TOGGLE_DEFAULT_WIDTH 30
+
+// the default minimal width of the columns:
+#define wxDVC_DEFAULT_MINWIDTH 30
+
+// The default alignment of wxDataViewRenderers is to take
+// the alignment from the column it owns.
+#define wxDVR_DEFAULT_ALIGNMENT -1
+
+#define wxDV_SINGLE 0x0000 // for convenience
+#define wxDV_MULTIPLE 0x0001 // can select multiple items
+
+#define wxDV_NO_HEADER 0x0002 // column titles not visible
+#define wxDV_HORIZ_RULES 0x0004 // light horizontal rules between rows
+#define wxDV_VERT_RULES 0x0008 // light vertical rules between columns
+
+#define wxDV_ROW_LINES 0x0010 // alternating colour in rows
+#define wxDV_VARIABLE_LINE_HEIGHT 0x0020 // variable line height
+
+// events
+
+wxEventType wxEVT_DATAVIEW_SELECTION_CHANGED;
+
+wxEventType wxEVT_DATAVIEW_ITEM_ACTIVATED;
+wxEventType wxEVT_DATAVIEW_ITEM_COLLAPSING;
+wxEventType wxEVT_DATAVIEW_ITEM_COLLAPSED;
+wxEventType wxEVT_DATAVIEW_ITEM_EXPANDING;
+wxEventType wxEVT_DATAVIEW_ITEM_EXPANDED;
+wxEventType wxEVT_DATAVIEW_ITEM_START_EDITING;
+wxEventType wxEVT_DATAVIEW_ITEM_EDITING_STARTED;
+wxEventType wxEVT_DATAVIEW_ITEM_EDITING_DONE;
+wxEventType wxEVT_DATAVIEW_ITEM_VALUE_CHANGED;
+
+wxEventType wxEVT_DATAVIEW_ITEM_CONTEXT_MENU;
+
+wxEventType wxEVT_DATAVIEW_COLUMN_HEADER_CLICK;
+wxEventType wxEVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK;
+wxEventType wxEVT_DATAVIEW_COLUMN_SORTED;
+wxEventType wxEVT_DATAVIEW_COLUMN_REORDERED;
+wxEventType wxEVT_DATAVIEW_CACHE_HINT;
+
+wxEventType wxEVT_DATAVIEW_ITEM_BEGIN_DRAG;
+wxEventType wxEVT_DATAVIEW_ITEM_DROP_POSSIBLE;
+wxEventType wxEVT_DATAVIEW_ITEM_DROP;
/**
@class wxDataViewCtrl
Currently only supported by the native GTK and OS X implementations
but not by the generic one.
@style{wxDV_HORIZ_RULES}
- Display fine rules between row if supported.
+ Display the separator lines between rows.
@style{wxDV_VERT_RULES}
- Display fine rules between columns is supported.
+ Display the separator lines between columns.
@style{wxDV_VARIABLE_LINE_HEIGHT}
Allow variable line heights.
This can be inefficient when displaying large number of items.
@beginEventEmissionTable{wxDataViewEvent}
@event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
+ Process a @c wxEVT_DATAVIEW_SELECTION_CHANGED event.
@event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
+ Process a @c 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.
@event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event. This
+ Process a @c wxEVT_DATAVIEW_ITEM_START_EDITING event. This
event can be vetoed in order to prevent editing on an item by item
- basis. Still experimental.
+ basis.
@event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
+ Process a @c wxEVT_DATAVIEW_ITEM_EDITING_STARTED event.
@event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
+ Process a @c wxEVT_DATAVIEW_ITEM_EDITING_DONE event.
@event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
+ Process a @c wxEVT_DATAVIEW_ITEM_COLLAPSING event.
@event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
+ Process a @c wxEVT_DATAVIEW_ITEM_COLLAPSED event.
@event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
+ Process a @c wxEVT_DATAVIEW_ITEM_EXPANDING event.
@event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
+ Process a @c wxEVT_DATAVIEW_ITEM_EXPANDED event.
@event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
+ Process a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED event.
@event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
+ Process a @c 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 wxDataViewEvent::GetItem() simply returns an
+ invalid item.
@event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
+ Process a @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICK event.
@event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
+ Process a @c wxEVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK event.
+ Notice that currently this event is not generated in the native OS X
+ versions of the control.
@event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
+ Process a @c wxEVT_DATAVIEW_COLUMN_SORTED event.
@event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
+ Process a @c wxEVT_DATAVIEW_COLUMN_REORDERED event.
@event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
+ Process a @c wxEVT_DATAVIEW_ITEM_BEGIN_DRAG event.
@event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
+ Process a @c wxEVT_DATAVIEW_ITEM_DROP_POSSIBLE event.
@event{EVT_DATAVIEW_ITEM_DROP(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
+ Process a @c wxEVT_DATAVIEW_ITEM_DROP event.
@endEventTable
+ Notice that this control doesn't allow to process generic mouse events such
+ as @c 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.
+
@library{wxadv}
@category{ctrl,dvc}
- @appearance{dataviewctrl.png}
+ @appearance{dataviewctrl}
*/
class wxDataViewCtrl : public wxControl
{
*/
virtual ~wxDataViewCtrl();
+ /**
+ Create the control. Useful for two step creation.
+ */
+ bool Create(wxWindow* parent, wxWindowID id,
+ const wxPoint& pos = wxDefaultPosition,
+ const wxSize& size = wxDefaultSize,
+ long style = 0,
+ const wxValidator& validator = wxDefaultValidator,
+ const wxString& name = wxDataViewCtrlNameStr);
+
/**
Appends a wxDataViewColumn to the control. Returns @true on success.
int flags = wxDATAVIEW_COL_RESIZABLE);
//@}
+ //@{
+ /**
+ Prepends a column for rendering a bitmap. Returns the wxDataViewColumn
+ created in the function or @NULL on failure.
+ */
+ wxDataViewColumn* PrependBitmapColumn(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* PrependBitmapColumn(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 date. Returns the wxDataViewColumn
int flags = wxDATAVIEW_COL_RESIZABLE);
//@}
+ //@{
+ /**
+ Prepends a column for rendering a date. Returns the wxDataViewColumn
+ created in the function or @NULL on failure.
+
+ @note The @a align parameter is applied to both the column header and
+ the column renderer.
+ */
+ wxDataViewColumn* PrependDateColumn(const wxString& label,
+ unsigned int model_column,
+ wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
+ int width = -1,
+ wxAlignment align = wxALIGN_NOT,
+ int flags = wxDATAVIEW_COL_RESIZABLE);
+ wxDataViewColumn* PrependDateColumn(const wxBitmap& label,
+ unsigned int model_column,
+ wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
+ int width = -1,
+ wxAlignment align = wxALIGN_NOT,
+ int flags = wxDATAVIEW_COL_RESIZABLE);
+ //@}
+
//@{
/**
Appends a column for rendering text with an icon. Returns the wxDataViewColumn
int flags = wxDATAVIEW_COL_RESIZABLE);
//@}
+ //@{
+ /**
+ Prepends 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.
+
+ @note The @a align parameter is applied to both the column header and
+ the column renderer.
+ */
+ wxDataViewColumn* PrependIconTextColumn(const wxString& label,
+ unsigned int model_column,
+ wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
+ int width = -1,
+ wxAlignment align = wxALIGN_NOT,
+ int flags = wxDATAVIEW_COL_RESIZABLE);
+ wxDataViewColumn* PrependIconTextColumn(const wxBitmap& label,
+ unsigned int model_column,
+ wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
+ int width = -1,
+ wxAlignment align = wxALIGN_NOT,
+ int flags = wxDATAVIEW_COL_RESIZABLE);
+ //@}
+
//@{
/**
Appends a column for rendering a progress indicator. Returns the
int flags = wxDATAVIEW_COL_RESIZABLE);
//@}
+ //@{
+ /**
+ Prepends a column for rendering a progress indicator. Returns the
+ wxDataViewColumn created in the function or @NULL on failure.
+
+ @note The @a align parameter is applied to both the column header and
+ the column renderer.
+ */
+ wxDataViewColumn* PrependProgressColumn(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* PrependProgressColumn(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 text. Returns the wxDataViewColumn
int flags = wxDATAVIEW_COL_RESIZABLE);
//@}
+ //@{
+ /**
+ Prepends a column for rendering text. Returns the wxDataViewColumn
+ created in the function or @NULL on failure.
+
+ @note The @a align parameter is applied to both the column header and
+ the column renderer.
+ */
+ wxDataViewColumn* PrependTextColumn(const wxString& label,
+ unsigned int model_column,
+ wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
+ int width = -1,
+ wxAlignment align = wxALIGN_NOT,
+ int flags = wxDATAVIEW_COL_RESIZABLE);
+ wxDataViewColumn* PrependTextColumn(const wxBitmap& label,
+ unsigned int model_column,
+ wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
+ int width = -1,
+ wxAlignment align = wxALIGN_NOT,
+ int flags = wxDATAVIEW_COL_RESIZABLE);
+ //@}
+
//@{
/**
Appends a column for rendering a toggle. Returns the wxDataViewColumn
int flags = wxDATAVIEW_COL_RESIZABLE);
//@}
+ //@{
+ /**
+ Prepends a column for rendering a toggle. Returns the wxDataViewColumn
+ created in the function or @NULL on failure.
+
+ @note The @a align parameter is applied to both the column header and
+ the column renderer.
+ */
+ wxDataViewColumn* PrependToggleColumn(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* PrependToggleColumn(const wxBitmap& label,
+ unsigned int model_column,
+ wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
+ int width = 30,
+ wxAlignment align = wxALIGN_CENTER,
+ int flags = wxDATAVIEW_COL_RESIZABLE);
+ //@}
+
/**
Associates a wxDataViewModel with the control.
This increases the reference count of the model by 1.
virtual void Collapse(const wxDataViewItem& item);
/**
- Create the control. Useful for two step creation.
+ Deletes given column.
*/
- bool Create(wxWindow* parent, wxWindowID id,
- const wxPoint& pos = wxDefaultPosition,
- const wxSize& size = wxDefaultSize,
- long style = 0,
- const wxValidator& validator = wxDefaultValidator,
- const wxString& name = wxDataViewCtrlNameStr);
+ virtual bool DeleteColumn(wxDataViewColumn* column);
/**
- Deletes given column.
+ Programmatically starts editing given cell of @a item.
+
+ Doesn't do anything if the item or this column is not editable.
+
+ @note Currently not implemented in wxOSX/Carbon.
+
+ @since 2.9.4
*/
- virtual bool DeleteColumn(wxDataViewColumn* column);
+ virtual void EditItem(const wxDataViewItem& item, const wxDataViewColumn *column);
/**
Enable drag operations using the given @a format.
item may be selected or not but under OS X the current item is always
selected.
- @see SetCurrentItem()
+ @see SetCurrentItem(), GetCurrentColumn()
@since 2.9.2
*/
wxDataViewItem GetCurrentItem() const;
+ /**
+ 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 NULL if no column currently has focus.
+
+ @see GetCurrentItem()
+
+ @since 2.9.4
+ */
+ wxDataViewColumn *GetCurrentColumn() const;
+
/**
Returns indentation.
*/
int GetIndent() const;
/**
- Returns item rect.
+ Returns item rectangle.
+
+ This method is currently not implemented at all in wxGTK and only
+ implemented for non-@NULL @a col argument in wxOSX. It is fully
+ implemented in the generic version of the control.
+
+ @param item
+ A valid item.
+ @param col
+ If non-@NULL, the rectangle returned corresponds to the
+ intersection of the item with the specified column. If @NULL, the
+ rectangle spans all the columns.
*/
virtual wxRect GetItemRect(const wxDataViewItem& item,
const wxDataViewColumn* col = NULL) const;
*/
virtual void SetSelections(const wxDataViewItemArray& sel);
- /**
- Programmatically starts editing the given item on the given column.
- Currently not implemented on wxOSX Carbon.
- @since 2.9.2
- */
-
- virtual void StartEditor(const wxDataViewItem & item, unsigned int column);
-
/**
Unselect the given item.
*/
/**
Called by owning model.
+
+ @return Always return @true from this function in derived classes.
*/
virtual bool ItemAdded(const wxDataViewItem& parent,
const wxDataViewItem& item) = 0;
/**
Called by owning model.
+
+ @return Always return @true from this function in derived classes.
*/
virtual bool ItemChanged(const wxDataViewItem& item) = 0;
/**
Called by owning model.
+
+ @return Always return @true from this function in derived classes.
*/
virtual bool ItemDeleted(const wxDataViewItem& parent,
const wxDataViewItem& item) = 0;
/**
Called by owning model.
+
+ @return Always return @true from this function in derived classes.
*/
virtual bool ItemsAdded(const wxDataViewItem& parent,
const wxDataViewItemArray& items);
/**
Called by owning model.
+
+ @return Always return @true from this function in derived classes.
*/
virtual bool ItemsChanged(const wxDataViewItemArray& items);
/**
Called by owning model.
+
+ @return Always return @true from this function in derived classes.
*/
virtual bool ItemsDeleted(const wxDataViewItem& parent,
const wxDataViewItemArray& items);
/**
Called by owning model.
+
+ @return Always return @true from this function in derived classes.
*/
virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col) = 0;
};
*/
enum wxDataViewCellMode
{
+ /**
+ The cell only displays information and cannot be manipulated or
+ otherwise interacted with in any way.
+
+ Note that this doesn't mean that the row being drawn can't be selected,
+ just that a particular element of it cannot be individually modified.
+ */
wxDATAVIEW_CELL_INERT,
/**
- Indicates that the user can double click the cell and something will
- happen (e.g. a window for editing a date will pop up).
+ Indicates that the cell can be @em activated by clicking it or using
+ keyboard.
+
+ Activating a cell is an alternative to showing inline editor when the
+ value can be edited in a simple way that doesn't warrant full editor
+ control. The most typical use of cell activation is toggling the
+ checkbox in wxDataViewToggleRenderer; others would be e.g. an embedded
+ volume slider or a five-star rating column.
+
+ The exact means of activating a cell are platform-dependent, but they
+ are usually similar to those used for inline editing of values.
+ Typically, a cell would be activated by Space or Enter keys or by left
+ mouse click.
+
+ @note Do not confuse this with item activation in wxDataViewCtrl
+ and the wxEVT_DATAVIEW_ITEM_ACTIVATED event. That one is
+ used for activating the item (or, to put it differently, the
+ entire row) similarly to analogous messages in wxTreeCtrl and
+ wxListCtrl, and the effect differs (play a song, open a file
+ etc.). Cell activation, on the other hand, is all about
+ interacting with the individual cell.
+
+ @see wxDataViewCustomRenderer::ActivateCell()
*/
wxDATAVIEW_CELL_ACTIVATABLE,
/**
- Indicates that the user can edit the data in-place, i.e. an control
- will show up after a slow click on the cell. This behaviour is best
- known from changing the filename in most file managers etc.
+ Indicates that the user can edit the data in-place in an inline editor
+ control that will show up when the user wants to edit the cell.
+
+ A typical example of this behaviour is changing the filename in a file
+ managers.
+
+ Editing is typically triggered by slowly double-clicking the cell or by
+ a platform-dependent keyboard shortcut (F2 is typical on Windows, Space
+ and/or Enter is common elsewhere and supported on Windows too).
+
+ @see wxDataViewCustomRenderer::CreateEditorCtrl()
*/
wxDATAVIEW_CELL_EDITABLE
};
- wxDataViewSpinRenderer.
- wxDataViewChoiceRenderer.
- Additionally, the user can write own renderers by deriving from
+ Additionally, the user can write their own renderers by deriving from
wxDataViewCustomRenderer.
The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted
editing process finished.
*/
virtual bool Validate(wxVariant& value);
+
+
+ virtual bool HasEditorCtrl() const;
+ virtual wxWindow* CreateEditorCtrl(wxWindow * parent,
+ wxRect labelRect,
+ const wxVariant& value);
+ virtual bool GetValueFromEditorCtrl(wxWindow * editor,
+ wxVariant& value);
+ virtual bool StartEditing( const wxDataViewItem &item, wxRect labelRect );
+ virtual void CancelEditing();
+ virtual bool FinishEditing();
+ wxWindow *GetEditorCtrl();
+
+protected:
+ wxDataViewCtrl* GetView() const;
};
/**
- @class wxDataViewChoiceRenderer
+ A wxDataViewCtrl renderer using wxChoice control and values of strings in
+ it.
This class is used by wxDataViewCtrl to render choice controls.
It stores a string so that SetValue() and GetValue() operate
on a variant holding a string.
+ @see wxDataViewChoiceByIndexRenderer
+
@library{wxadv}
@category{dvc}
*/
Returns the choice referred to by index.
*/
wxString GetChoice(size_t index) const;
-
+
/**
Returns all choices.
*/
};
+/**
+ A wxDataViewCtrl renderer using wxChoice control and indexes into it.
+
+ Unlike its base wxDataViewChoiceRenderer class, this one stores the choice
+ index, i.e. an @c int, in the variant used by its SetValue() and
+ GetValue().
+
+ @library{wxadv}
+ @category{dvc}
+*/
+class wxDataViewChoiceByIndexRenderer : public wxDataViewChoiceRenderer
+{
+public:
+ /**
+ The ctor.
+ */
+ wxDataViewChoiceByIndexRenderer( const wxArrayString &choices,
+ wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
+ int alignment = wxDVR_DEFAULT_ALIGNMENT );
+};
+
+
/**
@class wxDataViewDateRenderer
*/
wxDataViewCustomRenderer(const wxString& varianttype = "string",
wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
- int align = -1, bool no_init = false);
+ int align = wxDVR_DEFAULT_ALIGNMENT);
/**
Destructor.
virtual ~wxDataViewCustomRenderer();
/**
- Override this to react to double clicks or ENTER.
- This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
+ Override this to react to cell @em activation. Activating a cell is an
+ alternative to showing inline editor when the value can be edited in a
+ simple way that doesn't warrant full editor control. The most typical
+ use of cell activation is toggling the checkbox in
+ wxDataViewToggleRenderer; others would be e.g. an embedded volume
+ slider or a five-star rating column.
+
+ The exact means of activating a cell are platform-dependent, but they
+ are usually similar to those used for inline editing of values.
+ Typically, a cell would be activated by Space or Enter keys or by left
+ mouse click.
+
+ This method will only be called if the cell has the
+ wxDATAVIEW_CELL_ACTIVATABLE mode.
+
+ @param cell
+ Coordinates of the activated cell's area.
+ @param model
+ The model to manipulate in response.
+ @param item
+ Activated item.
+ @param col
+ Activated column of @a item.
+ @param mouseEvent
+ If the activation was triggered by mouse click, contains the
+ corresponding event. Is @NULL otherwise (for keyboard activation).
+ Mouse coordinates are adjusted to be relative to the cell.
+
+ @since 2.9.3
+
+ @note Do not confuse this method with item activation in wxDataViewCtrl
+ and the wxEVT_DATAVIEW_ITEM_ACTIVATED event. That one is
+ used for activating the item (or, to put it differently, the
+ entire row) similarly to analogous messages in wxTreeCtrl and
+ wxListCtrl, and the effect differs (play a song, open a file
+ etc.). Cell activation, on the other hand, is all about
+ interacting with the individual cell.
+
+ @see CreateEditorCtrl()
*/
- virtual bool Activate( const wxRect& cell,
- wxDataViewModel* model,
- const wxDataViewItem & item,
- unsigned int col );
+ virtual bool ActivateCell(const wxRect& cell,
+ wxDataViewModel* model,
+ const wxDataViewItem & item,
+ unsigned int col,
+ const wxMouseEvent *mouseEvent);
/**
Override this to create the actual editor control once editing
is about to start.
- @a parent is the parent of the editor control, @a labelRect indicates the
- position and size of the editor control and @a value is its initial value:
+ This method will only be called if the cell has the
+ wxDATAVIEW_CELL_EDITABLE mode. Editing is typically triggered by slowly
+ double-clicking the cell or by a platform-dependent keyboard shortcut
+ (F2 is typical on Windows, Space and/or Enter is common elsewhere and
+ supported on Windows too).
+
+ @param parent
+ The parent of the editor control.
+ @param labelRect
+ Indicates the position and size of the editor control. The control
+ should be created in place of the cell and @a labelRect should be
+ respected as much as possible.
+ @param value
+ Initial value of the editor.
+
+ An example:
@code
{
long l = value;
labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
}
@endcode
+
+ @see ActivateCell()
*/
virtual wxWindow* CreateEditorCtrl(wxWindow* parent,
wxRect labelRect,
virtual bool HasEditorCtrl() const;
/**
- Override this to react to a left click.
- This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
+ Override this to react to a left click. This method will only be
+ called in @c wxDATAVIEW_CELL_ACTIVATABLE mode. This method is
+ deprecated, please use ActivateCell instead.
*/
- virtual bool LeftClick( const wxPoint& cursor,
- const wxRect& cell,
+ virtual bool LeftClick( wxPoint cursor,
+ wxRect cell,
wxDataViewModel * model,
const wxDataViewItem & item,
unsigned int col );
+ /**
+ Override this to react to the activation of a cell. This method is
+ deprecated, please use ActivateCell instead.
+ */
+ virtual bool Activate(wxRect cell,
+ wxDataViewModel * model,
+ const wxDataViewItem & item,
+ unsigned int col);
+
+
/**
Override this to render the cell.
Before this is called, wxDataViewRenderer::SetValue was called
wxDataViewModel* model,
const wxDataViewItem & item,
unsigned int col);
+
+protected:
+ /**
+ Helper for GetSize() implementations, respects attributes.
+ */
+ wxSize GetTextExtent(const wxString& str) const;
};
@library{wxadv}
@category{ctrl,dvc}
+
+ @since 2.9.0
*/
class wxDataViewListCtrl: public wxDataViewCtrl
{
Appends a column to the control and additionally appends a
column to the store with the type string.
*/
- virtual void AppendColumn( wxDataViewColumn *column );
+ virtual bool AppendColumn( wxDataViewColumn *column );
/**
Appends a column to the control and additionally appends a
Inserts a column to the control and additionally inserts a
column to the store with the type string.
*/
- virtual void InsertColumn( unsigned int pos, wxDataViewColumn *column );
+ virtual bool InsertColumn( unsigned int pos, wxDataViewColumn *column );
/**
Inserts a column to the control and additionally inserts a
Prepends a column to the control and additionally prepends a
column to the store with the type string.
*/
- virtual void PrependColumn( wxDataViewColumn *column );
+ virtual bool PrependColumn( wxDataViewColumn *column );
/**
Prepends a column to the control and additionally prepends a
/**
Appends an item (=row) to the control and store.
*/
- void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
+ void AppendItem( const wxVector<wxVariant> &values, wxUIntPtr data = NULL );
/**
Prepends an item (=row) to the control and store.
*/
- void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
+ void PrependItem( const wxVector<wxVariant> &values, wxUIntPtr data = NULL );
/**
Inserts an item (=row) to the control and store.
*/
- void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
+ void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxUIntPtr data = NULL );
/**
Delete the row at position @a row.
*/
void DeleteAllItems();
+ /**
+ Returns the number of items (=rows) in the control
+
+ @since 2.9.4
+ */
+ unsigned int GetItemCount() const;
+
+ /**
+ Returns the client data associated with the item.
+
+ @see SetItemData()
+
+ @since 2.9.4
+ */
+ wxUIntPtr GetItemData(const wxDataViewItem& item) const;
+
/**
Sets the value in the store and update the control.
*/
*/
bool GetToggleValue( unsigned int row, unsigned int col ) const;
+ /**
+ Associates a client data pointer with the given item.
+
+ Notice that the control does @e not take ownership of the pointer for
+ compatibility with wxListCtrl. I.e. it will @e not delete the pointer
+ (if it is a pointer and not a number) itself, it is up to you to do it.
+
+ @see GetItemData()
+
+ @since 2.9.4
+ */
+ void SetItemData(const wxDataViewItem& item, wxUIntPtr data);
+
//@}
};
@library{wxadv}
@category{ctrl,dvc}
- @appearance{dataviewtreectrl.png}
+
+ @since 2.9.0
+
+ @appearance{dataviewtreectrl}
*/
class wxDataViewTreeCtrl : public wxDataViewCtrl
{
in number and type. No (default) values are filled in
automatically.
*/
- void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
+ void AppendItem( const wxVector<wxVariant> &values, wxUIntPtr data = NULL );
/**
Prepends an item (=row) and fills it with @a values.
in number and type. No (default) values are filled in
automatically.
*/
- void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
+ void PrependItem( const wxVector<wxVariant> &values, wxUIntPtr data = NULL );
/**
Inserts an item (=row) and fills it with @a values.
in number and type. No (default) values are filled in
automatically.
*/
- void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
+ void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxUIntPtr data = NULL );
/**
Delete the item (=row) at position @a pos.
*/
void DeleteAllItems();
+ /**
+ Returns the number of items (=rows) in the control
+
+ @since 2.9.4
+ */
+ unsigned int GetItemCount() const;
+
+ /**
+ Returns the client data associated with the item.
+
+ @see SetItemData()
+
+ @since 2.9.4
+ */
+ wxUIntPtr GetItemData(const wxDataViewItem& item) const;
+
/**
Overridden from wxDataViewModel
*/
*/
virtual wxString GetColumnType( unsigned int col ) const;
+ /**
+ Sets the client data associated with the item.
+
+ Notice that this class does @e not take ownership of the passed in
+ pointer and will not delete it.
+
+ @see GetItemData()
+
+ @since 2.9.4
+ */
+ void SetItemData(const wxDataViewItem& item, wxUIntPtr data);
+
/**
Overridden from wxDataViewIndexListModel
*/
@beginEventTable{wxDataViewEvent}
@event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
+ Process a @c wxEVT_DATAVIEW_SELECTION_CHANGED event.
@event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
+ Process a @c wxEVT_DATAVIEW_ITEM_ACTIVATED event.
@event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
+ Process a @c wxEVT_DATAVIEW_ITEM_EDITING_STARTED event.
@event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
+ Process a @c wxEVT_DATAVIEW_ITEM_EDITING_DONE event.
@event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
+ Process a @c wxEVT_DATAVIEW_ITEM_COLLAPSING event.
@event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
+ Process a @c wxEVT_DATAVIEW_ITEM_COLLAPSED event.
@event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
+ Process a @c wxEVT_DATAVIEW_ITEM_EXPANDING event.
@event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
+ Process a @c wxEVT_DATAVIEW_ITEM_EXPANDED event.
@event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
+ Process a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED event.
@event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
+ Process a @c wxEVT_DATAVIEW_ITEM_CONTEXT_MENU event.
@event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
+ Process a @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICK event.
@event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
+ Process a @c wxEVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK event.
@event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
+ Process a @c wxEVT_DATAVIEW_COLUMN_SORTED event.
@event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
+ Process a @c wxEVT_DATAVIEW_COLUMN_REORDERED event.
+ Currently this even is only generated when using the native OSX
+ version.
@event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
+ Process a @c wxEVT_DATAVIEW_ITEM_BEGIN_DRAG event.
@event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
+ Process a @c wxEVT_DATAVIEW_ITEM_DROP_POSSIBLE event.
@event{EVT_DATAVIEW_ITEM_DROP(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
+ Process a @c wxEVT_DATAVIEW_ITEM_DROP event.
@event{EVT_DATAVIEW_CACHE_HINT(id, func)}
- Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
+ Process a @c wxEVT_DATAVIEW_CACHE_HINT event.
@endEventTable
@library{wxadv}
/**
Can be used to determine whether the new value is going to be accepted
- in wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE handler.
+ in wxEVT_DATAVIEW_ITEM_EDITING_DONE handler.
Returns @true if editing the item was cancelled or if the user tried to
enter an invalid value (refused by wxDataViewRenderer::Validate()). If
this method returns @false, it means that the value in the model is
about to be changed to the new one.
- Notice that wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event handler can
+ Notice that wxEVT_DATAVIEW_ITEM_EDITING_DONE event handler can
call wxNotifyEvent::Veto() to prevent this from happening.
Currently support for setting this field and for vetoing the change is
void SetColumn(int col);
/**
- For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
+ For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICK only.
*/
void SetDataViewColumn(wxDataViewColumn* col);
*/
void SetDataObject( wxDataObject *obj );
- /**
- Used internally. Gets associated wxDataObject for data transfer
- within a drag operation.
- */
- wxDataObject *GetDataObject() const;
-
- /**
- Used internally. Sets the wxDataFormat during a drop operation.
- */
- void SetDataFormat( const wxDataFormat &format );
-
/**
Gets the wxDataFormat during a drop operation.
*/
wxDataFormat GetDataFormat() const;
/**
- Used internally. Sets the data size for a drop data transfer.
+ Gets the data size for a drop data transfer.
*/
- void SetDataSize( size_t size );
+ size_t GetDataSize() const;
/**
- Gets the data size for a drop data transfer.
+ Gets the data buffer for a drop data transfer.
*/
- size_t GetDataSize() const;
+ void *GetDataBuffer() const;
/**
- Used internally. Sets the data buffer for a drop data transfer.
+ Specify the kind of the drag operation to perform.
+
+ This method can be used inside a wxEVT_DATAVIEW_ITEM_BEGIN_DRAG
+ handler in order to configure the drag operation. Valid values are
+ ::wxDrag_CopyOnly (default), ::wxDrag_AllowMove (allow the data to be
+ moved) and ::wxDrag_DefaultMove.
+
+ Currently it is only honoured by the generic version of wxDataViewCtrl
+ (used e.g. under MSW) and not supported by the native GTK and OS X
+ versions.
+
+ @see GetDropEffect()
+
+ @since 2.9.4
*/
- void SetDataBuffer( void* buf );
+ void SetDragFlags(int flags);
/**
- Gets the data buffer for a drop data transfer.
+ Returns the effect the user requested to happen to the dropped data.
+
+ This function can be used inside
+ wxEVT_DATAVIEW_ITEM_DROP_POSSIBLE and
+ wxEVT_DATAVIEW_ITEM_DROP handlers and returns whether the user
+ is trying to copy (the return value is ::wxDragCopy) or move (if the
+ return value is ::wxDragMove) the data.
+
+ Currently this is only available when using the generic version of
+ wxDataViewCtrl (used e.g. under MSW) and always returns ::wxDragNone in
+ the GTK and OS X native versions.
+
+ @since 2.9.4
*/
- void *GetDataBuffer() const;
+ wxDragResult GetDropEffect() const;
/**
Return the first row that will be displayed.
Return the last row that will be displayed.
*/
int GetCacheTo() const;
+
+
+
+
+ wxDataViewItem GetItem() const;
+ void SetItem( const wxDataViewItem &item );
+ void SetEditCanceled(bool editCancelled);
+ void SetPosition( int x, int y );
+ void SetCache(int from, int to);
+ wxDataObject *GetDataObject() const;
+ void SetDataFormat( const wxDataFormat &format );
+ void SetDataSize( size_t size );
+ void SetDataBuffer( void* buf );
+ int GetDragFlags() const;
+ void SetDropEffect( wxDragResult effect );
+
};
projects / wxWidgets.git / blobdiff