]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/dataview.h
Fixed typo in wxFileName::GetHumanReadableSize docs.
[wxWidgets.git] / interface / wx / dataview.h
index 4e6639b172d2da578119952fa39b541190475f77..f8961f82745e04b5c829bcfaed81a6ae2c7640f2 100644 (file)
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxDataView* classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
     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.
+    Note that wxDataViewModel does not define the position or index of any item
+    in the control because different controls might display the same data differently.
+    wxDataViewModel does provide a wxDataViewModel::Compare method which the
+    wxDataViewCtrl may use to sort the data either in conjunction with a column
+    header or without (see wxDataViewModel::HasDefaultCompare).
 
     wxDataViewModel (as indeed the entire wxDataViewCtrl code) is using wxVariant
     to store data and its type in a generic way. wxVariant can be extended to contain
-    almost any data without changes to the original class.
+    almost any data without changes to the original class. To a certain extent,
+    you can use (the somewhat more elegant) wxAny instead of wxVariant as there
+    is code to convert between the two, but it is unclear what impact this will
+    have on performance.
 
-    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.
+    Since you will usually allow the wxDataViewCtrl to change your data
+    through its graphical interface, you will also have to override
+    wxDataViewModel::SetValue which the wxDataViewCtrl will call when a change
+    to some data has been committed.
+
+    If the data represented by the model is changed by something else than its
+    associated wxDataViewCtrl, the control has to be notified about the change.
     Depending on what happened you need to call one of the following methods:
     - wxDataViewModel::ValueChanged,
     - wxDataViewModel::ItemAdded,
     - wxDataViewModel::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
         wxDataViewModel *musicModel = new MyMusicModel;
         m_musicCtrl->AssociateModel( musicModel );
         musicModel->DecRef();  // avoid memory leak !!
+
+        // add columns now
+    @endcode
+
+    A potentially better way to avoid memory leaks is to use wxObjectDataPtr
+    
+    @code
+        wxObjectDataPtr<MyMusicModel> musicModel;
         
+        wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY );
+        musicModel = new MyMusicModel;
+        m_musicCtrl->AssociateModel( musicModel.get() );
+
         // add columns now
     @endcode
 
+
     @library{wxadv}
     @category{dvc}
 */
@@ -91,6 +107,28 @@ public:
     */
     void AddNotifier(wxDataViewModelNotifier* notifier);
 
+    /**
+        Change the value of the given item and update the control to reflect
+        it.
+
+        This function simply calls SetValue() and, if it succeeded,
+        ValueChanged().
+
+        @since 2.9.1
+
+        @param variant
+            The new value.
+        @param item
+            The item (row) to update.
+        @param col
+            The column to update.
+        @return
+            @true if both SetValue() and ValueChanged() returned @true.
+     */
+    bool ChangeValue(const wxVariant& variant,
+                     const wxDataViewItem& item,
+                     unsigned int col);
+
     /**
         Called to inform the model that all data has been cleared.
         The control will reread the data from the model again.
@@ -113,10 +151,48 @@ public:
         Override this to indicate that the item has special font attributes.
         This only affects the wxDataViewTextRendererText renderer.
 
+        The base class version always simply returns @false.
+
         @see wxDataViewItemAttr.
+
+        @param item
+            The item for which the attribute is requested.
+        @param col
+            The column of the item for which the attribute is requested.
+        @param attr
+            The attribute to be filled in if the function returns @true.
+        @return
+            @true if this item has an attribute or @false otherwise.
     */
     virtual bool GetAttr(const wxDataViewItem& item, unsigned int col,
-                         wxDataViewItemAttr& attr);
+                         wxDataViewItemAttr& attr) const;
+
+    /**
+        Override this to indicate that the item should be disabled.
+
+        Disabled items are displayed differently (e.g. grayed out) and cannot
+        be interacted with.
+
+        The base class version always returns @true, thus making all items
+        enabled by default.
+
+        @param item
+            The item whose enabled status is requested.
+        @param col
+            The column of the item whose enabled status is requested.
+        @return
+            @true if this item should be enabled, @false otherwise.
+
+        @note Currently disabling items is fully implemented only for the
+              native control implementation in wxOSX/Cocoa and wxGTK. 
+              This feature is only partially supported in the generic
+              version (used by wxMSW) and not supported by the wxOSX/Carbon
+              implementation.
+
+        @since 2.9.2
+    */
+    virtual bool IsEnabled(const wxDataViewItem &item,
+                           unsigned int col) const;
 
     /**
         Override this so the control can query the child items of an item.
@@ -171,6 +247,20 @@ public:
     */
     virtual bool HasDefaultCompare() const;
 
