Document that message box with wxYES_NO but without wxCANCEL can't be closed.

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

diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h
index 21f04a8472b9ed3248fb8dfa706d2ef57fd06ea1..f02803df969ce8bdeaa70003a60cc24ec0582428 100644 (file)
--- a/interface/wx/dataview.h
+++ b/interface/wx/dataview.h
@@ -71,7 +71,7 @@
         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
 
         // add columns now
     @endcode
 


@@ -135,10 +135,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.


@@ -339,10 +350,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.


@@ -436,6 +463,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;

 };
 
 
 };
 
 


@@ -482,7 +514,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


@@ -564,6 +596,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}


@@ -1234,8 +1268,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}


@@ -1403,9 +1437,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.


@@ -1413,7 +1458,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
         {


@@ -1434,7 +1479,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,


@@ -1460,7 +1505,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,


@@ -1611,11 +1656,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


@@ -1664,7 +1709,7 @@ public:
         @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.


@@ -1679,24 +1724,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 );
 
     /**


@@ -1707,7 +1752,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 );
 
     /**


@@ -1718,7 +1763,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 );
 
     /**


@@ -1731,7 +1776,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 );
 
     /**


@@ -1747,13 +1792,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.
     */


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

-    
+

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


@@ -1832,13 +1877,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


@@ -1856,12 +1901,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);
 
     /**


@@ -1888,11 +1935,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);
 
     /**


@@ -1975,6 +2025,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.


@@ -2375,7 +2430,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}
 */