X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..c86b476dd540ac302ad023dc864c7c7d4f9ed823:/interface/wx/dataview.h

diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h
index bf3eac6dec..53a0c72ac5 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,7 +63,7 @@ class wxDataViewEvent : public wxNotifyEvent
 public:
     //@{
     /**
-
+        Constructor. Typically used by wxWidgets internals only.
     */
     wxDataViewEvent(wxEventType commandType = wxEVT_NULL,
                     int winid = 0);
@@ -87,7 +85,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 +100,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 +113,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 +128,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 +204,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 +218,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 +228,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 +280,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 +292,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 +315,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 +340,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 +378,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 +402,7 @@ public:
     /**
         Destructor.
     */
-    ~wxDataViewIndexListModel();
+    virtual ~wxDataViewIndexListModel();
 
     /**
         Compare method that sorts the items by their index.
@@ -431,12 +413,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 +433,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 +474,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 +492,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 +519,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 +542,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 +557,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 +578,7 @@ class wxDataViewItem
 public:
     //@{
     /**
-
+        Constructor.
     */
     wxDataViewItem(void* id = NULL);
     wxDataViewItem(const wxDataViewItem& item);
@@ -616,7 +590,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 +600,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,12 +634,44 @@ 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}
+    @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
+           Process a wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
+    @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
+           Process a wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
+    @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
+           Process a wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
+    @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
+           Process a wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
+    @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
+           Process a wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
+    @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
+           Process a wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
+    @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
+           Process a wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
+    @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
+           Process a wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
+    @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
+           Process a wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
+    @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
+           Process a wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
+    @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
+           Process a 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.
+    @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
+           Process a wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
+    @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
+           Process a wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
+    @endEventTable
+
     @library{wxadv}
     @category{ctrl,dvc}
-    <!-- @appearance{dataviewctrl.png} -->
+    @appearance{dataviewctrl.png}
 */
 class wxDataViewCtrl : public wxControl
 {
@@ -683,7 +680,7 @@ public:
         Default Constructor.
     */
     wxDataViewCtrl();
-    
+
     /**
         Constructor. Calls Create().
     */
@@ -696,10 +693,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).
     */
@@ -707,6 +705,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.
     */
@@ -716,7 +715,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
@@ -740,9 +739,9 @@ 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,
@@ -761,11 +760,11 @@ public:
     //@{
     /**
         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,
@@ -785,9 +784,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,
@@ -807,9 +806,9 @@ 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,
@@ -829,9 +828,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,
@@ -848,8 +847,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);
 
@@ -858,15 +857,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.
@@ -880,23 +874,22 @@ 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);
 
     /**
-        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;
 
@@ -923,25 +916,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
@@ -952,23 +943,23 @@ 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 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.
@@ -983,18 +974,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();
 };
 
 
@@ -1002,13 +993,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
@@ -1022,12 +1011,12 @@ public:
     /**
         Destructor.
     */
-    ~wxDataViewModelNotifier();
+    virtual ~wxDataViewModelNotifier();
 
     /**
         Called by owning model.
     */
