Add a link to Microsoft guidelines from wxICON_QUESTION documentation.

[wxWidgets.git] / interface / wx / dataview.h

diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h
index 4e6639b172d2da578119952fa39b541190475f77..4947ed44ede781bb71ba7add6a72f31b057def62 100644 (file)
--- a/interface/wx/dataview.h
+++ b/interface/wx/dataview.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxDataView* classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxDataView* classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -20,17 +20,26 @@
     wxDataViewModel::GetValue in order to define the data model which acts as an
     interface between your actual data and the wxDataViewCtrl.
 
     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
 
     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.
+
+    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.

 
 

-    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.
+    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,
     Depending on what happened you need to call one of the following methods:
     - wxDataViewModel::ValueChanged,
     - wxDataViewModel::ItemAdded,


@@ -44,12 +53,6 @@
     - wxDataViewModel::ItemsDeleted,
     - wxDataViewModel::ItemsChanged.
 
     - 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
     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


@@ -71,10 +74,23 @@
         wxDataViewModel *musicModel = new MyMusicModel;
         m_musicCtrl->AssociateModel( musicModel );
         musicModel->DecRef();  // avoid memory leak !!
         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
 
         // add columns now
     @endcode
 

+

     @library{wxadv}
     @category{dvc}
 */
     @library{wxadv}
     @category{dvc}
 */


@@ -91,6 +107,28 @@ public:
     */
     void AddNotifier(wxDataViewModelNotifier* notifier);
 
     */
     void AddNotifier(wxDataViewModelNotifier* notifier);
 

+    /**
+        Change the value of the given item and update the control to reflect
+        it.
+
+        This function simply calls SetValue() and, if it succeeded,
+        ValueChanged().
+
+        @since 2.9.1
+
+        @param variant
+            The new value.
+        @param item
+            The item (row) to update.
+        @param col
+            The column to update.
+        @return
+            @true if both SetValue() and ValueChanged() returned @true.
+     */
+    bool ChangeValue(const wxVariant& variant,
+                     const wxDataViewItem& item,
+                     unsigned int col);
+

     /**
         Called to inform the model that all data has been cleared.
         The control will reread the data from the model again.
     /**
         Called to inform the model that all data has been cleared.
         The control will reread the data from the model again.


@@ -113,10 +151,21 @@ public:
         Override this to indicate that the item has special font attributes.
         This only affects the wxDataViewTextRendererText renderer.
 
         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.
         @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,
     */
     virtual bool GetAttr(const wxDataViewItem& item, unsigned int col,

-                         wxDataViewItemAttr& attr);
+                         wxDataViewItemAttr& attr) const;

 
     /**
         Override this so the control can query the child items of an item.
 
     /**
         Override this so the control can query the child items of an item.


@@ -171,6 +220,20 @@ public:
     */
     virtual bool HasDefaultCompare() const;
 
     */
     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.
     /**
         Override this to indicate of @a item is a container, i.e. if
         it can have child items.


@@ -180,7 +243,7 @@ public:
     /**
         Call this to inform the model that an item has been added to the data.
     */
     /**
         Call this to inform the model that an item has been added to the data.
     */

-    virtual bool ItemAdded(const wxDataViewItem& parent,
+    bool ItemAdded(const wxDataViewItem& parent,

                            const wxDataViewItem& item);
 
     /**
                            const wxDataViewItem& item);
 
     /**


@@ -189,18 +252,18 @@ public:
         This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
         event (in which the column fields will not be set) to the user.
     */
         This will eventually emit a 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.
     */
 
     /**
         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.
     */
                              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);
 
     /**
                             const wxDataViewItemArray& items);
 
     /**


@@ -209,12 +272,12 @@ public:
         This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
         events (in which the column fields will not be set) to the user.
     */
         This will eventually emit 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.
     */
 
     /**
         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);
 
     /**
                               const wxDataViewItemArray& items);
 
     /**


@@ -229,12 +292,17 @@ public:
 
     /**
         This gets called in order to set a value in the data model.
 
     /**
         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.
 
         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;
 
     /**
                           unsigned int col) = 0;
 
     /**


@@ -298,10 +366,26 @@ public:
         Override this to indicate that the row has special font attributes.
         This only affects the wxDataViewTextRendererText() renderer.
 
         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.
         @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,
     */
     virtual bool GetAttrByRow(unsigned int row, unsigned int col,

-                         wxDataViewItemAttr& attr);
+                         wxDataViewItemAttr& attr) const;
+
+    /**
+        Returns the number of items (i.e. rows) in the list.
+    */
+    unsigned int GetCount() const;

 
     /**
         Returns the wxDataViewItem at the given @e row.
 
     /**
         Returns the wxDataViewItem at the given @e row.


@@ -395,6 +479,11 @@ public:
         Constructor.
     */
     wxDataViewVirtualListModel(unsigned int initial_size = 0);
         Constructor.
     */
     wxDataViewVirtualListModel(unsigned int initial_size = 0);

