X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7d01d660c17e064b0ab6c3d5d53bcac8aea0806d..42fb9cdf6f1778ce06d5545fc37c85a966521f6c:/interface/wx/dataview.h diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h index 50ffa94920..31ed319e15 100644 --- a/interface/wx/dataview.h +++ b/interface/wx/dataview.h @@ -9,12 +9,10 @@ /** @class wxDataViewIconText - wxDataViewIconText is used by - wxDataViewIconTextRenderer - for data transfer. This class can be converted to a from - a wxVariant. + wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer. + This class can be converted to and from a wxVariant. - @library{wxbase} + @library{wxadv} @category{dvc} */ class wxDataViewIconText : public wxObject @@ -32,7 +30,7 @@ public: /** Gets the icon. */ - const wxIcon GetIcon() const; + const wxIcon& GetIcon() const; /** Gets the text. @@ -55,7 +53,7 @@ public: /** @class wxDataViewEvent - wxDataViewEvent - the event class for the wxDataViewCtrl notifications + This is the event class for the wxDataViewCtrl notifications. @library{wxadv} @category{events,dvc} @@ -65,18 +63,13 @@ class wxDataViewEvent : public wxNotifyEvent public: //@{ /** - + Constructor. Typically used by wxWidgets internals only. */ 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. @@ -87,7 +80,7 @@ public: Returns a pointer to the wxDataViewColumn from which the event was emitted or @NULL. */ - wxDataViewColumn* GetDataViewColumn(); + wxDataViewColumn* GetDataViewColumn() const; /** Returns the wxDataViewModel associated with the event. @@ -102,10 +95,10 @@ public: /** Returns a reference to a value. */ - const wxVariant GetValue() const; + const wxVariant& GetValue() const; /** - + Sets the column index associated with this event. */ void SetColumn(int col); @@ -115,12 +108,12 @@ public: 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); }; @@ -130,78 +123,63 @@ public: /** @class wxDataViewModel - 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. + + 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. - 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, ID_MUSIC_CTRL ); wxDataViewModel *musicModel = new MyMusicModel; m_musicCtrl-AssociateModel( musicModel ); musicModel-DecRef(); // avoid memory leak !! @@ -221,19 +199,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,7 +213,8 @@ 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, @@ -250,52 +223,51 @@ public: /** Oberride this to indicate that the item has special font attributes. - This only affects the - wxDataViewTextRendererText() renderer. - See also wxDataViewItemAttr. + 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 +275,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 +287,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 +310,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 +335,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 +373,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 +397,7 @@ public: /** Destructor. */ - ~wxDataViewIndexListModel(); + virtual ~wxDataViewIndexListModel(); /** Compare method that sorts the items by their index. @@ -431,12 +408,12 @@ public: /** Oberride this to indicate that the row has special font attributes. - This only affects the - wxDataViewTextRendererText() renderer. - See also wxDataViewItemAttr. + This only affects the wxDataViewTextRendererText() renderer. + + @see wxDataViewItemAttr. */ - bool GetAttr(unsigned int row, unsigned int col, - wxDataViewItemAttr& attr); + virtual bool GetAttr(unsigned int row, unsigned int col, + wxDataViewItemAttr& attr); /** Returns the wxDataViewItem at the given @e row. @@ -451,14 +428,13 @@ public: /** Override this to allow getting values from the model. */ - void GetValue(wxVariant& variant, unsigned int row, - unsigned int col) const; + virtual void GetValue(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 +469,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 SetValue(const wxVariant& variant, unsigned int row, + unsigned int col) = 0; }; @@ -511,18 +487,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 +514,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 +537,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 +552,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 +573,7 @@ class wxDataViewItem public: //@{ /** - + Constructor. */ wxDataViewItem(void* id = NULL); wxDataViewItem(const wxDataViewItem& item); @@ -616,7 +585,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 +595,27 @@ 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. + + 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. @beginStyleTable @style{wxDV_SINGLE} @@ -669,7 +629,8 @@ 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} @@ -702,10 +663,10 @@ public: @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)} Process a wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event. @endEventTable - + @library{wxadv} @category{ctrl,dvc} - + @appearance{dataviewctrl.png} */ class wxDataViewCtrl : public wxControl { @@ -714,7 +675,7 @@ public: Default Constructor. */ wxDataViewCtrl(); - + /** Constructor. Calls Create(). */ @@ -727,10 +688,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 +700,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 +710,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 +734,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 +779,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 +801,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 +823,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 +842,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 +852,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 +869,29 @@ public: /** Deletes given column. */ - virtual bool DeleteColumn(const wxDataViewColumn* column); + virtual bool DeleteColumn(wxDataViewColumn* column); /** 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 +918,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 +945,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 +981,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 +1000,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 +1018,12 @@ public: /** Destructor. */ - ~wxDataViewModelNotifier(); + virtual ~wxDataViewModelNotifier(); /** Called by owning model. */ - bool Cleared(); + virtual bool Cleared() = 0; /** Get owning wxDataViewModel. @@ -1068,41 +1033,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 +1077,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 +1143,7 @@ class wxDataViewRenderer : public wxObject { public: /** - Constructor. + Constructor. */ wxDataViewRenderer(const wxString& varianttype, wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, @@ -1190,54 +1157,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 +1218,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 +1228,7 @@ class wxDataViewTextRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ wxDataViewTextRenderer(const wxString& varianttype = "string", wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, @@ -1274,9 +1242,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 +1254,7 @@ class wxDataViewIconTextRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText", wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, @@ -1298,7 +1266,7 @@ public: /** @class wxDataViewProgressRenderer - wxDataViewProgressRenderer + This class is used by wxDataViewCtrl to render progress bars. @library{wxadv} @category{dvc} @@ -1307,7 +1275,7 @@ class wxDataViewProgressRenderer : public wxDataViewRenderer { public: /** - + The ctor. */ wxDataViewProgressRenderer(const wxString& label = wxEmptyString, const wxString& varianttype = "long", @@ -1320,19 +1288,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 +1312,7 @@ public: /** @class wxDataViewToggleRenderer - wxDataViewToggleRenderer + This class is used by wxDataViewCtrl to render toggle controls. @library{wxadv} @category{dvc} @@ -1353,10 +1321,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 +1333,7 @@ public: /** @class wxDataViewDateRenderer - wxDataViewDateRenderer + This class is used by wxDataViewCtrl to render calendar controls. @library{wxadv} @category{dvc} @@ -1373,10 +1342,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 +1354,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 +1366,7 @@ class wxDataViewTextRendererAttr : public wxDataViewTextRenderer { public: /** - + The ctor. */ wxDataViewTextRendererAttr(const wxString& varianttype = "string", wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, @@ -1411,20 +1379,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 +1402,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 +1420,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 +1444,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(); /** - 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 +1478,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 +1507,7 @@ public: /** @class wxDataViewBitmapRenderer - wxDataViewBitmapRenderer + This class is used by wxDataViewCtrl to render bitmap controls. @library{wxadv} @category{dvc} @@ -1536,29 +1516,38 @@ 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. +*/ +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 wxHeaderColumn { public: //@{ @@ -1569,31 +1558,21 @@ public: wxDataViewRenderer* renderer, unsigned int model_column, int width = wxDVC_DEFAULT_WIDTH, - wxAlignment align = wxALIGN_CENTRE, + wxAlignment align = wxALIGN_CENTER, int flags = wxDATAVIEW_COL_RESIZABLE); 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,72 +1581,10 @@ public: /** Returns the renderer of this wxDataViewColumn. - See also wxDataViewRenderer. - */ - wxDataViewRenderer* GetRenderer(); - /** - Returns @true if the column is reorderable. - */ - bool GetReorderable(); - - /** - 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(); - - /** - Set the alignment of the column header. - */ - void SetAlignment(wxAlignment align); - - /** - Set the bitmap of the column header. - */ - void SetBitmap(const wxBitmap& bitmap); - - /** - Indicate wether the column can be reordered by the - user using the mouse. This is typically implemented - visually by dragging the header button around. - */ - void SetReorderable(bool reorderable); - - /** - Indicate the sort order if the implementation of the - wxDataViewCtrl supports it, most commonly by showing - a little arrow. - */ - void SetSortOrder(bool ascending); - - /** - 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. + @see wxDataViewRenderer. */ - void SetSortable(bool sortable); - - /** - Set the title of the column header to @e title. - */ - void SetTitle(const wxString& title); + wxDataViewRenderer* GetRenderer() const; }; @@ -1675,39 +1592,41 @@ public: /** @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. - @library{wxbase} + The main purpose of this class is to look like a wxTreeCtrl to make a transition + from it to the wxDataViewCtrl class simpler. + + @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(); /** - + @todo docme */ wxDataViewItem AppendContainer(const wxDataViewItem& parent, const wxString& text, @@ -1716,7 +1635,7 @@ public: wxClientData* data = NULL); /** - + @todo docme */ wxDataViewItem AppendItem(const wxDataViewItem& parent, const wxString& text, @@ -1724,8 +1643,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 +1684,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 +1706,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 +1722,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 +1732,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 +1742,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, @@ -1865,11 +1783,12 @@ public: /** @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. + 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. @library{wxadv} @@ -1886,7 +1805,7 @@ public: /** Destructor. */ - ~wxDataViewTreeStore(); + virtual ~wxDataViewTreeStore(); /** Append a container. @@ -1933,12 +1852,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 +1871,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 +1881,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 +1890,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 +1899,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,