X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7d01d660c17e064b0ab6c3d5d53bcac8aea0806d..5b88a837ba75928cd3835a6b97ae2bf5ad983a6e:/interface/wx/dataview.h diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h index 50ffa94920..79db099c1f 100644 --- a/interface/wx/dataview.h +++ b/interface/wx/dataview.h @@ -1,214 +1,80 @@ ///////////////////////////////////////////////////////////////////////////// // Name: dataview.h -// Purpose: interface of wxDataViewIconText +// Purpose: interface of wxDataView* classes // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/** - @class wxDataViewIconText - - 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 - - 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 + wxDataViewModel is the base class for all data model to be displayed by a + wxDataViewCtrl. -/** - @class wxDataViewModel + 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. - 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 + Since you will usually also 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::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 + 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 + 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 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 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 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 - @library{wxadv} @category{dvc} */ @@ -221,19 +87,13 @@ public: wxDataViewModel(); /** - Destructor. This should not be called directly. Use DecRef() instead. - */ - ~wxDataViewModel(); - - /** - Adds a wxDataViewModelNotifier - to the model. + Adds a wxDataViewModelNotifier to the model. */ void AddNotifier(wxDataViewModelNotifier* notifier); /** - 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(); @@ -241,61 +101,61 @@ 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; /** - 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 has special font attributes. + This only affects the wxDataViewTextRendererText renderer. + + @see wxDataViewItemAttr. */ - bool GetAttr(const wxDataViewItem& item, unsigned int col, - wxDataViewItemAttr& attr); + virtual bool GetAttr(const wxDataViewItem& item, unsigned int col, + wxDataViewItemAttr& attr); /** - 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 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 futher columns. By default returns @false. */ virtual bool HasContainerColumns(const wxDataViewItem& item) const; @@ -303,10 +163,11 @@ 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; @@ -314,17 +175,17 @@ public: 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, const wxDataViewItem& item); /** Call this to inform the model that an item has changed. + This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED event (in which the column fields will not be set) to the user. */ @@ -337,14 +198,14 @@ public: 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, const wxDataViewItemArray& items); /** Call this to inform the model that several items have changed. + This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED events (in which the column fields will not be set) to the user. */ @@ -362,32 +223,37 @@ 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. + + Afterwards ValueChanged() has to be called! */ - virtual bool SetValue(const wxVariant& variant, - const wxDataViewItem& item, - unsigned int col); + virtual bool SetValue(const wxVariant& variant, const wxDataViewItem& item, + 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. + 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 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(); }; @@ -395,18 +261,17 @@ public: /** @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). + 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. - @library{wxbase} + 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. + + @library{wxadv} @category{dvc} */ class wxDataViewIndexListModel : public wxDataViewModel @@ -420,7 +285,7 @@ public: /** Destructor. */ - ~wxDataViewIndexListModel(); + virtual ~wxDataViewIndexListModel(); /** Compare method that sorts the items by their index. @@ -430,13 +295,13 @@ 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. + + @see wxDataViewItemAttr. */ - bool GetAttr(unsigned int row, unsigned int col, - wxDataViewItemAttr& attr); + virtual bool GetAttrByRow(unsigned int row, unsigned int col, + wxDataViewItemAttr& attr); /** Returns the wxDataViewItem at the given @e row. @@ -451,14 +316,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); @@ -493,17 +357,17 @@ 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; }; @@ -511,18 +375,17 @@ public: /** @class wxDataViewVirtualListModel - 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 + 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 the Carbon API under OS X). @see wxDataViewIndexListModel for the API. - @library{wxbase} + @library{wxadv} @category{dvc} */ class wxDataViewVirtualListModel : public wxDataViewModel @@ -539,13 +402,11 @@ public: /** @class wxDataViewItemAttr - 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} @@ -564,8 +425,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); @@ -580,20 +440,17 @@ public: /** @class wxDataViewItem - 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. 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 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} @@ -604,7 +461,7 @@ class wxDataViewItem public: //@{ /** - + Constructor. */ wxDataViewItem(void* id = NULL); wxDataViewItem(const wxDataViewItem& item); @@ -616,7 +473,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; }; @@ -626,36 +483,31 @@ public: /** @class wxDataViewCtrl - 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} @@ -669,43 +521,54 @@ public: @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. @endStyleTable - @beginEventTable{wxDataViewEvent} + @beginEventEmissionTable{wxDataViewEvent} @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event. + Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event. @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. + 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 wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event. + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event. @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event. + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event. @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event. + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event. @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event. + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event. @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event. + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event. @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event. + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event. @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event. + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event. @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event. + Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event. @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event. + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event. @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event. + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event. @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event. + Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event. @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)} - Process a wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event. + 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 { @@ -714,7 +577,7 @@ public: Default Constructor. */ wxDataViewCtrl(); - + /** Constructor. Calls Create(). */ @@ -727,10 +590,11 @@ public: /** 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). */ @@ -738,6 +602,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. */ @@ -747,7 +612,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 @@ -771,44 +636,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); //@} @@ -816,9 +681,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, @@ -838,21 +703,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); //@} @@ -860,9 +725,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, @@ -879,8 +744,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); @@ -889,15 +754,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. @@ -911,23 +771,39 @@ public: /** 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; @@ -954,25 +830,23 @@ public: /** Returns item rect. */ - wxRect GetItemRect(const wxDataViewItem& item, - const wxDataViewColumn* col = NULL) const; + 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 @@ -983,23 +857,28 @@ 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. */ - 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. @@ -1014,18 +893,18 @@ public: /** Sets the selection to the array of wxDataViewItems. */ - void SetSelections(const wxDataViewItemArray& sel); + virtual void SetSelections(const wxDataViewItemArray& sel); /** 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(); }; @@ -1033,13 +912,11 @@ public: /** @class wxDataViewModelNotifier - 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 @@ -1053,12 +930,12 @@ public: /** Destructor. */ - ~wxDataViewModelNotifier(); + virtual ~wxDataViewModelNotifier(); /** Called by owning model. */ - bool Cleared(); + virtual bool Cleared() = 0; /** Get owning wxDataViewModel. @@ -1068,41 +945,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. @@ -1112,62 +989,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 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, + - wxDataViewTextRendererAttr, + - wxDataViewIconTextRenderer, + - wxDataViewToggleRenderer, + - wxDataViewProgressRenderer, + - wxDataViewBitmapRenderer, + - wxDataViewDateRenderer, + - wxDataViewSpinRenderer. 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} @@ -1176,7 +1055,7 @@ class wxDataViewRenderer : public wxObject { public: /** - Constructor. + Constructor. */ wxDataViewRenderer(const wxString& varianttype, wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, @@ -1190,54 +1069,55 @@ public: /** 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. @@ -1250,8 +1130,8 @@ public: /** @class wxDataViewTextRenderer - 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} @@ -1260,7 +1140,7 @@ class wxDataViewTextRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ wxDataViewTextRenderer(const wxString& varianttype = "string", wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, @@ -1274,9 +1154,9 @@ public: 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 + + This classes uses the wxDataViewIconText helper class to store its data. + wxDataViewIonText can be converted to and from a wxVariant using the left shift operator. @library{wxadv} @@ -1286,7 +1166,7 @@ class wxDataViewIconTextRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText", wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, @@ -1298,7 +1178,7 @@ public: /** @class wxDataViewProgressRenderer - wxDataViewProgressRenderer + This class is used by wxDataViewCtrl to render progress bars. @library{wxadv} @category{dvc} @@ -1307,7 +1187,7 @@ class wxDataViewProgressRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ wxDataViewProgressRenderer(const wxString& label = wxEmptyString, const wxString& varianttype = "long", @@ -1320,19 +1200,19 @@ public: /** @class wxDataViewSpinRenderer - 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, @@ -1344,7 +1224,7 @@ public: /** @class wxDataViewToggleRenderer - wxDataViewToggleRenderer + This class is used by wxDataViewCtrl to render toggle controls. @library{wxadv} @category{dvc} @@ -1353,10 +1233,11 @@ 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); }; @@ -1364,7 +1245,7 @@ public: /** @class wxDataViewDateRenderer - wxDataViewDateRenderer + This class is used by wxDataViewCtrl to render calendar controls. @library{wxadv} @category{dvc} @@ -1373,10 +1254,11 @@ class wxDataViewDateRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ wxDataViewDateRenderer(const wxString& varianttype = "datetime", - wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE); + wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, + int align = wxDVR_DEFAULT_ALIGNMENT); }; @@ -1384,12 +1266,10 @@ public: /** @class wxDataViewTextRendererAttr - The same as wxDataViewTextRenderer but with - support for font attributes. Font attributes are currently only supported - under GTK+ and MSW. + The same as wxDataViewTextRenderer but with support for font attributes. + Font attributes are currently only supported under GTK+ and MSW. - See also wxDataViewModel::GetAttr and - wxDataViewItemAttr. + @see wxDataViewModel::GetAttr and wxDataViewItemAttr. @library{wxadv} @category{dvc} @@ -1398,7 +1278,7 @@ class wxDataViewTextRendererAttr : public wxDataViewTextRenderer { public: /** - + The ctor. */ wxDataViewTextRendererAttr(const wxString& varianttype = "string", wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, @@ -1411,20 +1291,17 @@ public: @class wxDataViewCustomRenderer 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} @@ -1437,16 +1314,16 @@ 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, wxDataViewModel* model, @@ -1455,9 +1332,17 @@ public: /** 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, @@ -1471,24 +1356,32 @@ public: /** 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): + Overrride 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, 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. + Overrride 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, @@ -1497,24 +1390,23 @@ public: 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 + Overrride this to start a drag operation. Not yet supported. */ virtual bool StartDrag(wxPoint cursor, wxRect cell, wxDataViewModel* model, @@ -1527,7 +1419,7 @@ public: /** @class wxDataViewBitmapRenderer - wxDataViewBitmapRenderer + This class is used by wxDataViewCtrl to render bitmap controls. @library{wxadv} @category{dvc} @@ -1536,64 +1428,94 @@ 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 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); - //@} - - /** - Destructor. - */ - ~wxDataViewColumn(); - - /** - Returns the bitmap in the header of the column, if any. - */ - const wxBitmap GetBitmap(); /** Returns the index of the column of the model, which this wxDataViewColumn is displaying. */ - unsigned int GetModelColumn(); + unsigned int GetModelColumn() const; /** Returns the owning wxDataViewCtrl. @@ -1602,112 +1524,299 @@ public: /** Returns the renderer of this wxDataViewColumn. - See also wxDataViewRenderer. - */ - wxDataViewRenderer* GetRenderer(); - /** - Returns @true if the column is reorderable. + @see wxDataViewRenderer. */ - bool GetReorderable(); + wxDataViewRenderer* GetRenderer() const; +}; - /** - Returns @true if the column is sortable. - See SetSortable() - */ - bool GetSortable(); - /** - Returns the width of the column. - */ - int GetWidth(); - /** - Returns @true, if the sort order is ascending. - See also SetSortOrder() - */ - bool IsSortOrderAscending(); +/** + @class wxDataViewListCtrl - /** - Set the alignment of the column header. + 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. */ - void SetAlignment(wxAlignment align); + wxDataViewListCtrl(); /** - Set the bitmap of the column header. + Constructor. Calls Create(). */ - void SetBitmap(const wxBitmap& bitmap); + wxDataViewListCtrl( wxWindow *parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES, + const wxValidator& validator = wxDefaultValidator ); /** - Indicate wether the column can be reordered by the - user using the mouse. This is typically implemented - visually by dragging the header button around. + Destructor. Deletes the image list if any. */ - void SetReorderable(bool reorderable); + ~wxDataViewListCtrl(); /** - Indicate the sort order if the implementation of the - wxDataViewCtrl supports it, most commonly by showing - a little arrow. + Creates the control and a wxDataViewListStore as its internal model. */ - void SetSortOrder(bool ascending); + bool Create( wxWindow *parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES, + const wxValidator& validator = wxDefaultValidator ); + //@{ /** - 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. + Returns the store. */ - void SetSortable(bool sortable); + wxDataViewListStore *GetStore(); + const wxDataViewListStore *GetStore() const; + //@} /** - Set the title of the column header to @e title. + @name Column management functions */ - void SetTitle(const wxString& title); -}; + //@{ + + /** + Appends a column to the control and additionally appends a + column to the store with the type string. + */ + virtual void AppendColumn( wxDataViewColumn *column ); + + /** + Appends a column to the control and additionally appends a + column to the list store with the type @a varianttype. + */ + void AppendColumn( wxDataViewColumn *column, const wxString &varianttype ); + + /** + Appends a text column to the control and the store. + + See wxDataViewColumn::wxDataViewColumn for more info about + the parameters. + */ + wxDataViewColumn *AppendTextColumn( const wxString &label, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE ); + + /** + Appends a toggle column to the control and the store. + + See wxDataViewColumn::wxDataViewColumn for more info about + the parameters. + */ + wxDataViewColumn *AppendToggleColumn( const wxString &label, + wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, + int width = -1, wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE ); + + /** + Appends a progress column to the control and the store. + + See wxDataViewColumn::wxDataViewColumn for more info about + the parameters. + */ + wxDataViewColumn *AppendProgressColumn( const wxString &label, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE ); + + /** + Appends an icon-and-text column to the control and the store. + + See wxDataViewColumn::wxDataViewColumn for more info about + the parameters. + */ + wxDataViewColumn *AppendIconTextColumn( const wxString &label, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE ); + + /** + Inserts a column to the control and additionally inserts a + column to the store with the type string. + */ + virtual void InsertColumn( unsigned int pos, wxDataViewColumn *column ); + + /** + Inserts a column to the control and additionally inserts a + column to the list store with the type @a varianttype. + */ + void InsertColumn( unsigned int pos, wxDataViewColumn *column, + const wxString &varianttype ); + + /** + Prepends a column to the control and additionally prepends a + column to the store with the type string. + */ + virtual void PrependColumn( wxDataViewColumn *column ); + + /** + Prepends a column to the control and additionally prepends a + column to the list store with the type @a varianttype. + */ + void PrependColumn( wxDataViewColumn *column, const wxString &varianttype ); + + //@} + + + /** + @name Item management functions + */ + //@{ + + /** + Appends an item (=row) to the control and store. + */ + void AppendItem( const wxVector &values, wxClientData *data = NULL ); + + /** + Prepends an item (=row) to the control and store. + */ + void PrependItem( const wxVector &values, wxClientData *data = NULL ); + + /** + Inserts an item (=row) to the control and store. + */ + 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 a 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 a 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 a 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 a boolean value is stored in + respective column. + */ + bool GetToggleValue( unsigned int row, unsigned int col ) const; + + //@} +}; /** @class wxDataViewTreeCtrl - 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 represent a possible replacement for + wxTreeCtrl. + + @beginStyleTable + See wxDataViewCtrl for the list of supported styles. + @endStyleTable + + @beginEventEmissionTable + See wxDataViewCtrl for the list of events emitted by this class. + @endEventTable - @library{wxbase} + @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, 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, @@ -1716,7 +1825,7 @@ public: wxClientData* data = NULL); /** - + Appends an item to the given @a parent. */ wxDataViewItem AppendItem(const wxDataViewItem& parent, const wxString& text, @@ -1724,8 +1833,7 @@ public: wxClientData* data = NULL); /** - Creates the control and a wxDataViewTreeStore as - its internal model. + Creates the control and a wxDataViewTreeStore as its internal model. */ bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, @@ -1766,12 +1874,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. @@ -1788,13 +1896,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, @@ -1804,8 +1912,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, @@ -1814,8 +1922,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 PrependContainer(const wxDataViewItem& parent, const wxString& text, @@ -1824,8 +1932,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, @@ -1861,16 +1969,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(); + + /** + Overriden from wxDataViewModel + */ + virtual unsigned int GetColumnCount() const; + + /** + Overriden from wxDataViewModel + */ + virtual wxString GetColumnType( unsigned int col ) const; + + /** + Overriden from wxDataViewIndexListModel + */ + virtual void GetValueByRow( wxVariant &value, + unsigned int row, unsigned int col ) const; + + /** + Overriden from wxDataViewIndexListModel + */ + virtual bool SetValueByRow( const wxVariant &value, + unsigned int row, unsigned int col ); +}; + /** @class wxDataViewTreeStore - 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 stroing 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} @@ -1886,7 +2115,7 @@ public: /** Destructor. */ - ~wxDataViewTreeStore(); + virtual ~wxDataViewTreeStore(); /** Append a container. @@ -1933,12 +2162,12 @@ public: /** 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. @@ -1952,7 +2181,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, @@ -1962,7 +2191,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, @@ -1971,7 +2200,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, @@ -1980,7 +2209,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, @@ -2004,3 +2233,191 @@ 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. + @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 a the position of a context menu event in screen coordinates. + */ + wxPoint GetPosition() const; + + /** + Returns a reference to a value. + */ + const wxVariant& GetValue() const; + + /** + Sets the column index associated with this event. + */ + void SetColumn(int col); + + /** + For 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; +}; +