+    /**
+        Return true if there is a value in the given column of this item.
+
+        All normal items have values in all columns but the container items
+        only show their label in the first column (@a col == 0) by default (but
+        see HasContainerColumns()). So this function always returns true for
+        the first column while for the other ones it returns true only if the
+        item is not a container or HasContainerColumns() was overridden to
+        return true for it.
+
+        @since 2.9.1
+     */
+    bool HasValue(const wxDataViewItem& item, unsigned col) const;
+
     /**
         Override this to indicate of @a item is a container, i.e. if
         it can have child items.
@@ -180,41 +270,41 @@ public:
     /**
         Call this to inform the model that an item has been added to the data.
     */
-    virtual bool ItemAdded(const wxDataViewItem& parent,
+    bool ItemAdded(const wxDataViewItem& parent,
                            const wxDataViewItem& item);
 
     /**
         Call this to inform the model that an item has changed.
 
-        This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
+        This will eventually emit a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
         event (in which the column fields will not be set) to the user.
     */
-    virtual bool ItemChanged(const wxDataViewItem& item);
+    bool ItemChanged(const wxDataViewItem& item);
 
     /**
         Call this to inform the model that an item has been deleted from the data.
     */
-    virtual bool ItemDeleted(const wxDataViewItem& parent,
+    bool ItemDeleted(const wxDataViewItem& parent,
                              const wxDataViewItem& item);
 
     /**
         Call this to inform the model that several items have been added to the data.
     */
-    virtual bool ItemsAdded(const wxDataViewItem& parent,
+    bool ItemsAdded(const wxDataViewItem& parent,
                             const wxDataViewItemArray& items);
 
     /**
         Call this to inform the model that several items have changed.
 
-        This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
+        This will eventually emit @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
         events (in which the column fields will not be set) to the user.
     */
-    virtual bool ItemsChanged(const wxDataViewItemArray& items);
+    bool ItemsChanged(const wxDataViewItemArray& items);
 
     /**
         Call this to inform the model that several items have been deleted.
     */
-    virtual bool ItemsDeleted(const wxDataViewItem& parent,
+    bool ItemsDeleted(const wxDataViewItem& parent,
                               const wxDataViewItemArray& items);
 
     /**
@@ -229,12 +319,17 @@ public:
 
     /**
         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!
+        This is the function you need to override in your derived class but if
+        you want to call it, ChangeValue() is usually more convenient as
+        otherwise you need to manually call ValueChanged() to update the
+        control itself.
     */
-    virtual bool SetValue(const wxVariant& variant, const wxDataViewItem& item,
+    virtual bool SetValue(const wxVariant& variant,
+                          const wxDataViewItem& item,
                           unsigned int col) = 0;
 
     /**
@@ -242,7 +337,7 @@ public:
         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
+        This will eventually emit a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
         event to the user.
     */
     virtual bool ValueChanged(const wxDataViewItem& item,
@@ -259,28 +354,17 @@ protected:
 
 
 /**
-    @class wxDataViewIndexListModel
+    @class wxDataViewListModel
 
-    wxDataViewIndexListModel is a specialized data model which lets you address
-    an item by its position (row) rather than its wxDataViewItem (which you can
-    obtain from this class).
-    This model also provides its own wxDataViewIndexListModel::Compare
-    method which sorts the model's data by the index.
-
-    This model is not a virtual model since the control stores each wxDataViewItem.
-    Use wxDataViewVirtualListModel if you need to display millions of items or
-    have other reason to use a virtual control.
+    Base class with abstract API for wxDataViewIndexListModel and
+    wxDataViewVirtualListModel.
 
     @library{wxadv}
     @category{dvc}
 */
-class wxDataViewIndexListModel : public wxDataViewModel
+class wxDataViewListModel : public wxDataViewModel
 {
 public:
-    /**
-        Constructor.
-    */
-    wxDataViewIndexListModel(unsigned int initial_size = 0);
 
     /**
         Destructor.
@@ -298,10 +382,48 @@ public:
         Override this to indicate that the row has special font attributes.
         This only affects the wxDataViewTextRendererText() renderer.
 
+        The base class version always simply returns @false.
+
         @see wxDataViewItemAttr.
+
+        @param row
+            The row for which the attribute is requested.
+        @param col
+            The column for which the attribute is requested.
+        @param attr
+            The attribute to be filled in if the function returns @true.
+        @return
+            @true if this item has an attribute or @false otherwise.
     */
     virtual bool GetAttrByRow(unsigned int row, unsigned int col,
-                         wxDataViewItemAttr& attr);
+                         wxDataViewItemAttr& attr) const;
+
+    /**
+        Override this if you want to disable specific items.
+
+        The base class version always returns @true, thus making all items
+        enabled by default.
+
+        @param row
+            The row of the item whose enabled status is requested.
+        @param col
+            The column of the item whose enabled status is requested.
+        @return
+            @true if the item at this row and column should be enabled,
+            @false otherwise.
+
+        @note See wxDataViewModel::IsEnabled() for the current status of
+              support for disabling the items under different platforms.
+
+        @since 2.9.2
+    */
+    virtual bool IsEnabledByRow(unsigned int row,
+                                unsigned int col) const;
+
+    /**
+        Returns the number of items (i.e. rows) in the list.
+    */
+    unsigned int GetCount() const;
 
     /**
         Returns the wxDataViewItem at the given @e row.
@@ -371,6 +493,34 @@ 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).
+    This model also provides its own wxDataViewIndexListModel::Compare
+    method which sorts the model's data by the index.
+
+    This model is not a virtual model since the control stores each wxDataViewItem.
+    Use wxDataViewVirtualListModel if you need to display millions of items or
+    have other reason to use a virtual control.
+
+    @see wxDataViewListModel for the API.
+    
+    @library{wxadv}
+    @category{dvc}
+*/
+
+class wxDataViewIndexListModel : public wxDataViewListModel
+{
+public:
+    /**
+        Constructor.
+    */
+    wxDataViewIndexListModel(unsigned int initial_size = 0);
+
+};
 
 /**
     @class wxDataViewVirtualListModel
@@ -380,21 +530,22 @@ public:
     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).
+    as the control doesn't store any item (a feature not supported by OS X).
 
-    @see wxDataViewIndexListModel for the API.
+    @see wxDataViewListModel for the API.
 
     @library{wxadv}
     @category{dvc}
 */
-class wxDataViewVirtualListModel : public wxDataViewModel
+
+class wxDataViewVirtualListModel : public wxDataViewListModel
 {
 public:
     /**
         Constructor.
     */
     wxDataViewVirtualListModel(unsigned int initial_size = 0);
+
 };
 
 
@@ -441,7 +592,7 @@ 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
+    in a persistent way, i.e. independent of the position of the item in the control
     or changes to its contents.
 
     It must hold a unique ID of type @e void* in its only field and can be converted
@@ -516,6 +667,8 @@ public:
            Multiple selection mode.
     @style{wxDV_ROW_LINES}
            Use alternating colours for rows if supported by platform and theme.
+           Currently only supported by the native GTK and OS X implementations
+           but not by the generic one.
     @style{wxDV_HORIZ_RULES}
            Display fine rules between row if supported.
     @style{wxDV_VERT_RULES}
@@ -523,6 +676,8 @@ public:
     @style{wxDV_VARIABLE_LINE_HEIGHT}
            Allow variable line heights.
            This can be inefficient when displaying large number of items.
+    @style{wxDV_NO_HEADER}
+           Do not show column headers (which are shown by default).
     @endStyleTable
 
     @beginEventEmissionTable{wxDataViewEvent}
@@ -585,7 +740,8 @@ public:
                    const wxPoint& pos = wxDefaultPosition,
                    const wxSize& size = wxDefaultSize,
                    long style = 0,
-                   const wxValidator& validator = wxDefaultValidator);
+                   const wxValidator& validator = wxDefaultValidator,
+                   const wxString& name = wxDataViewCtrlNameStr);
 
     /**
         Destructor.
@@ -766,7 +922,8 @@ public:
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = 0,
-                const wxValidator& validator = wxDefaultValidator);
+                const wxValidator& validator = wxDefaultValidator,
+                const wxString& name = wxDataViewCtrlNameStr);
 
     /**
         Deletes given column.
@@ -822,6 +979,26 @@ public:
     */
     wxDataViewColumn* GetExpanderColumn() const;
 
+    /**
+        Returns the currently focused item.
+
+        This is the item that the keyboard commands apply to. It may be invalid
+        if there is no focus currently.
+
+        This method is mostly useful for the controls with @c wxDV_MULTIPLE
+        style as in the case of single selection it returns the same thing as
+        GetSelection().
+
+        Notice that under all platforms except Mac OS X the currently focused
+        item may be selected or not but under OS X the current item is always
+        selected.
+
+        @see SetCurrentItem()
+
+        @since 2.9.2
+     */
+    wxDataViewItem GetCurrentItem() const;
+
     /**
         Returns indentation.
     */
@@ -872,6 +1049,10 @@ public:
 
     /**
         Select the given item.
+
+        In single selection mode this changes the (unique) currently selected
+        item. In multi selection mode, the @a item is selected and the
+        previously selected items remain selected.
     */
     virtual void Select(const wxDataViewItem& item);
 
@@ -885,6 +1066,25 @@ public:
     */
     void SetExpanderColumn(wxDataViewColumn* col);
 
+    /**
+        Changes the currently focused item.
+
+        The @a item parameter must be valid, there is no way to remove the
+        current item from the control.
+
+        In single selection mode, calling this method is the same as calling
+        Select() and is thus not very useful. In multiple selection mode this
+        method only moves the current item however without changing the
+        selection except under OS X where the current item is always selected,
+        so calling SetCurrentItem() selects @a item if it hadn't been selected
+        before.
+
+        @see GetCurrentItem()
+
+        @since 2.9.2
+     */
+    void SetCurrentItem(const wxDataViewItem& item);
+
     /**
         Sets the indendation.
     */
@@ -1039,6 +1239,7 @@ enum wxDataViewCellRenderState
     - wxDataViewBitmapRenderer,
     - wxDataViewDateRenderer,
     - wxDataViewSpinRenderer.
+    - wxDataViewChoiceRenderer.
 
     Additionally, the user can write own renderers by deriving from
     wxDataViewCustomRenderer.
@@ -1060,11 +1261,49 @@ public:
                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
                        int align = wxDVR_DEFAULT_ALIGNMENT );
 
+    /**
+        Enable or disable replacing parts of the item text with ellipsis to
+        make it fit the column width.
+
+        This method only makes sense for the renderers working with text, such
+        as wxDataViewTextRenderer or wxDataViewIconTextRenderer.
+
+        By default wxELLIPSIZE_MIDDLE is used.
+
+        @param mode
+            Ellipsization mode, use wxELLIPSIZE_NONE to disable.
+
+        @since 2.9.1
+     */
+    void EnableEllipsize(wxEllipsizeMode mode = wxELLIPSIZE_MIDDLE);
+
+    /**
+        Disable replacing parts of the item text with ellipsis.
+
+        If ellipsizing is disabled, the string will be truncated if it doesn't
+        fit.
+
+        This is the same as @code EnableEllipsize(wxELLIPSIZE_NONE) @endcode.
+
+        @since 2.9.1
+     */
+    void DisableEllipsize();
+
     /**
         Returns the alignment. See SetAlignment()
     */
     virtual int GetAlignment() const;
 
+    /**
+        Returns the ellipsize mode used by the renderer.
+
+        If the return value is wxELLIPSIZE_NONE, the text is simply truncated
+        if it doesn't fit.
+
+        @see EnableEllipsize()
+     */
+    wxEllipsizeMode GetEllipsizeMode() const;
+
     /**
         Returns the cell mode.
     */
@@ -1155,8 +1394,8 @@ public:
     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 and from a wxVariant using the left shift
-    operator.
+    wxDataViewIconText can be converted to and from a wxVariant using the left
+    shift operator.
 
     @library{wxadv}
     @category{dvc}
@@ -1240,6 +1479,38 @@ public:
 };
 
 
+/**
+    @class wxDataViewChoiceRenderer
+
+    This class is used by wxDataViewCtrl to render choice controls.
+    It stores a string so that SetValue() and GetValue() operate
+    on a variant holding a string.
+
+    @library{wxadv}
+    @category{dvc}
+*/
+
+class wxDataViewChoiceRenderer: public wxDataViewRenderer
+{
+public:
+    /**
+        The ctor.
+    */
+    wxDataViewChoiceRenderer( const wxArrayString &choices,
+                              wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
+                              int alignment = wxDVR_DEFAULT_ALIGNMENT );
+
+    /**
+        Returns the choice referred to by index.
+    */
+    wxString GetChoice(size_t index) const;
+    
+    /**
+        Returns all choices.
+    */
+    const wxArrayString& GetChoices() const;
+};
+
 
 /**
     @class wxDataViewDateRenderer
@@ -1324,9 +1595,20 @@ public:
                                         const wxVariant& value);
 
     /**
-        Create DC on request. Internal.
-    */
-    virtual wxDC* GetDC();
+        Return the attribute to be used for rendering.
+
+        This function may be called from Render() implementation to use the
+        attributes defined for the item if the renderer supports them.
+
+        Notice that when Render() is called, the wxDC object passed to it is
+        already set up to use the correct attributes (e.g. its font is set to
+        bold or italic version if wxDataViewItemAttr::GetBold() or GetItalic()
+        returns true) so it may not be necessary to call it explicitly if you
+        only want to render text using the items attributes.
+
+        @since 2.9.1
+     */
+    const wxDataViewItemAttr& GetAttr() const;
 
     /**
         Return size required to show content.
@@ -1334,7 +1616,7 @@ public:
     virtual wxSize GetSize() const = 0;
 
     /**
-        Overrride this so that the renderer can get the value from the editor
+        Override this so that the renderer can get the value from the editor
         control (pointed to by @a editor):
         @code
         {
@@ -1355,7 +1637,7 @@ public:
     virtual bool HasEditorCtrl() const;
 
     /**
-        Overrride this to react to a left click.
+        Override this to react to a left click.
         This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
     */
     virtual bool LeftClick( wxPoint cursor,
@@ -1381,7 +1663,7 @@ public:
                     wxDC* dc, int state);
 
     /**
-        Overrride this to start a drag operation. Not yet supported.
+        Override this to start a drag operation. Not yet supported.
     */
     virtual bool StartDrag(wxPoint cursor, wxRect cell,
                            wxDataViewModel* model,
@@ -1532,11 +1814,11 @@ public:
        data.push_back( wxVariant("row 3") );
        listctrl->AppendItem( data );
     @endcode
-    
+
     @beginStyleTable
     See wxDataViewCtrl for the list of supported styles.
     @endStyleTable
-    
+
     @beginEventEmissionTable
     See wxDataViewCtrl for the list of events emitted by this class.
     @endEventTable
@@ -1581,11 +1863,69 @@ public:
     const wxDataViewListStore *GetStore() const;
     //@}
 
+    /**
+        Returns the position of given @e item or wxNOT_FOUND if it's
+        not a valid item.
+
+        @since 2.9.2
+     */
+    int ItemToRow(const wxDataViewItem &item) const;
+
+    /**
+        Returns the wxDataViewItem at the given @e row.
+
+        @since 2.9.2
+     */
+    wxDataViewItem RowToItem(int row) const;
+
+    //@{
+    /**
+        @name Selection handling functions
+     */
+
+    /**
+        Returns index of the selected row or wxNOT_FOUND.
+
+        @see wxDataViewCtrl::GetSelection()
+
+        @since 2.9.2
+     */
+    int GetSelectedRow() const;
+
+    /**
+        Selects given row.
+
+        @see wxDataViewCtrl::Select()
+
+        @since 2.9.2
+     */
+    void SelectRow(unsigned row);
+
+    /**
+        Unselects given row.
+
+        @see wxDataViewCtrl::Unselect()
+
+        @since 2.9.2
+     */
+    void UnselectRow(unsigned row);
+
+    /**
+        Returns true if @a row is selected.
+
+        @see wxDataViewCtrl::IsSelected()
+
+        @since 2.9.2
+     */
+    bool IsRowSelected(unsigned row) const;
+
+    //@}
+
     /**
         @name Column management functions
     */
     //@{
-   
+
     /**
         Appends a column to the control and additionally appends a
         column to the store with the type string.
@@ -1600,24 +1940,24 @@ public:
 
     /**
         Appends a text column to the control and the store.
-        
+
         See wxDataViewColumn::wxDataViewColumn for more info about
         the parameters.
     */
     wxDataViewColumn *AppendTextColumn( const wxString &label,
           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
-          int width = -1, wxAlignment align = wxALIGN_LEFT, 
+          int width = -1, wxAlignment align = wxALIGN_LEFT,
           int flags = wxDATAVIEW_COL_RESIZABLE );
 
     /**
         Appends a toggle column to the control and the store.
-        
+
         See wxDataViewColumn::wxDataViewColumn for more info about
         the parameters.
     */
     wxDataViewColumn *AppendToggleColumn( const wxString &label,
           wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
-          int width = -1, wxAlignment align = wxALIGN_LEFT, 
+          int width = -1, wxAlignment align = wxALIGN_LEFT,
           int flags = wxDATAVIEW_COL_RESIZABLE );
 
     /**
@@ -1628,7 +1968,7 @@ public:
     */
     wxDataViewColumn *AppendProgressColumn( const wxString &label,
           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
-          int width = -1, wxAlignment align = wxALIGN_LEFT, 
+          int width = -1, wxAlignment align = wxALIGN_LEFT,
           int flags = wxDATAVIEW_COL_RESIZABLE );
 
     /**
@@ -1639,7 +1979,7 @@ public:
     */
     wxDataViewColumn *AppendIconTextColumn( const wxString &label,
           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
-          int width = -1, wxAlignment align = wxALIGN_LEFT, 
+          int width = -1, wxAlignment align = wxALIGN_LEFT,
           int flags = wxDATAVIEW_COL_RESIZABLE );
 
     /**
@@ -1652,7 +1992,7 @@ public:
         Inserts a column to the control and additionally inserts a
         column to the list store with the type @a varianttype.
     */
-    void InsertColumn( unsigned int pos, wxDataViewColumn *column, 
+    void InsertColumn( unsigned int pos, wxDataViewColumn *column,
                        const wxString &varianttype );
 
     /**
@@ -1668,13 +2008,13 @@ public:
     void PrependColumn( wxDataViewColumn *column, const wxString &varianttype );
 
     //@}
-    
-    
+
+
     /**
         @name Item management functions
     */
     //@{
-    
+
     /**
         Appends an item (=row) to the control and store.
     */
@@ -1741,7 +2081,7 @@ public:
          respective column.
     */
     bool GetToggleValue( unsigned int row, unsigned int col ) const;
-    
+
     //@}
 };
 
@@ -1753,13 +2093,13 @@ public:
     and forwards most of its API to that class.
     Additionally, it uses a wxImageList to store a list of icons.
 
-    The main purpose of this class is to represent a possible replacement for
-    wxTreeCtrl.
+    The main purpose of this class is to provide a simple upgrade path for code
+    using wxTreeCtrl.
 
     @beginStyleTable
     See wxDataViewCtrl for the list of supported styles.
     @endStyleTable
-    
+
     @beginEventEmissionTable
     See wxDataViewCtrl for the list of events emitted by this class.
     @endEventTable
@@ -1777,12 +2117,14 @@ public:
     wxDataViewTreeCtrl();
 
     /**
-        Constructor. Calls Create().
+        Constructor.
+
+        Calls Create().
     */
     wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
                        const wxPoint& pos = wxDefaultPosition,
                        const wxSize& size = wxDefaultSize,
-                       long style = wxDV_NO_HEADER,
+                       long style = wxDV_NO_HEADER | wxDV_ROW_LINES,
                        const wxValidator& validator = wxDefaultValidator);
 
     /**
@@ -1809,11 +2151,14 @@ public:
 
     /**
         Creates the control and a wxDataViewTreeStore as its internal model.
+
+        The default tree column created by this method is an editable column
+        using wxDataViewIconTextRenderer as its renderer.
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
-                long style = wxDV_NO_HEADER,
+                long style = wxDV_NO_HEADER | wxDV_ROW_LINES,
                 const wxValidator& validator = wxDefaultValidator);
 
     /**
@@ -1896,6 +2241,11 @@ public:
                               int icon = -1,
                               wxClientData* data = NULL);
 
+    /**
+        Returns true if item is a container.
+    */
+    bool IsContainer( const wxDataViewItem& item );
+    
     /**
         Calls the same method from wxDataViewTreeStore but uses
         an index position in the image list instead of a wxIcon.
@@ -2296,7 +2646,7 @@ public:
     @event{EVT_DATAVIEW_CACHE_HINT(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
     @endEventTable
-    
+
     @library{wxadv}
     @category{events,dvc}
 */
@@ -2342,7 +2692,7 @@ public:
     void SetColumn(int col);
 
     /**
-        For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
+        For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
     */
     void SetDataViewColumn(wxDataViewColumn* col);