-    bool Cleared();
+    virtual bool Cleared() = 0;
 
     /**
         Get owning wxDataViewModel.
@@ -1037,41 +1026,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.
@@ -1081,62 +1070,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}
@@ -1145,7 +1136,7 @@ class wxDataViewRenderer : public wxObject
 {
 public:
     /**
-        Constructor. 
+        Constructor.
     */
     wxDataViewRenderer(const wxString& varianttype,
                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
@@ -1159,54 +1150,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.
@@ -1219,8 +1211,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}
@@ -1229,7 +1221,7 @@ class wxDataViewTextRenderer : public wxDataViewRenderer
 {
 public:
     /**
-
+        The ctor.
     */
     wxDataViewTextRenderer(const wxString& varianttype = "string",
                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
@@ -1243,9 +1235,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}
@@ -1255,7 +1247,7 @@ class wxDataViewIconTextRenderer : public wxDataViewRenderer
 {
 public:
     /**
-
+        The ctor.
     */
     wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText",
                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
@@ -1267,7 +1259,7 @@ public:
 /**
     @class wxDataViewProgressRenderer
 
-    wxDataViewProgressRenderer
+    This class is used by wxDataViewCtrl to render progress bars.
 
     @library{wxadv}
     @category{dvc}
@@ -1276,7 +1268,7 @@ class wxDataViewProgressRenderer : public wxDataViewRenderer
 {
 public:
     /**
-
+        The ctor.
     */
     wxDataViewProgressRenderer(const wxString& label = wxEmptyString,
                                const wxString& varianttype = "long",
@@ -1289,19 +1281,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,
@@ -1313,7 +1305,7 @@ public:
 /**
     @class wxDataViewToggleRenderer
 
-    wxDataViewToggleRenderer
+    This class is used by wxDataViewCtrl to render toggle controls.
 
     @library{wxadv}
     @category{dvc}
@@ -1322,10 +1314,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);
 };
 
 
@@ -1333,7 +1326,7 @@ public:
 /**
     @class wxDataViewDateRenderer
 
-    wxDataViewDateRenderer
+    This class is used by wxDataViewCtrl to render calendar controls.
 
     @library{wxadv}
     @category{dvc}
@@ -1342,10 +1335,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);
 };
 
 
@@ -1353,12 +1347,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}
@@ -1367,7 +1359,7 @@ class wxDataViewTextRendererAttr : public wxDataViewTextRenderer
 {
 public:
     /**
-
+        The ctor.
     */
     wxDataViewTextRendererAttr(const wxString& varianttype = "string",
                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
@@ -1380,20 +1372,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 \<ENTER\> and focus out events in order to end the editing.
 
     @library{wxadv}
     @category{dvc}
@@ -1406,16 +1395,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,
@@ -1424,9 +1413,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,
@@ -1440,24 +1437,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,
@@ -1466,24 +1471,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,
@@ -1496,7 +1500,7 @@ public:
 /**
     @class wxDataViewBitmapRenderer
 
-    wxDataViewBitmapRenderer
+    This class is used by wxDataViewCtrl to render bitmap controls.
 
     @library{wxadv}
     @category{dvc}
@@ -1505,7 +1509,7 @@ class wxDataViewBitmapRenderer : public wxDataViewRenderer
 {
 public:
     /**
-
+        The ctor.
     */
     wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap",
                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
@@ -1513,16 +1517,25 @@ public:
 };
 
 
+/**
+    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}
@@ -1551,18 +1564,18 @@ public:
     /**
         Destructor.
     */
-    ~wxDataViewColumn();
+    virtual ~wxDataViewColumn();
 
     /**
         Returns the bitmap in the header of the column, if any.
     */
-    const wxBitmap GetBitmap();
+    const wxBitmap& GetBitmap() const;
 
     /**
         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.
@@ -1571,72 +1584,72 @@ public:
 
     /**
         Returns the renderer of this wxDataViewColumn.
-        See also wxDataViewRenderer.
+
+        @see wxDataViewRenderer.
     */
-    wxDataViewRenderer* GetRenderer();
+    wxDataViewRenderer* GetRenderer() const;
 
     /**
         Returns @true if the column is reorderable.
     */
-    bool GetReorderable();
+    virtual bool IsReorderable() const;
 
     /**
         Returns @true if the column is sortable.
-        See SetSortable()
+
+        @see SetSortable()
     */
-    bool GetSortable();
+    virtual bool IsSortable() const;
 
     /**
         Returns the width of the column.
     */
-    int GetWidth();
+    virtual int GetWidth() const;
 
     /**
         Returns @true, if the sort order is ascending.
-        See also SetSortOrder()
+
+        @see SetSortOrder()
     */
-    bool IsSortOrderAscending();
+    virtual bool IsSortOrderAscending() const;
 
     /**
         Set the alignment of the column header.
     */
-    void SetAlignment(wxAlignment align);
+    virtual void SetAlignment(wxAlignment align);
 
     /**
         Set the bitmap of the column header.
     */
-    void SetBitmap(const wxBitmap& bitmap);
+    virtual 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.
+        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);
+    virtual void SetReorderable(bool reorderable);
 
     /**
-        Indicate the sort order if the implementation of the
-        wxDataViewCtrl supports it, most commonly by showing
-        a little arrow.
+        Indicate the sort order if the implementation of the wxDataViewCtrl supports
+        it, most commonly by showing a little arrow.
     */
-    void SetSortOrder(bool ascending);
+    virtual 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.
+        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.
     */
-    void SetSortable(bool sortable);
+    virtual void SetSortable(bool sortable);
 
     /**
-        Set the title of the column header to @e title.
+        Set the title of the column header to @a title.
     */
-    void SetTitle(const wxString& title);
+    virtual void SetTitle(const wxString& title);
 };
 
 
@@ -1644,39 +1657,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.
+
+    The main purpose of this class is to look like a wxTreeCtrl to make a transition
+    from it to the wxDataViewCtrl class simpler.
 
-    @library{wxbase}
+    @library{wxadv}
     @category{ctrl,dvc}
-    <!-- @appearance{dataviewtreectrl.png} -->
+    @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,
@@ -1685,7 +1700,7 @@ public:
                                    wxClientData* data = NULL);
 
     /**
-
+        @todo docme
     */
     wxDataViewItem AppendItem(const wxDataViewItem& parent,
                               const wxString& text,
@@ -1693,8 +1708,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,
@@ -1735,12 +1749,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.
@@ -1762,8 +1776,8 @@ public:
     //@}
 
     /**
-        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,
@@ -1773,8 +1787,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,
@@ -1783,8 +1797,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,
@@ -1793,8 +1807,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,
@@ -1834,11 +1848,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}
@@ -1855,7 +1870,7 @@ public:
     /**
         Destructor.
     */
-    ~wxDataViewTreeStore();
+    virtual ~wxDataViewTreeStore();
 
     /**
         Append a container.
@@ -1902,12 +1917,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.
@@ -1921,7 +1936,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,
@@ -1931,7 +1946,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,
@@ -1940,7 +1955,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,
@@ -1949,7 +1964,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,