+
+    /**
+        Returns the number of virtual items (i.e. rows) in the list.
+    */
+    unsigned int GetCount() const;

 };
 
 
 };
 
 


@@ -441,7 +530,7 @@ public:
     @class wxDataViewItem
 
     wxDataViewItem is a small opaque class that represents an item in a wxDataViewCtrl
     @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
     or changes to its contents.
 
     It must hold a unique ID of type @e void* in its only field and can be converted


@@ -523,6 +612,8 @@ public:
     @style{wxDV_VARIABLE_LINE_HEIGHT}
            Allow variable line heights.
            This can be inefficient when displaying large number of items.
     @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}
     @endStyleTable
 
     @beginEventEmissionTable{wxDataViewEvent}


@@ -585,7 +676,8 @@ public:
                    const wxPoint& pos = wxDefaultPosition,
                    const wxSize& size = wxDefaultSize,
                    long style = 0,
                    const wxPoint& pos = wxDefaultPosition,
                    const wxSize& size = wxDefaultSize,
                    long style = 0,

-                   const wxValidator& validator = wxDefaultValidator);
+                   const wxValidator& validator = wxDefaultValidator,
+                   const wxString& name = wxDataViewCtrlNameStr);

 
     /**
         Destructor.
 
     /**
         Destructor.


@@ -766,7 +858,8 @@ public:
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = 0,
                 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.
 
     /**
         Deletes given column.


@@ -822,6 +915,26 @@ public:
     */
     wxDataViewColumn* GetExpanderColumn() const;
 
     */
     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.
     */
     /**
         Returns indentation.
     */


@@ -872,6 +985,10 @@ public:
 
     /**
         Select the given item.
 
     /**
         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);
 
     */
     virtual void Select(const wxDataViewItem& item);
 


@@ -885,6 +1002,25 @@ public:
     */
     void SetExpanderColumn(wxDataViewColumn* col);
 
     */
     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.
     */
     /**
         Sets the indendation.
     */


@@ -1039,6 +1175,7 @@ enum wxDataViewCellRenderState
     - wxDataViewBitmapRenderer,
     - wxDataViewDateRenderer,
     - wxDataViewSpinRenderer.
     - wxDataViewBitmapRenderer,
     - wxDataViewDateRenderer,
     - wxDataViewSpinRenderer.

+    - wxDataViewChoiceRenderer.

 
     Additionally, the user can write own renderers by deriving from
     wxDataViewCustomRenderer.
 
     Additionally, the user can write own renderers by deriving from
     wxDataViewCustomRenderer.


@@ -1060,11 +1197,49 @@ public:
                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
                        int align = wxDVR_DEFAULT_ALIGNMENT );
 
                        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 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.
     */
     /**
         Returns the cell mode.
     */


@@ -1155,8 +1330,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.
     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}
 
     @library{wxadv}
     @category{dvc}


