X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..c29c95fe24973b94fd724db767193171ca7c513d:/interface/wx/dataview.h diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h index 533e8ec36b..8779ef96f9 100644 --- a/interface/wx/dataview.h +++ b/interface/wx/dataview.h @@ -1,213 +1,92 @@ ///////////////////////////////////////////////////////////////////////////// // Name: dataview.h -// Purpose: interface of wxDataViewIconText +// Purpose: interface of wxDataView* classes // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// -/** - @class wxDataViewIconText - @wxheader{dataview.h} - - wxDataViewIconText is used by - wxDataViewIconTextRenderer - for data transfer. This class can be converted to a from - a wxVariant. - - @library{wxbase} - @category{dvc} -*/ -class wxDataViewIconText : public wxObject -{ -public: - //@{ - /** - Constructor. - */ - wxDataViewIconText(const wxString& text = wxEmptyString, - const wxIcon& icon = wxNullIcon); - wxDataViewIconText(const wxDataViewIconText& other); - //@} - - /** - Gets the icon. - */ - const wxIcon GetIcon() const; - - /** - Gets the text. - */ - wxString GetText() const; - - /** - Set the icon. - */ - void SetIcon(const wxIcon& icon); - - /** - Set the text. - */ - void SetText(const wxString& text); -}; - - - -/** - @class wxDataViewEvent - @wxheader{dataview.h} - - wxDataViewEvent - the event class for the wxDataViewCtrl notifications - - @library{wxadv} - @category{events,dvc} -*/ -class wxDataViewEvent : public wxNotifyEvent -{ -public: - //@{ - /** - - */ - wxDataViewEvent(wxEventType commandType = wxEVT_NULL, - int winid = 0); - wxDataViewEvent(const wxDataViewEvent& event); - //@} - - /** - Used to clone the event. - */ - wxEvent* Clone() const; - - /** - Returns the position of the column in the control or -1 - if no column field was set by the event emitter. - */ - int GetColumn() const; - - /** - Returns a pointer to the wxDataViewColumn from which - the event was emitted or @NULL. - */ - wxDataViewColumn* GetDataViewColumn(); - - /** - Returns the wxDataViewModel associated with the event. - */ - wxDataViewModel* GetModel() const; - - /** - Returns a the position of a context menu event in screen coordinates. - */ - wxPoint GetPosition() const; - - /** - Returns a reference to a value. - */ - const wxVariant GetValue() const; - - /** - - */ - void SetColumn(int col); - - /** - For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only. - */ - void SetDataViewColumn(wxDataViewColumn* col); - - /** - - */ - void SetModel(wxDataViewModel* model); - - /** - - */ - void SetValue(const wxVariant& value); -}; - - /** @class wxDataViewModel - @wxheader{dataview.h} - - wxDataViewModel is the base class for all data model to be - displayed by a wxDataViewCtrl. - All other models derive from it and must implement its - pure virtual functions in order to define a complete - data model. In detail, you need to override - wxDataViewModel::IsContainer, - wxDataViewModel::GetParent, - wxDataViewModel::GetChildren, - wxDataViewModel::GetColumnCount, - wxDataViewModel::GetColumnType and - wxDataViewModel::GetValue in order to - define the data model which acts as an interface between - your actual data and the wxDataViewCtrl. Since you will - usually also allow the wxDataViewCtrl to change your data + + wxDataViewModel is the base class for all data model to be displayed by a + wxDataViewCtrl. + + All other models derive from it and must implement its pure virtual functions + in order to define a complete data model. In detail, you need to override + wxDataViewModel::IsContainer, wxDataViewModel::GetParent, wxDataViewModel::GetChildren, + wxDataViewModel::GetColumnCount, wxDataViewModel::GetColumnType and + wxDataViewModel::GetValue in order to define the data model which acts as an + interface between your actual data and the wxDataViewCtrl. + + Note that wxDataViewModel does not define the position or index of any item + in the control because different controls might display the same data differently. + wxDataViewModel does provide a wxDataViewModel::Compare method which the + wxDataViewCtrl may use to sort the data either in conjunction with a column + header or without (see wxDataViewModel::HasDefaultCompare). + + wxDataViewModel (as indeed the entire wxDataViewCtrl code) is using wxVariant + to store data and its type in a generic way. wxVariant can be extended to contain + almost any data without changes to the original class. To a certain extent, + you can use (the somewhat more elegant) wxAny instead of wxVariant as there + is code to convert between the two, but it is unclear what impact this will + have on performance. + + Since you will usually allow the wxDataViewCtrl to change your data through its graphical interface, you will also have to override - wxDataViewModel::SetValue which the - wxDataViewCtrl will call when a change to some data has been - commited. - - wxDataViewModel (as indeed the entire wxDataViewCtrl - code) is using wxVariant to store data and - its type in a generic way. wxVariant can be extended to contain - almost any data without changes to the original class. - - The data that is presented through this data model is expected - to change at run-time. You need to inform the data model when - a change happened. Depending on what happened you need to call - one of the following methods: - wxDataViewModel::ValueChanged, - wxDataViewModel::ItemAdded, - wxDataViewModel::ItemDeleted, - wxDataViewModel::ItemChanged, - wxDataViewModel::Cleared. There are - plural forms for notification of addition, change - or removal of several item at once. See - wxDataViewModel::ItemsAdded, - wxDataViewModel::ItemsDeleted, - wxDataViewModel::ItemsChanged. - - Note that wxDataViewModel does not define the position or - index of any item in the control because different controls - might display the same data differently. wxDataViewModel does - provide a wxDataViewModel::Compare method - which the wxDataViewCtrl may use to sort the data either - in conjunction with a column header or without (see - wxDataViewModel::HasDefaultCompare). - - This class maintains a list of - wxDataViewModelNotifier - which link this class to the specific implementations on the - supported platforms so that e.g. calling - wxDataViewModel::ValueChanged - on this model will just call - wxDataViewModelNotifier::ValueChanged - for each notifier that has been added. You can also add - your own notifier in order to get informed about any changes + wxDataViewModel::SetValue which the wxDataViewCtrl will call when a change + to some data has been committed. + + If the data represented by the model is changed by something else than its + associated wxDataViewCtrl, the control has to be notified about the change. + Depending on what happened you need to call one of the following methods: + - wxDataViewModel::ValueChanged, + - wxDataViewModel::ItemAdded, + - wxDataViewModel::ItemDeleted, + - wxDataViewModel::ItemChanged, + - wxDataViewModel::Cleared. + + There are plural forms for notification of addition, change or removal of + several item at once. See: + - wxDataViewModel::ItemsAdded, + - wxDataViewModel::ItemsDeleted, + - wxDataViewModel::ItemsChanged. + + This class maintains a list of wxDataViewModelNotifier which link this class + to the specific implementations on the supported platforms so that e.g. calling + wxDataViewModel::ValueChanged on this model will just call + wxDataViewModelNotifier::ValueChanged for each notifier that has been added. + You can also add your own notifier in order to get informed about any changes to the data in the list model. - Currently wxWidgets provides the following models apart - from the base model: - wxDataViewIndexListModel, - wxDataViewVirtualListModel, - wxDataViewTreeStore. + Currently wxWidgets provides the following models apart from the base model: + wxDataViewIndexListModel, wxDataViewVirtualListModel, wxDataViewTreeStore, + wxDataViewListStore. - Note that wxDataViewModel is reference counted, derives from - wxObjectRefData and cannot be deleted - directly as it can be shared by several wxDataViewCtrls. This - implies that you need to decrease the reference count after + Note that wxDataViewModel is reference counted, derives from wxRefCounter + and cannot be deleted directly as it can be shared by several wxDataViewCtrls. + This implies that you need to decrease the reference count after associating the model with a control like this: @code - wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, ID_MUSIC_CTRL ); + wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY ); wxDataViewModel *musicModel = new MyMusicModel; - m_musicCtrl-AssociateModel( musicModel ); - musicModel-DecRef(); // avoid memory leak !! + m_musicCtrl->AssociateModel( musicModel ); + musicModel->DecRef(); // avoid memory leak !! + + // add columns now + @endcode + + A potentially better way to avoid memory leaks is to use wxObjectDataPtr + + @code + wxObjectDataPtr musicModel; + + wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY ); + musicModel = new MyMusicModel; + m_musicCtrl->AssociateModel( musicModel.get() ); + // add columns now @endcode @@ -215,7 +94,7 @@ public: @library{wxadv} @category{dvc} */ -class wxDataViewModel : public wxObjectRefData +class wxDataViewModel : public wxRefCounter { public: /** @@ -224,19 +103,35 @@ public: wxDataViewModel(); /** - Destructor. This should not be called directly. Use DecRef() instead. + Adds a wxDataViewModelNotifier to the model. */ - ~wxDataViewModel(); + void AddNotifier(wxDataViewModelNotifier* notifier); /** - Adds a wxDataViewModelNotifier - to the model. - */ - void AddNotifier(wxDataViewModelNotifier* notifier); + Change the value of the given item and update the control to reflect + it. + + This function simply calls SetValue() and, if it succeeded, + ValueChanged(). + + @since 2.9.1 + + @param variant + The new value. + @param item + The item (row) to update. + @param col + The column to update. + @return + @true if both SetValue() and ValueChanged() returned @true. + */ + bool ChangeValue(const wxVariant& variant, + const wxDataViewItem& item, + unsigned int col); /** - Called to inform the model that all data has been cleared. The - control will reread the data from the model again. + Called to inform the model that all data has been cleared. + The control will reread the data from the model again. */ virtual bool Cleared(); @@ -244,61 +139,99 @@ public: The compare function to be used by control. The default compare function sorts by container and other items separately and in ascending order. Override this for a different sorting behaviour. - See also HasDefaultCompare(). + + @see HasDefaultCompare(). */ virtual int Compare(const wxDataViewItem& item1, const wxDataViewItem& item2, unsigned int column, - bool ascending); + bool ascending) const; + + /** + Override this to indicate that the item has special font attributes. + This only affects the wxDataViewTextRendererText renderer. + + The base class version always simply returns @false. + + @see wxDataViewItemAttr. + + @param item + The item for which the attribute is requested. + @param col + The column of the item for which the attribute is requested. + @param attr + The attribute to be filled in if the function returns @true. + @return + @true if this item has an attribute or @false otherwise. + */ + virtual bool GetAttr(const wxDataViewItem& item, unsigned int col, + wxDataViewItemAttr& attr) const; /** - Oberride this to indicate that the item has special font attributes. - This only affects the - wxDataViewTextRendererText() renderer. - See also wxDataViewItemAttr. + Override this to indicate that the item should be disabled. + + Disabled items are displayed differently (e.g. grayed out) and cannot + be interacted with. + + The base class version always returns @true, thus making all items + enabled by default. + + @param item + The item whose enabled status is requested. + @param col + The column of the item whose enabled status is requested. + @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 + implementation. + + @since 2.9.2 */ - bool GetAttr(const wxDataViewItem& item, unsigned int col, - wxDataViewItemAttr& attr); + virtual bool IsEnabled(const wxDataViewItem &item, + unsigned int col) const; /** - Override this so the control can query the child items of - an item. Returns the number of items. + Override this so the control can query the child items of an item. + Returns the number of items. */ virtual unsigned int GetChildren(const wxDataViewItem& item, - wxDataViewItemArray& children) const; + wxDataViewItemArray& children) const = 0; /** Override this to indicate the number of columns in the model. */ - virtual unsigned int GetColumnCount() const; + virtual unsigned int GetColumnCount() const = 0; /** Override this to indicate what type of data is stored in the - column specified by @e col. This should return a string - indicating the type of data as reported by wxVariant. + column specified by @a col. + + This should return a string indicating the type of data as reported by wxVariant. */ - virtual wxString GetColumnType(unsigned int col) const; + virtual wxString GetColumnType(unsigned int col) const = 0; /** Override this to indicate which wxDataViewItem representing the parent - of @a item or an invalid wxDataViewItem if the the root item is + of @a item or an invalid wxDataViewItem if the root item is the parent item. */ - virtual wxDataViewItem GetParent(const wxDataViewItem& item) const; + virtual wxDataViewItem GetParent(const wxDataViewItem& item) const = 0; /** - Override this to indicate the value of @e item + Override this to indicate the value of @a item. A wxVariant is used to store the data. */ - virtual void GetValue(wxVariant& variant, - const wxDataViewItem& item, - unsigned int col) const; + virtual void GetValue(wxVariant& variant, const wxDataViewItem& item, + unsigned int col) const = 0; /** - Override this method to indicate if a container item merely - acts as a headline (or for categorisation) or if it also - acts a normal item with entries for futher columns. By - default returns @e @false. + Override this method to indicate if a container item merely acts as a + headline (or for categorisation) or if it also acts a normal item with + entries for further columns. By default returns @false. */ virtual bool HasContainerColumns(const wxDataViewItem& item) const; @@ -306,57 +239,72 @@ public: Override this to indicate that the model provides a default compare function that the control should use if no wxDataViewColumn has been chosen for sorting. Usually, the user clicks on a column header for - sorting, the data will be sorted alphanumerically. If any other - order (e.g. by index or order of appearance) is required, then this - should be used. See also wxDataViewIndexListModel - for a model which makes use of this. + sorting, the data will be sorted alphanumerically. + + If any other order (e.g. by index or order of appearance) is required, + then this should be used. + See wxDataViewIndexListModel for a model which makes use of this. */ virtual bool HasDefaultCompare() const; + /** + Return true if there is a value in the given column of this item. + + All normal items have values in all columns but the container items + only show their label in the first column (@a col == 0) by default (but + see HasContainerColumns()). So this function always returns true for + the first column while for the other ones it returns true only if the + item is not a container or HasContainerColumns() was overridden to + return true for it. + + @since 2.9.1 + */ + bool HasValue(const wxDataViewItem& item, unsigned col) const; + /** 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; + virtual bool IsContainer(const wxDataViewItem& item) const = 0; /** - Call this to inform the model that an item has been added - to the data. + Call this to inform the model that an item has been added to the data. */ - virtual bool ItemAdded(const wxDataViewItem& parent, + bool ItemAdded(const wxDataViewItem& parent, const wxDataViewItem& item); /** Call this to inform the model that an item has changed. - This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED + + This will eventually emit a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED event (in which the column fields will not be set) to the user. */ - virtual bool ItemChanged(const wxDataViewItem& item); + bool ItemChanged(const wxDataViewItem& item); /** Call this to inform the model that an item has been deleted from the data. */ - virtual bool ItemDeleted(const wxDataViewItem& parent, + bool ItemDeleted(const wxDataViewItem& parent, const wxDataViewItem& item); /** - Call this to inform the model that several items have been added - to the data. + Call this to inform the model that several items have been added to the data. */ - virtual bool ItemsAdded(const wxDataViewItem& parent, + bool ItemsAdded(const wxDataViewItem& parent, const wxDataViewItemArray& items); /** Call this to inform the model that several items have changed. - This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED + + This will eventually emit @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED events (in which the column fields will not be set) to the user. */ - virtual bool ItemsChanged(const wxDataViewItemArray& items); + bool ItemsChanged(const wxDataViewItemArray& items); /** Call this to inform the model that several items have been deleted. */ - virtual bool ItemsDeleted(const wxDataViewItem& parent, + bool ItemsDeleted(const wxDataViewItem& parent, const wxDataViewItemArray& items); /** @@ -365,66 +313,63 @@ public: void RemoveNotifier(wxDataViewModelNotifier* notifier); /** - Call this to initiate a resort after the sort function has - been changed. + Call this to initiate a resort after the sort function has been changed. */ virtual void Resort(); /** This gets called in order to set a value in the data model. - The most common scenario is that the wxDataViewCtrl calls - this method after the user changed some data in the view. - Afterwards ValueChanged() - has to be called! + + The most common scenario is that the wxDataViewCtrl calls this method + after the user changed some data in the view. + + This is the function you need to override in your derived class but if + you want to call it, ChangeValue() is usually more convenient as + otherwise you need to manually call ValueChanged() to update the + control itself. */ virtual bool SetValue(const wxVariant& variant, const wxDataViewItem& item, - unsigned int col); + unsigned int col) = 0; /** - Call this to inform this model that a value in the model has - been changed. This is also called from wxDataViewCtrl's - internal editing code, e.g. when editing a text field - in the control. - This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED + Call this to inform this model that a value in the model has been changed. + This is also called from wxDataViewCtrl's internal editing code, e.g. when + editing a text field in the control. + + This will eventually emit a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED event to the user. */ virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col); + +protected: + + /** + Destructor. This should not be called directly. Use DecRef() instead. + */ + virtual ~wxDataViewModel(); }; /** - @class wxDataViewIndexListModel - @wxheader{dataview.h} + @class wxDataViewListModel - 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. + Base class with abstract API for wxDataViewIndexListModel and + wxDataViewVirtualListModel. - @library{wxbase} + @library{wxadv} @category{dvc} */ -class wxDataViewIndexListModel : public wxDataViewModel +class wxDataViewListModel : public wxDataViewModel { public: - /** - Constructor. - */ - wxDataViewIndexListModel(unsigned int initial_size = 0); /** Destructor. */ - ~wxDataViewIndexListModel(); + virtual ~wxDataViewIndexListModel(); /** Compare method that sorts the items by their index. @@ -434,13 +379,51 @@ public: unsigned int column, bool ascending); /** - Oberride this to indicate that the row has special font attributes. - This only affects the - wxDataViewTextRendererText() renderer. - See also wxDataViewItemAttr. + Override this to indicate that the row has special font attributes. + This only affects the wxDataViewTextRendererText() renderer. + + The base class version always simply returns @false. + + @see wxDataViewItemAttr. + + @param row + The row for which the attribute is requested. + @param col + The column for which the attribute is requested. + @param attr + The attribute to be filled in if the function returns @true. + @return + @true if this item has an attribute or @false otherwise. + */ + virtual bool GetAttrByRow(unsigned int row, unsigned int col, + wxDataViewItemAttr& attr) const; + + /** + Override this if you want to disable specific items. + + The base class version always returns @true, thus making all items + enabled by default. + + @param row + The row of the item whose enabled status is requested. + @param col + The column of the item whose enabled status is requested. + @return + @true if the item at this row and column should be enabled, + @false otherwise. + + @note See wxDataViewModel::IsEnabled() for the current status of + support for disabling the items under different platforms. + + @since 2.9.2 + */ + virtual bool IsEnabledByRow(unsigned int row, + unsigned int col) const; + + /** + Returns the number of items (i.e. rows) in the list. */ - bool GetAttr(unsigned int row, unsigned int col, - wxDataViewItemAttr& attr); + unsigned int GetCount() const; /** Returns the wxDataViewItem at the given @e row. @@ -455,14 +438,13 @@ public: /** Override this to allow getting values from the model. */ - void GetValue(wxVariant& variant, unsigned int row, - unsigned int col) const; + virtual void GetValueByRow(wxVariant& variant, unsigned int row, + unsigned int col) const = 0; /** - 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. + 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); @@ -497,61 +479,85 @@ public: 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. + 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); /** Called in order to set a value in the model. */ - bool SetValue(const wxVariant& variant, unsigned int row, - unsigned int col); + 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); + +}; /** @class wxDataViewVirtualListModel - @wxheader{dataview.h} - wxDataViewVirtualListModel is a specialized data model which lets - you address an item by its position (row) rather than its - wxDataViewItem and as such offers the exact same interface as - wxDataViewIndexListModel. The important difference is that under - platforms other than OS X, using this model will result in a - truely virtual control able to handle millions of items as the - control doesn't store any item (a feature not supported by the - Carbon API under OS X). + wxDataViewVirtualListModel is a specialized data model which lets you address + an item by its position (row) rather than its wxDataViewItem and as such offers + the exact same interface as wxDataViewIndexListModel. + The important difference is that under platforms other than OS X, using this + model will result in a truly virtual control able to handle millions of items + as the control doesn't store any item (a feature not supported by OS X). - @see wxDataViewIndexListModel for the API. + @see wxDataViewListModel for the API. - @library{wxbase} + @library{wxadv} @category{dvc} */ -class wxDataViewVirtualListModel : public wxDataViewModel + +class wxDataViewVirtualListModel : public wxDataViewListModel { public: /** Constructor. */ wxDataViewVirtualListModel(unsigned int initial_size = 0); + }; /** @class wxDataViewItemAttr - @wxheader{dataview.h} - This class is used to indicate to a wxDataViewCtrl - that a certain Item() has extra font attributes - for its renderer. For this, it is required to override - wxDataViewModel::GetAttr. + This class is used to indicate to a wxDataViewCtrl that a certain item + (see wxDataViewItem) has extra font attributes for its renderer. + For this, it is required to override wxDataViewModel::GetAttr. - Attributes are currently only supported by - wxDataViewTextRendererText(). + Attributes are currently only supported by wxDataViewTextRendererText. @library{wxadv} @category{dvc} @@ -570,8 +576,7 @@ public: void SetBold(bool set); /** - Call this to indicate that the item shall be displayed with - that colour. + Call this to indicate that the item shall be displayed with that colour. */ void SetColour(const wxColour& colour); @@ -585,22 +590,18 @@ public: /** @class wxDataViewItem - @wxheader{dataview.h} - - wxDataViewItem is a small opaque class that represents an - item in a wxDataViewCtrl in a - persistent way, i.e. indepent of the position of the - item in the control or changes to its contents. It must - hold a unique ID of type @e void* in its only field - and can be converted to a from it. - - If the ID is @e @NULL the wxDataViewItem is invalid and - wxDataViewItem::IsOk will return @e @false - which used in many places in the API of wxDataViewCtrl - to indicate that e.g. no item was found. An ID of @NULL - is also used to indicate the invisible root. Examples - for this are - wxDataViewModel::GetParent and + + wxDataViewItem is a small opaque class that represents an item in a wxDataViewCtrl + in a persistent way, i.e. independent of the position of the item in the control + or changes to its contents. + + It must hold a unique ID of type @e void* in its only field and can be converted + to and from it. + + If the ID is @NULL the wxDataViewItem is invalid and wxDataViewItem::IsOk will + return @false which used in many places in the API of wxDataViewCtrl to + indicate that e.g. no item was found. An ID of @NULL is also used to indicate + the invisible root. Examples for this are wxDataViewModel::GetParent and wxDataViewModel::GetChildren. @library{wxadv} @@ -611,7 +612,7 @@ class wxDataViewItem public: //@{ /** - + Constructor. */ wxDataViewItem(void* id = NULL); wxDataViewItem(const wxDataViewItem& item); @@ -623,7 +624,7 @@ public: void* GetID() const; /** - Returns @true if the ID is not @e @NULL. + Returns @true if the ID is not @NULL. */ bool IsOk() const; }; @@ -632,38 +633,32 @@ public: /** @class wxDataViewCtrl - @wxheader{dataview.h} - - 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. + + 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. + Likewise, if you only want to display simple table structure you can use + the specialized wxDataViewListCtrl class. Both wxDataViewTreeCtrl and + wxDataViewListCtrl can be used without defining your own wxDataViewModel. + + 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 + renderers 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. @beginStyleTable @style{wxDV_SINGLE} @@ -672,17 +667,63 @@ public: Multiple selection mode. @style{wxDV_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. @style{wxDV_HORIZ_RULES} Display fine rules between row if supported. @style{wxDV_VERT_RULES} Display fine rules between columns is supported. @style{wxDV_VARIABLE_LINE_HEIGHT} - Allow variable line heights. This can be inefficient when displaying large number of items. + Allow variable line heights. + This can be inefficient when displaying large number of items. + @style{wxDV_NO_HEADER} + Do not show column headers (which are shown by default). @endStyleTable + @beginEventEmissionTable{wxDataViewEvent} + @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event. + @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. + @event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event. This + event can be vetoed in order to prevent editing on an item by item + basis. Still experimental. + @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event. + @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event. + @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event. + @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event. + @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event. + @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event. + @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event. + @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event. + @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event. + @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event. + @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event. + @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event. + @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event. + @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event. + @event{EVT_DATAVIEW_ITEM_DROP(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event. + @endEventTable + @library{wxadv} @category{ctrl,dvc} - + @appearance{dataviewctrl.png} */ class wxDataViewCtrl : public wxControl { @@ -691,7 +732,7 @@ public: Default Constructor. */ wxDataViewCtrl(); - + /** Constructor. Calls Create(). */ @@ -699,15 +740,17 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = 0, - const wxValidator& validator = wxDefaultValidator); + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxDataViewCtrlNameStr); /** Destructor. */ - ~wxDataViewCtrl(); + virtual ~wxDataViewCtrl(); /** 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). */ @@ -715,6 +758,7 @@ public: /** 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. */ @@ -724,7 +768,7 @@ public: Inserts a wxDataViewColumn to the control. Returns @true on success. */ virtual bool InsertColumn(unsigned int pos, wxDataViewColumn* col); - + //@{ /** Appends a column for rendering a bitmap. Returns the wxDataViewColumn @@ -748,44 +792,44 @@ public: /** Appends a column for rendering a date. Returns the wxDataViewColumn created in the function or @NULL on failure. - - NB: The @e align parameter is applied to both the column header and - the column renderer. + + @note The @a align parameter is applied to both the column header and + the column renderer. */ wxDataViewColumn* AppendDateColumn(const wxString& label, unsigned int model_column, wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, int width = -1, - wxAlignment align = wxALIGN_CENTER, + wxAlignment align = wxALIGN_NOT, 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, + wxAlignment align = wxALIGN_NOT, 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 @e align parameter is applied to both the column header and - the column renderer. + 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* AppendIconTextColumn(const wxString& label, unsigned int model_column, wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, int width = -1, - wxAlignment align = wxALIGN_LEFT, + wxAlignment align = wxALIGN_NOT, 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, + wxAlignment align = wxALIGN_NOT, int flags = wxDATAVIEW_COL_RESIZABLE); //@} @@ -793,9 +837,9 @@ public: /** Appends a column for rendering a progress indicator. Returns the wxDataViewColumn created in the function or @NULL on failure. - - NB: The @e align parameter is applied to both the column header and - the column renderer. + + @note The @a align parameter is applied to both the column header and + the column renderer. */ wxDataViewColumn* AppendProgressColumn(const wxString& label, unsigned int model_column, @@ -815,21 +859,21 @@ public: /** Appends a column for rendering text. Returns the wxDataViewColumn created in the function or @NULL on failure. - - NB: The @e align parameter is applied to both the column header and - the column renderer. + + @note The @a align parameter is applied to both the column header and + the column renderer. */ wxDataViewColumn* AppendTextColumn(const wxString& label, unsigned int model_column, wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, int width = -1, - wxAlignment align = wxALIGN_LEFT, + wxAlignment align = wxALIGN_NOT, 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, + wxAlignment align = wxALIGN_NOT, int flags = wxDATAVIEW_COL_RESIZABLE); //@} @@ -837,9 +881,9 @@ public: /** Appends a column for rendering a toggle. Returns the wxDataViewColumn created in the function or @NULL on failure. - - NB: The @e align parameter is applied to both the column header and - the column renderer. + + @note The @a align parameter is applied to both the column header and + the column renderer. */ wxDataViewColumn* AppendToggleColumn(const wxString& label, unsigned int model_column, @@ -856,8 +900,8 @@ public: //@} /** - Associates a wxDataViewModel with the control. This increases the reference - count of the model by 1. + Associates a wxDataViewModel with the control. + This increases the reference count of the model by 1. */ virtual bool AssociateModel(wxDataViewModel* model); @@ -866,15 +910,10 @@ public: */ virtual bool ClearColumns(); - /** - Unselects all rows. - */ - void ClearSelection(); - /** Collapses the item. */ - void Collapse(const wxDataViewItem& item); + virtual void Collapse(const wxDataViewItem& item); /** Create the control. Useful for two step creation. @@ -883,28 +922,45 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = 0, - const wxValidator& validator = wxDefaultValidator); + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxDataViewCtrlNameStr); /** Deletes given column. */ - virtual bool DeleteColumn(const wxDataViewColumn* column); + virtual bool DeleteColumn(wxDataViewColumn* column); + + /** + Enable drag operations using the given @a format. + */ + virtual bool EnableDragSource( const wxDataFormat &format ); + + /** + Enable drop operations using the given @a format. + */ + virtual bool EnableDropTarget( const wxDataFormat &format ); /** Call this to ensure that the given item is visible. */ - void EnsureVisible(const wxDataViewItem& item, - const wxDataViewColumn* column = NULL); + virtual void EnsureVisible(const wxDataViewItem& item, + const wxDataViewColumn* column = NULL); /** Expands the item. */ - void Expand(const wxDataViewItem& item); + virtual void Expand(const wxDataViewItem& item); + + /** + Expands all ancestors of the @a item. This method also + ensures that the item itself as well as all ancestor + items have been read from the model by the control. + */ + virtual void ExpandAncestors( const wxDataViewItem & item ); /** - Returns pointer to the column. @a pos refers to the - position in the control which may change after reordering - columns by the user. + Returns pointer to the column. @a pos refers to the position in the + control which may change after reordering columns by the user. */ virtual wxDataViewColumn* GetColumn(unsigned int pos) const; @@ -924,32 +980,50 @@ public: wxDataViewColumn* GetExpanderColumn() const; /** - Returns indentation. - */ - int GetIndent() const; + Returns the currently focused item. - /** - Returns item rect. - */ - wxRect GetItemRect(const wxDataViewItem& item, - const wxDataViewColumn* col = NULL) const; + This is the item that the keyboard commands apply to. It may be invalid + if there is no focus currently. + + This method is mostly useful for the controls with @c wxDV_MULTIPLE + style as in the case of single selection it returns the same thing as + GetSelection(). + + Notice that under all platforms except Mac OS X the currently focused + item may be selected or not but under OS X the current item is always + selected. + + @see SetCurrentItem() + + @since 2.9.2 + */ + wxDataViewItem GetCurrentItem() const; + + /** + Returns indentation. + */ + int GetIndent() const; + + /** + Returns item rect. + */ + virtual wxRect GetItemRect(const wxDataViewItem& item, + const wxDataViewColumn* col = NULL) const; /** - Returns pointer to the data model associated with the - control (if any). + Returns pointer to the data model associated with the control (if any). */ - virtual wxDataViewModel* GetModel() const; + wxDataViewModel* GetModel(); /** Returns first selected item or an invalid item if none is selected. */ - wxDataViewItem GetSelection() const; + virtual wxDataViewItem GetSelection() const; /** - Fills @a sel with currently selected items and returns - their number. + Fills @a sel with currently selected items and returns their number. */ - int GetSelections(wxDataViewItemArray& sel) const; + virtual int GetSelections(wxDataViewItemArray& sel) const; /** Returns the wxDataViewColumn currently responsible for sorting @@ -960,23 +1034,32 @@ public: /** Hittest. */ - void HitTest(const wxPoint& point, wxDataViewItem& item, - wxDataViewColumn*& col) const; + virtual void HitTest(const wxPoint& point, wxDataViewItem& item, + wxDataViewColumn*& col) const; + + /** + Return @true if the item is expanded. + */ + virtual bool IsExpanded(const wxDataViewItem& item) const; /** Return @true if the item is selected. */ - bool IsSelected(const wxDataViewItem& item) const; + virtual bool IsSelected(const wxDataViewItem& item) const; /** Select the given item. + + In single selection mode this changes the (unique) currently selected + item. In multi selection mode, the @a item is selected and the + previously selected items remain selected. */ - void Select(const wxDataViewItem& item); + virtual void Select(const wxDataViewItem& item); /** Select all items. */ - void SelectAll(); + virtual void SelectAll(); /** Set which column shall contain the tree-like expanders. @@ -984,40 +1067,84 @@ public: void SetExpanderColumn(wxDataViewColumn* col); /** - Sets the indendation. + Changes the currently focused item. + + The @a item parameter must be valid, there is no way to remove the + current item from the control. + + In single selection mode, calling this method is the same as calling + Select() and is thus not very useful. In multiple selection mode this + method only moves the current item however without changing the + selection except under OS X where the current item is always selected, + so calling SetCurrentItem() selects @a item if it hadn't been selected + before. + + @see GetCurrentItem() + + @since 2.9.2 + */ + void SetCurrentItem(const wxDataViewItem& item); + + /** + Sets the indentation. */ void SetIndent(int indent); /** Sets the selection to the array of wxDataViewItems. */ - void SetSelections(const wxDataViewItemArray& sel); + 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. */ - void Unselect(const wxDataViewItem& item); + virtual void Unselect(const wxDataViewItem& item); /** - Unselect all item. This method only has effect if multiple - selections are allowed. + Unselect all item. + This method only has effect if multiple selections are allowed. */ - void UnselectAll(); + virtual void UnselectAll(); + + /** + Sets the row height. + + This function can only be used when all rows have the same height, i.e. + when wxDV_VARIABLE_LINE_HEIGHT flag is not used. + + Currently this is implemented in the generic and native GTK versions + only and nothing is done (and @false returned) when using OS X port. + + Also notice that this method can only be used to increase the row + height compared with the default one (as determined by the return value + of wxDataViewRenderer::GetSize()), if it is set to a too small value + then the minimum required by the renderers will be used. + + @return @true if the line height was changed or @false otherwise. + + @since 2.9.2 + */ + virtual bool SetRowHeight(int rowHeight); }; /** @class wxDataViewModelNotifier - @wxheader{dataview.h} - A wxDataViewModelNotifier instance is owned by a - wxDataViewModel - and mirrors its notification interface. See - the documentation of that class for further - information. + A wxDataViewModelNotifier instance is owned by a wxDataViewModel and mirrors + its notification interface. + See the documentation of that class for further information. - @library{wxbase} + @library{wxadv} @category{dvc} */ class wxDataViewModelNotifier @@ -1031,12 +1158,12 @@ public: /** Destructor. */ - ~wxDataViewModelNotifier(); + virtual ~wxDataViewModelNotifier(); /** Called by owning model. */ - bool Cleared(); + virtual bool Cleared() = 0; /** Get owning wxDataViewModel. @@ -1046,41 +1173,41 @@ public: /** Called by owning model. */ - bool ItemAdded(const wxDataViewItem& parent, - const wxDataViewItem& item); + virtual bool ItemAdded(const wxDataViewItem& parent, + const wxDataViewItem& item) = 0; /** Called by owning model. */ - bool ItemChanged(const wxDataViewItem& item); + virtual bool ItemChanged(const wxDataViewItem& item) = 0; /** Called by owning model. */ - bool ItemDeleted(const wxDataViewItem& parent, - const wxDataViewItem& item); + virtual bool ItemDeleted(const wxDataViewItem& parent, + const wxDataViewItem& item) = 0; /** Called by owning model. */ - bool ItemsAdded(const wxDataViewItem& parent, - const wxDataViewItemArray& items); + virtual bool ItemsAdded(const wxDataViewItem& parent, + const wxDataViewItemArray& items); /** Called by owning model. */ - bool ItemsChanged(const wxDataViewItemArray& items); + virtual bool ItemsChanged(const wxDataViewItemArray& items); /** Called by owning model. */ - bool ItemsDeleted(const wxDataViewItem& parent, - const wxDataViewItemArray& items); + virtual bool ItemsDeleted(const wxDataViewItem& parent, + const wxDataViewItemArray& items); /** Called by owning model. */ - void Resort(); + virtual void Resort() = 0; /** Set owner of this notifier. Used internally. @@ -1090,63 +1217,64 @@ public: /** Called by owning model. */ - bool ValueChanged(const wxDataViewItem& item, unsigned int col); + virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col) = 0; }; +/** + The mode of a data-view cell; see wxDataViewRenderer for more info. +*/ +enum wxDataViewCellMode +{ + 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). + */ + 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. + */ + wxDATAVIEW_CELL_EDITABLE +}; + +/** + The values of this enum controls how a wxDataViewRenderer should display + its contents in a cell. +*/ +enum wxDataViewCellRenderState +{ + wxDATAVIEW_CELL_SELECTED = 1, + wxDATAVIEW_CELL_PRELIT = 2, + wxDATAVIEW_CELL_INSENSITIVE = 4, + wxDATAVIEW_CELL_FOCUSED = 8 +}; /** @class wxDataViewRenderer - @wxheader{dataview.h} This class is used by wxDataViewCtrl to render the individual cells. - One instance of a renderer class is owned by a wxDataViewColumn. There - is a number of ready-to-use renderers provided: - wxDataViewTextRenderer, - wxDataViewTextRendererAttr, - wxDataViewIconTextRenderer, - wxDataViewToggleRenderer, - wxDataViewProgressRenderer, - wxDataViewBitmapRenderer, - wxDataViewDateRenderer. - wxDataViewSpinRenderer. + One instance of a renderer class is owned by a wxDataViewColumn. + There is a number of ready-to-use renderers provided: + - wxDataViewTextRenderer, + - wxDataViewIconTextRenderer, + - wxDataViewToggleRenderer, + - wxDataViewProgressRenderer, + - wxDataViewBitmapRenderer, + - wxDataViewDateRenderer, + - wxDataViewSpinRenderer. + - wxDataViewChoiceRenderer. Additionally, the user can write own renderers by deriving from wxDataViewCustomRenderer. - The @e wxDataViewCellMode flag controls, what actions - the cell data allows. @e wxDATAVIEW_CELL_ACTIVATABLE - indicates that the user can double click the cell and - something will happen (e.g. a window for editing a date - will pop up). @e wxDATAVIEW_CELL_EDITABLE 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. - - - @code - enum wxDataViewCellMode - { - wxDATAVIEW_CELL_INERT, - wxDATAVIEW_CELL_ACTIVATABLE, - wxDATAVIEW_CELL_EDITABLE - }; - @endcode - - The @e wxDataViewCellRenderState flag controls how the - the renderer should display its contents in a cell: - - @code - enum wxDataViewCellRenderState - { - wxDATAVIEW_CELL_SELECTED = 1, - wxDATAVIEW_CELL_PRELIT = 2, - wxDATAVIEW_CELL_INSENSITIVE = 4, - wxDATAVIEW_CELL_FOCUSED = 8 - }; - @endcode - + The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted + by the constructors respectively controls what actions the cell data allows + and how the renderer should display its contents in a cell. @library{wxadv} @category{dvc} @@ -1155,68 +1283,107 @@ class wxDataViewRenderer : public wxObject { public: /** - Constructor. + Constructor. */ wxDataViewRenderer(const wxString& varianttype, wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, int align = wxDVR_DEFAULT_ALIGNMENT ); + /** + Enable or disable replacing parts of the item text with ellipsis to + make it fit the column width. + + This method only makes sense for the renderers working with text, such + as wxDataViewTextRenderer or wxDataViewIconTextRenderer. + + By default wxELLIPSIZE_MIDDLE is used. + + @param mode + Ellipsization mode, use wxELLIPSIZE_NONE to disable. + + @since 2.9.1 + */ + void EnableEllipsize(wxEllipsizeMode mode = wxELLIPSIZE_MIDDLE); + + /** + Disable replacing parts of the item text with ellipsis. + + If ellipsizing is disabled, the string will be truncated if it doesn't + fit. + + This is the same as @code EnableEllipsize(wxELLIPSIZE_NONE) @endcode. + + @since 2.9.1 + */ + void DisableEllipsize(); + /** Returns the alignment. See SetAlignment() */ virtual int GetAlignment() const; + /** + Returns the ellipsize mode used by the renderer. + + If the return value is wxELLIPSIZE_NONE, the text is simply truncated + if it doesn't fit. + + @see EnableEllipsize() + */ + wxEllipsizeMode GetEllipsizeMode() const; + /** Returns the cell mode. */ - virtual wxDataViewCellMode GetMode(); + virtual wxDataViewCellMode GetMode() const; /** Returns pointer to the owning wxDataViewColumn. */ - virtual wxDataViewColumn* GetOwner() const; + wxDataViewColumn* GetOwner() const; /** This methods retrieves the value from the renderer in order to - transfer the value back to the data model. Returns @e @false - on failure. + transfer the value back to the data model. + + Returns @false on failure. */ - virtual bool GetValue(wxVariant& value); + virtual bool GetValue(wxVariant& value) const = 0; /** - Returns a string with the type of the wxVariant - supported by this renderer. + Returns a string with the type of the wxVariant supported by this renderer. */ - virtual wxString GetVariantType(); + wxString GetVariantType() const; /** - Sets the alignment of the renderer's content. The default value - of wxDVR_DEFAULT_ALIGMENT indicates that the content should - have the same alignment as the column header. The method is - not implemented under OS X and the renderer always aligns its - contents as the column header on that platform. The other platforms + Sets the alignment of the renderer's content. + The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content + should have the same alignment as the column header. + + The method is not implemented under OS X and the renderer always aligns + its contents as the column header on that platform. The other platforms support both vertical and horizontal alignment. */ virtual void SetAlignment( int align ); /** - Sets the owning wxDataViewColumn. This - is usually called from within wxDataViewColumn. + Sets the owning wxDataViewColumn. + This is usually called from within wxDataViewColumn. */ - virtual void SetOwner(wxDataViewColumn* owner); + void SetOwner(wxDataViewColumn* owner); /** - Set the value of the renderer (and thus its cell) to @e value. + Set the value of the renderer (and thus its cell) to @a value. The internal code will then render this cell with this data. */ - virtual bool SetValue(const wxVariant& value); + virtual bool SetValue(const wxVariant& value) = 0; /** Before data is committed to the data model, it is passed to this method where it can be checked for validity. This can also be used for checking a valid range or limiting the user input in a certain aspect (e.g. max number of characters or only alphanumeric - input, ASCII only etc.). Return @e @false if the value is - not valid. + input, ASCII only etc.). Return @false if the value is not valid. + Please note that due to implementation limitations, this validation is done after the editing control already is destroyed and the editing process finished. @@ -1228,10 +1395,9 @@ public: /** @class wxDataViewTextRenderer - @wxheader{dataview.h} - wxDataViewTextRenderer is used for rendering text. It supports - in-place editing if desired. + wxDataViewTextRenderer is used for rendering text. + It supports in-place editing if desired. @library{wxadv} @category{dvc} @@ -1240,7 +1406,7 @@ class wxDataViewTextRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ wxDataViewTextRenderer(const wxString& varianttype = "string", wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, @@ -1251,14 +1417,13 @@ public: /** @class wxDataViewIconTextRenderer - @wxheader{dataview.h} The wxDataViewIconTextRenderer class is used to display text with a small icon next to it as it is typically done in a file manager. - This classes uses the wxDataViewIconText - helper class to store its data. wxDataViewIonText can be converted - to a from a wxVariant using the left shift - operator. + + This classes uses the wxDataViewIconText helper class to store its data. + wxDataViewIconText can be converted to and from a wxVariant using the left + shift operator. @library{wxadv} @category{dvc} @@ -1267,7 +1432,7 @@ class wxDataViewIconTextRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText", wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, @@ -1278,9 +1443,8 @@ public: /** @class wxDataViewProgressRenderer - @wxheader{dataview.h} - wxDataViewProgressRenderer + This class is used by wxDataViewCtrl to render progress bars. @library{wxadv} @category{dvc} @@ -1289,7 +1453,7 @@ class wxDataViewProgressRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ wxDataViewProgressRenderer(const wxString& label = wxEmptyString, const wxString& varianttype = "long", @@ -1301,21 +1465,20 @@ public: /** @class wxDataViewSpinRenderer - @wxheader{dataview.h} - This is a specialized renderer for rendering integer values. It - supports modifying the values in-place by using a wxSpinCtrl. + This is a specialized renderer for rendering integer values. + It supports modifying the values in-place by using a wxSpinCtrl. The renderer only support variants of type @e long. - @library{wxbase} + @library{wxadv} @category{dvc} */ class wxDataViewSpinRenderer : public wxDataViewCustomRenderer { public: /** - Constructor. @a min and @a max indicate the minimum und - maximum values of for the wxSpinCtrl. + Constructor. + @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl. */ wxDataViewSpinRenderer(int min, int max, wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE, @@ -1326,9 +1489,8 @@ public: /** @class wxDataViewToggleRenderer - @wxheader{dataview.h} - wxDataViewToggleRenderer + This class is used by wxDataViewCtrl to render toggle controls. @library{wxadv} @category{dvc} @@ -1337,81 +1499,83 @@ class wxDataViewToggleRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ wxDataViewToggleRenderer(const wxString& varianttype = "bool", - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT); + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int align = wxDVR_DEFAULT_ALIGNMENT); }; - /** - @class wxDataViewDateRenderer - @wxheader{dataview.h} + @class wxDataViewChoiceRenderer - wxDataViewDateRenderer + 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. @library{wxadv} @category{dvc} */ -class wxDataViewDateRenderer : public wxDataViewRenderer + +class wxDataViewChoiceRenderer: public wxDataViewRenderer { public: /** + The ctor. + */ + wxDataViewChoiceRenderer( const wxArrayString &choices, + wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE, + int alignment = wxDVR_DEFAULT_ALIGNMENT ); + /** + Returns the choice referred to by index. */ - wxDataViewDateRenderer(const wxString& varianttype = "datetime", - wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE); + wxString GetChoice(size_t index) const; + + /** + Returns all choices. + */ + const wxArrayString& GetChoices() const; }; - /** - @class wxDataViewTextRendererAttr - @wxheader{dataview.h} - - The same as wxDataViewTextRenderer but with - support for font attributes. Font attributes are currently only supported - under GTK+ and MSW. + @class wxDataViewDateRenderer - See also wxDataViewModel::GetAttr and - wxDataViewItemAttr. + This class is used by wxDataViewCtrl to render calendar controls. @library{wxadv} @category{dvc} */ -class wxDataViewTextRendererAttr : public wxDataViewTextRenderer +class wxDataViewDateRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ - wxDataViewTextRendererAttr(const wxString& varianttype = "string", - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int align = wxDVR_DEFAULT_ALIGNMENT); + wxDataViewDateRenderer(const wxString& varianttype = "datetime", + wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, + int align = wxDVR_DEFAULT_ALIGNMENT); }; /** @class wxDataViewCustomRenderer - @wxheader{dataview.h} You need to derive a new class from wxDataViewCustomRenderer in - order to write a new renderer. You need to override at least - wxDataViewRenderer::SetValue, - wxDataViewRenderer::GetValue, - wxDataViewCustomRenderer::GetSize - and wxDataViewCustomRenderer::Render. - - If you want your renderer to support in-place editing then you - also need to override - wxDataViewCustomRenderer::HasEditorCtrl, - wxDataViewCustomRenderer::CreateEditorCtrl + order to write a new renderer. + + You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue, + wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render. + + If you want your renderer to support in-place editing then you also need to override + wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl and wxDataViewCustomRenderer::GetValueFromEditorCtrl. - Note that a special event handler will be pushed onto that - editor control which handles ENTER and focus out events - in order to end the editing. + + Note that a special event handler will be pushed onto that editor control + which handles @e \ and focus out events in order to end the editing. @library{wxadv} @category{dvc} @@ -1424,86 +1588,113 @@ public: */ wxDataViewCustomRenderer(const wxString& varianttype = "string", wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int align = wxDVR_DEFAULT_ALIGNMENT ); + int align = -1, bool no_init = false); /** Destructor. */ - ~wxDataViewCustomRenderer(); + 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 double clicks or ENTER. + This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode. */ - virtual bool Activate( wxRect cell, + virtual bool Activate( const wxRect& cell, wxDataViewModel* model, const wxDataViewItem & item, unsigned int col ); /** 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: + 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: + @code + { + long l = value; + return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString, + labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l ); + } + @endcode */ - virtual wxControl* CreateEditorCtrl(wxWindow* parent, - wxRect labelRect, - const wxVariant& value); + virtual wxWindow* CreateEditorCtrl(wxWindow* parent, + wxRect labelRect, + const wxVariant& value); /** - Create DC on request. Internal. - */ - virtual wxDC* GetDC(); + Return the attribute to be used for rendering. + + This function may be called from Render() implementation to use the + attributes defined for the item if the renderer supports them. + + Notice that when Render() is called, the wxDC object passed to it is + already set up to use the correct attributes (e.g. its font is set to + bold or italic version if wxDataViewItemAttr::GetBold() or GetItalic() + returns true) so it may not be necessary to call it explicitly if you + only want to render text using the items attributes. + + @since 2.9.1 + */ + const wxDataViewItemAttr& GetAttr() const; /** Return size required to show content. */ - virtual wxSize GetSize(); + virtual wxSize GetSize() const = 0; /** - Overrride this so that the renderer can get the value - from the editor control (pointed to by @e editor): + Override this so that the renderer can get the value from the editor + control (pointed to by @a editor): + @code + { + wxSpinCtrl *sc = (wxSpinCtrl*) editor; + long l = sc->GetValue(); + value = l; + return true; + } + @endcode */ - virtual bool GetValueFromEditorCtrl(wxControl* editor, + virtual bool GetValueFromEditorCtrl(wxWindow* editor, wxVariant& value); /** - Override this and make it return @e @true in order to + Override this and make it return @true in order to indicate that this renderer supports in-place editing. */ - virtual bool HasEditorCtrl(); + virtual bool HasEditorCtrl() const; /** - Overrride this to react to a left click. This method will - only be called in wxDATAVIEW_CELL_ACTIVATABLE mode. + Override this to react to a left click. + This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode. */ - virtual bool LeftClick( wxPoint cursor, - wxRect cell, + virtual bool LeftClick( const wxPoint& cursor, + const wxRect& cell, wxDataViewModel * model, const wxDataViewItem & item, unsigned int col ); /** - Override this to render the cell. Before this is called, - wxDataViewRenderer::SetValue was called + Override this to render the cell. + Before this is called, wxDataViewRenderer::SetValue was called so that this instance knows what to render. */ - virtual bool Render(wxRect cell, wxDC* dc, int state); + virtual bool Render(wxRect cell, wxDC* dc, int state) = 0; /** - This method should be called from within Render() - whenever you need to render simple text. This will ensure that the - correct colour, font and vertical alignment will be chosen so the - text will look the same as text drawn by native renderers. + This method should be called from within Render() whenever you need to + render simple text. + This will ensure that the correct colour, font and vertical alignment will + be chosen so the text will look the same as text drawn by native renderers. */ - bool RenderText(const wxString& text, int xoffset, wxRect cell, + void RenderText(const wxString& text, int xoffset, wxRect cell, wxDC* dc, int state); /** - Overrride this to start a drag operation. Not yet - supported + Override this to start a drag operation. Not yet supported. */ - virtual bool StartDrag(wxPoint cursor, wxRect cell, + virtual bool StartDrag(const wxPoint& cursor, + const wxRect& cell, wxDataViewModel* model, const wxDataViewItem & item, unsigned int col); @@ -1513,9 +1704,8 @@ public: /** @class wxDataViewBitmapRenderer - @wxheader{dataview.h} - wxDataViewBitmapRenderer + This class is used by wxDataViewCtrl to render bitmap controls. @library{wxadv} @category{dvc} @@ -1524,180 +1714,455 @@ class wxDataViewBitmapRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap", wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int align = wxDVR_DEFAULT_ALIGNMENT, + int align = wxDVR_DEFAULT_ALIGNMENT); }; +/** + The flags used by wxDataViewColumn. + Can be combined together. +*/ +enum wxDataViewColumnFlags +{ + wxDATAVIEW_COL_RESIZABLE = 1, + wxDATAVIEW_COL_SORTABLE = 2, + wxDATAVIEW_COL_REORDERABLE = 4, + wxDATAVIEW_COL_HIDDEN = 8 +}; /** @class wxDataViewColumn - @wxheader{dataview.h} This class represents a column in a wxDataViewCtrl. - One wxDataViewColumn is bound to one column in the data model, - to which the wxDataViewCtrl has been associated. + One wxDataViewColumn is bound to one column in the data model to which the + wxDataViewCtrl has been associated. - An instance of wxDataViewRenderer is used by - this class to render its data. + An instance of wxDataViewRenderer is used by this class to render its data. @library{wxadv} @category{dvc} */ -class wxDataViewColumn : public wxObject +class wxDataViewColumn : public wxSettableHeaderColumn { public: - //@{ /** - Constructors. + Constructs a text column. + + @param title + The title of the column. + @param renderer + The class which will render the contents of this column. + @param model_column + The index of the model's column which is associated with this object. + @param width + The width of the column. + The @c wxDVC_DEFAULT_WIDTH value is the fixed default value. + @param align + The alignment of the column title. + @param flags + One or more flags of the ::wxDataViewColumnFlags enumeration. */ wxDataViewColumn(const wxString& title, wxDataViewRenderer* renderer, unsigned int model_column, int width = wxDVC_DEFAULT_WIDTH, - wxAlignment align = wxALIGN_CENTRE, + wxAlignment align = wxALIGN_CENTER, int flags = wxDATAVIEW_COL_RESIZABLE); + + /** + Constructs a bitmap column. + + @param bitmap + The bitmap of the column. + @param renderer + The class which will render the contents of this column. + @param model_column + The index of the model's column which is associated with this object. + @param width + The width of the column. + The @c wxDVC_DEFAULT_WIDTH value is the fixed default value. + @param align + The alignment of the column title. + @param flags + One or more flags of the ::wxDataViewColumnFlags enumeration. + */ wxDataViewColumn(const wxBitmap& bitmap, wxDataViewRenderer* renderer, unsigned int model_column, int width = wxDVC_DEFAULT_WIDTH, - wxAlignment align = wxALIGN_CENTRE, + wxAlignment align = wxALIGN_CENTER, int flags = wxDATAVIEW_COL_RESIZABLE); + + /** + Returns the index of the column of the model, which this + wxDataViewColumn is displaying. + */ + unsigned int GetModelColumn() const; + + /** + Returns the owning wxDataViewCtrl. + */ + wxDataViewCtrl* GetOwner() const; + + /** + Returns the renderer of this wxDataViewColumn. + + @see wxDataViewRenderer. + */ + wxDataViewRenderer* GetRenderer() const; +}; + + + +/** + @class wxDataViewListCtrl + + This class is a wxDataViewCtrl which internally uses a wxDataViewListStore + and forwards most of its API to that class. + + The purpose of this class is to offer a simple way to display and + edit a small table of data without having to write your own wxDataViewModel. + + @code + wxDataViewListCtrl *listctrl = new wxDataViewListCtrl( parent, wxID_ANY ); + + listctrl->AppendToggleColumn( "Toggle" ); + listctrl->AppendTextColumn( "Text" ); + + wxVector data; + data.push_back( wxVariant(true) ); + data.push_back( wxVariant("row 1") ); + listctrl->AppendItem( data ); + + data.clear(); + data.push_back( wxVariant(false) ); + data.push_back( wxVariant("row 3") ); + listctrl->AppendItem( data ); + @endcode + + @beginStyleTable + See wxDataViewCtrl for the list of supported styles. + @endStyleTable + + @beginEventEmissionTable + See wxDataViewCtrl for the list of events emitted by this class. + @endEventTable + + @library{wxadv} + @category{ctrl,dvc} +*/ +class wxDataViewListCtrl: public wxDataViewCtrl +{ +public: + /** + Default ctor. + */ + wxDataViewListCtrl(); + + /** + Constructor. Calls Create(). + */ + wxDataViewListCtrl( wxWindow *parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES, + const wxValidator& validator = wxDefaultValidator ); + + /** + Destructor. Deletes the image list if any. + */ + ~wxDataViewListCtrl(); + + /** + Creates the control and a wxDataViewListStore as its internal model. + */ + bool Create( wxWindow *parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES, + const wxValidator& validator = wxDefaultValidator ); + + //@{ + /** + Returns the store. + */ + wxDataViewListStore *GetStore(); + const wxDataViewListStore *GetStore() const; //@} /** - Destructor. + Returns the position of given @e item or wxNOT_FOUND if it's + not a valid item. + + @since 2.9.2 + */ + int ItemToRow(const wxDataViewItem &item) const; + + /** + Returns the wxDataViewItem at the given @e row. + + @since 2.9.2 + */ + wxDataViewItem RowToItem(int row) const; + + //@{ + /** + @name Selection handling functions + */ + + /** + Returns index of the selected row or wxNOT_FOUND. + + @see wxDataViewCtrl::GetSelection() + + @since 2.9.2 + */ + int GetSelectedRow() const; + + /** + Selects given row. + + @see wxDataViewCtrl::Select() + + @since 2.9.2 + */ + void SelectRow(unsigned row); + + /** + Unselects given row. + + @see wxDataViewCtrl::Unselect() + + @since 2.9.2 + */ + void UnselectRow(unsigned row); + + /** + Returns true if @a row is selected. + + @see wxDataViewCtrl::IsSelected() + + @since 2.9.2 + */ + bool IsRowSelected(unsigned row) const; + + //@} + + /** + @name Column management functions */ - ~wxDataViewColumn(); + //@{ /** - Returns the bitmap in the header of the column, if any. + Appends a column to the control and additionally appends a + column to the store with the type string. */ - const wxBitmap GetBitmap(); + virtual void AppendColumn( wxDataViewColumn *column ); /** - Returns the index of the column of the model, which this - wxDataViewColumn is displaying. + Appends a column to the control and additionally appends a + column to the list store with the type @a varianttype. */ - unsigned int GetModelColumn(); + void AppendColumn( wxDataViewColumn *column, const wxString &varianttype ); /** - Returns the owning wxDataViewCtrl. + Appends a text column to the control and the store. + + See wxDataViewColumn::wxDataViewColumn for more info about + the parameters. */ - wxDataViewCtrl* GetOwner() const; + wxDataViewColumn *AppendTextColumn( const wxString &label, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE ); /** - Returns the renderer of this wxDataViewColumn. - See also wxDataViewRenderer. + Appends a toggle column to the control and the store. + + See wxDataViewColumn::wxDataViewColumn for more info about + the parameters. */ - wxDataViewRenderer* GetRenderer(); + wxDataViewColumn *AppendToggleColumn( const wxString &label, + wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, + int width = -1, wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE ); /** - Returns @true if the column is reorderable. + Appends a progress column to the control and the store. + + See wxDataViewColumn::wxDataViewColumn for more info about + the parameters. */ - bool GetReorderable(); + wxDataViewColumn *AppendProgressColumn( const wxString &label, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE ); /** - Returns @true if the column is sortable. - See SetSortable() + Appends an icon-and-text column to the control and the store. + + See wxDataViewColumn::wxDataViewColumn for more info about + the parameters. */ - bool GetSortable(); + wxDataViewColumn *AppendIconTextColumn( const wxString &label, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE ); /** - Returns the width of the column. + Inserts a column to the control and additionally inserts a + column to the store with the type string. */ - int GetWidth(); + virtual void InsertColumn( unsigned int pos, wxDataViewColumn *column ); /** - Returns @true, if the sort order is ascending. - See also SetSortOrder() + Inserts a column to the control and additionally inserts a + column to the list store with the type @a varianttype. */ - bool IsSortOrderAscending(); + void InsertColumn( unsigned int pos, wxDataViewColumn *column, + const wxString &varianttype ); /** - Set the alignment of the column header. + Prepends a column to the control and additionally prepends a + column to the store with the type string. */ - void SetAlignment(wxAlignment align); + virtual void PrependColumn( wxDataViewColumn *column ); /** - Set the bitmap of the column header. + Prepends a column to the control and additionally prepends a + column to the list store with the type @a varianttype. */ - void SetBitmap(const wxBitmap& bitmap); + void PrependColumn( wxDataViewColumn *column, const wxString &varianttype ); + + //@} + /** - Indicate wether the column can be reordered by the - user using the mouse. This is typically implemented - visually by dragging the header button around. + @name Item management functions */ - void SetReorderable(bool reorderable); + //@{ /** - Indicate the sort order if the implementation of the - wxDataViewCtrl supports it, most commonly by showing - a little arrow. + Appends an item (=row) to the control and store. */ - void SetSortOrder(bool ascending); + void AppendItem( const wxVector &values, wxClientData *data = NULL ); /** - Indicate that the column is sortable. This does - not show any sorting indicate yet, but it does - make the column header clickable. Call - SetSortOrder() - afterwards to actually make the sort indicator appear. - If @a sortable is @false, the column header is - no longer clickable and the sort indicator (little - arrow) will disappear. + Prepends an item (=row) to the control and store. */ - void SetSortable(bool sortable); + void PrependItem( const wxVector &values, wxClientData *data = NULL ); /** - Set the title of the column header to @e title. + Inserts an item (=row) to the control and store. */ - void SetTitle(const wxString& title); -}; + void InsertItem( unsigned int row, const wxVector &values, wxClientData *data = NULL ); + /** + Delete the row at position @a row. + */ + void DeleteItem( unsigned row ); + + /** + Delete all items (= all rows). + */ + void DeleteAllItems(); + + /** + Sets the value in the store and update the control. + */ + void SetValue( const wxVariant &value, unsigned int row, unsigned int col ); + + /** + Returns the value from the store. + */ + void GetValue( wxVariant &value, unsigned int row, unsigned int col ); + + /** + Sets the value in the store and update the control. + + This method assumes that the string is stored in respective + column. + */ + void SetTextValue( const wxString &value, unsigned int row, unsigned int col ); + + /** + Returns the value from the store. + + This method assumes that the string is stored in respective + column. + */ + wxString GetTextValue( unsigned int row, unsigned int col ) const; + + /** + Sets the value in the store and update the control. + + This method assumes that the boolean value is stored in + respective column. + */ + void SetToggleValue( bool value, unsigned int row, unsigned int col ); + + /** + Returns the value from the store. + + This method assumes that the boolean value is stored in + respective column. + */ + bool GetToggleValue( unsigned int row, unsigned int col ) const; + + //@} +}; /** @class wxDataViewTreeCtrl - @wxheader{dataview.h} - This class is a wxDataViewCtrl which internally - uses a wxDataViewTreeStore and forwards - most of its API to that class. Additionally, it uses a wxImageList - to store a list of icons. The main purpose of this class is to look - like a wxTreeCtrl to make a transition from it - to the wxDataViewCtrl class simpler. + This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore + and forwards most of its API to that class. + Additionally, it uses a wxImageList to store a list of icons. + + The main purpose of this class is to provide a simple upgrade path for code + using wxTreeCtrl. - @library{wxbase} + @beginStyleTable + See wxDataViewCtrl for the list of supported styles. + @endStyleTable + + @beginEventEmissionTable + See wxDataViewCtrl for the list of events emitted by this class. + @endEventTable + + @library{wxadv} @category{ctrl,dvc} - + @appearance{dataviewtreectrl.png} */ class wxDataViewTreeCtrl : public wxDataViewCtrl { public: - //@{ /** - Constructor. Calls Create(). + Default ctor. */ wxDataViewTreeCtrl(); + + /** + Constructor. + + Calls Create(). + */ wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxDV_NO_HEADER, + long style = wxDV_NO_HEADER | wxDV_ROW_LINES, const wxValidator& validator = wxDefaultValidator); - //@} /** Destructor. Deletes the image list if any. */ - ~wxDataViewTreeCtrl(); + virtual ~wxDataViewTreeCtrl(); /** - + Appends a container to the given @a parent. */ wxDataViewItem AppendContainer(const wxDataViewItem& parent, const wxString& text, @@ -1706,7 +2171,7 @@ public: wxClientData* data = NULL); /** - + Appends an item to the given @a parent. */ wxDataViewItem AppendItem(const wxDataViewItem& parent, const wxString& text, @@ -1714,13 +2179,15 @@ public: wxClientData* data = NULL); /** - Creates the control and a wxDataViewTreeStore as - its internal model. + Creates the control and a wxDataViewTreeStore as its internal model. + + The default tree column created by this method is an editable column + using wxDataViewIconTextRenderer as its renderer. */ bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, - long style = wxDV_NO_HEADER, + long style = wxDV_NO_HEADER | wxDV_ROW_LINES, const wxValidator& validator = wxDefaultValidator); /** @@ -1756,12 +2223,12 @@ public: /** Calls the identical method from wxDataViewTreeStore. */ - const wxIcon GetItemExpandedIcon(const wxDataViewItem& item) const; + const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const; /** Calls the identical method from wxDataViewTreeStore. */ - const wxIcon GetItemIcon(const wxDataViewItem& item) const; + const wxIcon& GetItemIcon(const wxDataViewItem& item) const; /** Calls the identical method from wxDataViewTreeStore. @@ -1778,13 +2245,13 @@ public: /** Returns the store. */ - wxDataViewTreeStore* GetStore() const; + wxDataViewTreeStore* GetStore(); const wxDataViewTreeStore* GetStore() const; //@} /** - Calls the same method from wxDataViewTreeStore but uess - and index position in the image list instead of a wxIcon. + Calls the same method from wxDataViewTreeStore but uses + an index position in the image list instead of a wxIcon. */ wxDataViewItem InsertContainer(const wxDataViewItem& parent, const wxDataViewItem& previous, @@ -1794,8 +2261,8 @@ public: wxClientData* data = NULL); /** - Calls the same method from wxDataViewTreeStore but uess - and index position in the image list instead of a wxIcon. + Calls the same method from wxDataViewTreeStore but uses + an index position in the image list instead of a wxIcon. */ wxDataViewItem InsertItem(const wxDataViewItem& parent, const wxDataViewItem& previous, @@ -1804,8 +2271,13 @@ public: wxClientData* data = NULL); /** - Calls the same method from wxDataViewTreeStore but uess - and index position in the image list instead of a wxIcon. + Returns true if item is a container. + */ + bool IsContainer( const wxDataViewItem& item ); + + /** + Calls the same method from wxDataViewTreeStore but uses + an index position in the image list instead of a wxIcon. */ wxDataViewItem PrependContainer(const wxDataViewItem& parent, const wxString& text, @@ -1814,8 +2286,8 @@ public: wxClientData* data = NULL); /** - Calls the same method from wxDataViewTreeStore but uess - and index position in the image list instead of a wxIcon. + Calls the same method from wxDataViewTreeStore but uses + an index position in the image list instead of a wxIcon. */ wxDataViewItem PrependItem(const wxDataViewItem& parent, const wxString& text, @@ -1851,17 +2323,137 @@ public: }; +/** + @class wxDataViewListStore + + wxDataViewListStore is a specialised wxDataViewModel for storing + a simple table of data. Since it derives from wxDataViewIndexListModel + its data is be accessed by row (i.e. by index) instead of only + by wxDataViewItem. + + This class actually stores the values (therefore its name) + and implements all virtual methods from the base classes so it can be + used directly without having to derive any class from it, but it is + mostly used from within wxDataViewListCtrl. + + @library{wxadv} + @category{dvc} +*/ + +class wxDataViewListStore: public wxDataViewIndexListModel +{ +public: + /** + Constructor + */ + wxDataViewListStore(); + + /** + Destructor + */ + ~wxDataViewListStore(); + + /** + Prepends a data column. + + @a variantype indicates the type of values store in the column. + + This does not automatically fill in any (default) values in + rows which exist in the store already. + */ + void PrependColumn( const wxString &varianttype ); + + /** + Inserts a data column before @a pos. + + @a variantype indicates the type of values store in the column. + + This does not automatically fill in any (default) values in + rows which exist in the store already. + */ + void InsertColumn( unsigned int pos, const wxString &varianttype ); + + /** + Appends a data column. + + @a variantype indicates the type of values store in the column. + + This does not automatically fill in any (default) values in + rows which exist in the store already. + */ + void AppendColumn( const wxString &varianttype ); + + /** + Appends an item (=row) and fills it with @a values. + + The values must match the values specifies in the column + in number and type. No (default) values are filled in + automatically. + */ + void AppendItem( const wxVector &values, wxClientData *data = NULL ); + + /** + Prepends an item (=row) and fills it with @a values. + + The values must match the values specifies in the column + in number and type. No (default) values are filled in + automatically. + */ + void PrependItem( const wxVector &values, wxClientData *data = NULL ); + + /** + Inserts an item (=row) and fills it with @a values. + + The values must match the values specifies in the column + in number and type. No (default) values are filled in + automatically. + */ + void InsertItem( unsigned int row, const wxVector &values, wxClientData *data = NULL ); + + /** + Delete the item (=row) at position @a pos. + */ + void DeleteItem( unsigned pos ); + + /** + Delete all item (=all rows) in the store. + */ + void DeleteAllItems(); + + /** + Overridden from wxDataViewModel + */ + virtual unsigned int GetColumnCount() const; + + /** + Overridden from wxDataViewModel + */ + virtual wxString GetColumnType( unsigned int col ) const; + + /** + Overridden from wxDataViewIndexListModel + */ + virtual void GetValueByRow( wxVariant &value, + unsigned int row, unsigned int col ) const; + + /** + Overridden from wxDataViewIndexListModel + */ + virtual bool SetValueByRow( const wxVariant &value, + unsigned int row, unsigned int col ); +}; + /** @class wxDataViewTreeStore - @wxheader{dataview.h} - wxDataViewTreeStore is a specialised wxDataViewModel - for displaying simple trees very much like wxTreeCtrl - does and it offers a similar API. This class actually stores the entire - tree (therefore its name) and implements all virtual methods from the base - class so it can be used directly without having to derive any class from it. - This comes at the price of much reduced flexibility. + wxDataViewTreeStore is a specialised wxDataViewModel for storing simple + trees very much like wxTreeCtrl does and it offers a similar API. + + This class actually stores the entire tree and the values (therefore its name) + and implements all virtual methods from the base class so it can be used directly + without having to derive any class from it, but it is mostly used from within + wxDataViewTreeCtrl. @library{wxadv} @category{dvc} @@ -1877,7 +2469,7 @@ public: /** Destructor. */ - ~wxDataViewTreeStore(); + virtual ~wxDataViewTreeStore(); /** Append a container. @@ -1917,19 +2509,19 @@ public: int GetChildCount(const wxDataViewItem& parent) const; /** - Returns the client data asoociated with the item. + Returns the client data associated with the item. */ wxClientData* GetItemData(const wxDataViewItem& item) const; /** Returns the icon to display in expanded containers. */ - const wxIcon GetItemExpandedIcon(const wxDataViewItem& item) const; + const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const; /** Returns the icon of the item. */ - const wxIcon GetItemIcon(const wxDataViewItem& item) const; + const wxIcon& GetItemIcon(const wxDataViewItem& item) const; /** Returns the text of the item. @@ -1943,7 +2535,7 @@ public: unsigned int pos) const; /** - Inserts a container after @e previous. + Inserts a container after @a previous. */ wxDataViewItem InsertContainer(const wxDataViewItem& parent, const wxDataViewItem& previous, @@ -1953,7 +2545,7 @@ public: wxClientData* data = NULL); /** - Inserts an item after @e previous. + Inserts an item after @a previous. */ wxDataViewItem InsertItem(const wxDataViewItem& parent, const wxDataViewItem& previous, @@ -1962,7 +2554,7 @@ public: wxClientData* data = NULL); /** - Inserts a container before the first child item or @e parent. + Inserts a container before the first child item or @a parent. */ wxDataViewItem PrependContainer(const wxDataViewItem& parent, const wxString& text, @@ -1971,7 +2563,7 @@ public: wxClientData* data = NULL); /** - Inserts an item before the first child item or @e parent. + Inserts an item before the first child item or @a parent. */ wxDataViewItem PrependItem(const wxDataViewItem& parent, const wxString& text, @@ -1995,3 +2587,223 @@ public: void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon); }; + +/** + @class wxDataViewIconText + + wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer. + This class can be converted to and from a wxVariant. + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewIconText : public wxObject +{ +public: + //@{ + /** + Constructor. + */ + wxDataViewIconText(const wxString& text = wxEmptyString, + const wxIcon& icon = wxNullIcon); + wxDataViewIconText(const wxDataViewIconText& other); + //@} + + /** + Gets the icon. + */ + const wxIcon& GetIcon() const; + + /** + Gets the text. + */ + wxString GetText() const; + + /** + Set the icon. + */ + void SetIcon(const wxIcon& icon); + + /** + Set the text. + */ + void SetText(const wxString& text); +}; + + + +/** + @class wxDataViewEvent + + This is the event class for the wxDataViewCtrl notifications. + + @beginEventTable{wxDataViewEvent} + @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event. + @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. + @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event. + @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event. + @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event. + @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event. + @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event. + @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event. + @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event. + @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event. + @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event. + @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event. + @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event. + @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event. + @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event. + @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event. + @event{EVT_DATAVIEW_ITEM_DROP(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event. + @event{EVT_DATAVIEW_CACHE_HINT(id, func)} + Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event. + @endEventTable + + @library{wxadv} + @category{events,dvc} +*/ +class wxDataViewEvent : public wxNotifyEvent +{ +public: + /** + Constructor. Typically used by wxWidgets internals only. + */ + wxDataViewEvent(wxEventType commandType = wxEVT_NULL, + int winid = 0); + + /** + Returns the position of the column in the control or -1 + if no column field was set by the event emitter. + */ + int GetColumn() const; + + /** + Returns a pointer to the wxDataViewColumn from which + the event was emitted or @NULL. + */ + wxDataViewColumn* GetDataViewColumn() const; + + /** + Returns the wxDataViewModel associated with the event. + */ + wxDataViewModel* GetModel() const; + + /** + Returns the position of a context menu event in screen coordinates. + */ + wxPoint GetPosition() const; + + /** + Returns a reference to a value. + */ + const wxVariant& GetValue() const; + + /** + Can be used to determine whether the new value is going to be accepted + in wxEVT_COMMAND_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 + call wxNotifyEvent::Veto() to prevent this from happening. + + Currently support for setting this field and for vetoing the change is + only available in the generic version of wxDataViewCtrl, i.e. under MSW + but not GTK nor OS X. + + @since 2.9.3 + */ + bool IsEditCancelled() const; + + /** + Sets the column index associated with this event. + */ + void SetColumn(int col); + + /** + For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only. + */ + void SetDataViewColumn(wxDataViewColumn* col); + + /** + Sets the dataview model associated with this event. + */ + void SetModel(wxDataViewModel* model); + + /** + Sets the value associated with this event. + */ + void SetValue(const wxVariant& value); + + /** + Set wxDataObject for data transfer within a drag operation. + */ + 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. + */ + void SetDataSize( size_t size ); + + /** + Gets the data size for a drop data transfer. + */ + size_t GetDataSize() const; + + /** + Used internally. Sets the data buffer for a drop data transfer. + */ + void SetDataBuffer( void* buf ); + + /** + Gets the data buffer for a drop data transfer. + */ + void *GetDataBuffer() const; + + /** + Return the first row that will be displayed. + */ + int GetCacheFrom() const; + + /** + Return the last row that will be displayed. + */ + int GetCacheTo() const; +}; +