@@ -1240,6 +1415,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
 
 /**
     @class wxDataViewDateRenderer


@@ -1324,9 +1531,20 @@ public:
                                         const wxVariant& value);
 
     /**
                                         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.
 
     /**
         Return size required to show content.


@@ -1334,7 +1552,7 @@ public:
     virtual wxSize GetSize() const = 0;
 
     /**
     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
         {
         control (pointed to by @a editor):
         @code
         {


@@ -1355,7 +1573,7 @@ public:
     virtual bool HasEditorCtrl() const;
 
     /**
     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,
         This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
     */
     virtual bool LeftClick( wxPoint cursor,


@@ -1381,7 +1599,7 @@ public:
                     wxDC* dc, int state);
 
     /**
                     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,
     */
     virtual bool StartDrag(wxPoint cursor, wxRect cell,
                            wxDataViewModel* model,


@@ -1532,11 +1750,11 @@ public:
        data.push_back( wxVariant("row 3") );
        listctrl->AppendItem( data );
     @endcode
        data.push_back( wxVariant("row 3") );
        listctrl->AppendItem( data );
     @endcode

-    
+

     @beginStyleTable
     See wxDataViewCtrl for the list of supported styles.
     @endStyleTable
     @beginStyleTable
     See wxDataViewCtrl for the list of supported styles.
     @endStyleTable

-    
+

     @beginEventEmissionTable
     See wxDataViewCtrl for the list of events emitted by this class.
     @endEventTable
     @beginEventEmissionTable
     See wxDataViewCtrl for the list of events emitted by this class.
     @endEventTable


@@ -1581,11 +1799,69 @@ public:
     const wxDataViewListStore *GetStore() const;
     //@}
 
     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
     */
     //@{
     /**
         @name Column management functions
     */
     //@{

-   
+

     /**
         Appends a column to the control and additionally appends a
         column to the store with the type string.
     /**
         Appends a column to the control and additionally appends a
         column to the store with the type string.


@@ -1600,24 +1876,24 @@ public:
 
     /**
         Appends a text column to the control and the store.
 
     /**
         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,
         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.
           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,
         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 );
 
     /**
           int flags = wxDATAVIEW_COL_RESIZABLE );
 
     /**


@@ -1628,7 +1904,7 @@ public:
     */
     wxDataViewColumn *AppendProgressColumn( const wxString &label,
           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
     */
     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 );
 
     /**
           int flags = wxDATAVIEW_COL_RESIZABLE );
 
     /**


@@ -1639,7 +1915,7 @@ public:
     */
     wxDataViewColumn *AppendIconTextColumn( const wxString &label,
           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
     */
     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 );
 
     /**
           int flags = wxDATAVIEW_COL_RESIZABLE );
 
     /**


@@ -1652,7 +1928,7 @@ public:
         Inserts a column to the control and additionally inserts a
         column to the list store with the type @a varianttype.
     */
         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 );
 
     /**
                        const wxString &varianttype );
 
     /**


@@ -1668,13 +1944,13 @@ public:
     void PrependColumn( wxDataViewColumn *column, const wxString &varianttype );
 
     //@}
     void PrependColumn( wxDataViewColumn *column, const wxString &varianttype );
 
     //@}

-    
-    
+
+

     /**
         @name Item management functions
     */
     //@{
     /**
         @name Item management functions
     */
     //@{

-    
+

     /**
         Appends an item (=row) to the control and store.
     */
     /**
         Appends an item (=row) to the control and store.
     */


@@ -1741,7 +2017,7 @@ public:
          respective column.
     */
     bool GetToggleValue( unsigned int row, unsigned int col ) const;
          respective column.
     */
     bool GetToggleValue( unsigned int row, unsigned int col ) const;

-    
+

     //@}
 };
 
     //@}
 };
 


@@ -1753,13 +2029,13 @@ public:
     and forwards most of its API to that class.
     Additionally, it uses a wxImageList to store a list of icons.
 
     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
 
     @beginStyleTable
     See wxDataViewCtrl for the list of supported styles.
     @endStyleTable

-    
+

     @beginEventEmissionTable
     See wxDataViewCtrl for the list of events emitted by this class.
     @endEventTable
     @beginEventEmissionTable
     See wxDataViewCtrl for the list of events emitted by this class.
     @endEventTable


@@ -1777,12 +2053,14 @@ public:
     wxDataViewTreeCtrl();
 
     /**
     wxDataViewTreeCtrl();
 
     /**

-        Constructor. Calls Create().
+        Constructor.
+
+        Calls Create().

     */
     wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
                        const wxPoint& pos = wxDefaultPosition,
                        const wxSize& size = wxDefaultSize,
     */
     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);
 
     /**
                        const wxValidator& validator = wxDefaultValidator);
 
     /**


@@ -1809,11 +2087,14 @@ public:
 
     /**
         Creates the control and a wxDataViewTreeStore as its internal model.
 
     /**
         Creates the control and a wxDataViewTreeStore as its internal model.

+
+        The default tree column created by this method is an editable column
+        using wxDataViewIconTextRenderer as its renderer.

     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
     */
     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);
 
     /**
                 const wxValidator& validator = wxDefaultValidator);
 
     /**


@@ -1896,6 +2177,11 @@ public:
                               int icon = -1,
                               wxClientData* data = NULL);
 
                               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.
     /**
         Calls the same method from wxDataViewTreeStore but uses
         an index position in the image list instead of a wxIcon.


@@ -2296,7 +2582,7 @@ public:
     @event{EVT_DATAVIEW_CACHE_HINT(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
     @endEventTable
     @event{EVT_DATAVIEW_CACHE_HINT(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
     @endEventTable

-    
+

     @library{wxadv}
     @category{events,dvc}
 */
     @library{wxadv}
     @category{events,dvc}
 */