synchronize GTK2 minimum version in docs

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

diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h
index f51a81a6815ad7e6936aba0f8523a01c10105176..e45d0fced14153d526ef07fcee6f27b8feee7a00 100644 (file)
--- a/interface/wx/dataview.h
+++ b/interface/wx/dataview.h
@@ -747,7 +747,9 @@ wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP;
     @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
     @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
-           Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
+           Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. This event
+           is triggered by double clicking an item or pressing some special key
+           (usually "Enter") when it is focused.
     @event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_START_EDITING event. This
            event can be vetoed in order to prevent editing on an item by item
@@ -788,6 +790,11 @@ wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP;
            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
     @endEventTable
 
+    Notice that this control doesn't allow to process generic mouse events such
+    as @c wxEVT_LEFT_DOWN in all ports (notably it doesn't work in wxGTK). If
+    you need to handle any mouse events not covered by the ones above, consider
+    using a custom renderer for the cells that must handle them.
+
     @library{wxadv}
     @category{ctrl,dvc}
     @appearance{dataviewctrl.png}
@@ -1690,12 +1697,15 @@ public:
 
 
 /**
-    @class wxDataViewChoiceRenderer
+    A wxDataViewCtrl renderer using wxChoice control and values of strings in
+    it.
 
     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.
 
+    @see wxDataViewChoiceByIndexRenderer
+
     @library{wxadv}
     @category{dvc}
 */
@@ -1714,7 +1724,7 @@ public:
         Returns the choice referred to by index.
     */
     wxString GetChoice(size_t index) const;
-    
+
     /**
         Returns all choices.
     */
@@ -1722,6 +1732,28 @@ public:
 };
 
 
+/**
+    A wxDataViewCtrl renderer using wxChoice control and indexes into it.
+
+    Unlike its base wxDataViewChoiceRenderer class, this one stores the choice
+    index, i.e. an @c int, in the variant used by its SetValue() and
+    GetValue().
+
+    @library{wxadv}
+    @category{dvc}
+*/
+class wxDataViewChoiceByIndexRenderer : public wxDataViewChoiceRenderer
+{
+public:
+    /**
+        The ctor.
+    */
+    wxDataViewChoiceByIndexRenderer( const wxArrayString &choices,
+                              wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
+                              int alignment = wxDVR_DEFAULT_ALIGNMENT );
+};
+
+
 /**
     @class wxDataViewDateRenderer
 
@@ -2283,17 +2315,17 @@ public:
     /**
         Appends an item (=row) to the control and store.
     */
-    void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
+    void AppendItem( const wxVector<wxVariant> &values, wxUIntPtr data = NULL );
 
     /**
         Prepends an item (=row) to the control and store.
     */
-    void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
+    void PrependItem( const wxVector<wxVariant> &values, wxUIntPtr data = NULL );
 
     /**
         Inserts an item (=row) to the control and store.
     */
-    void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
+    void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxUIntPtr data = NULL );
 
     /**
         Delete the row at position @a row.
@@ -2305,6 +2337,22 @@ public:
     */
     void DeleteAllItems();
 
+    /**
+        Returns the number of items (=rows) in the control
+
+        @since 2.9.4
+    */
+    unsigned int GetItemCount() const;
+
+    /**
+        Returns the client data associated with the item.
+
+        @see SetItemData()
+
+        @since 2.9.4
+    */
+    wxUIntPtr GetItemData(const wxDataViewItem& item) const;
+
     /**
          Sets the value in the store and update the control.
     */
@@ -2347,6 +2395,19 @@ public:
     */
     bool GetToggleValue( unsigned int row, unsigned int col ) const;
 
+    /**
+        Associates a client data pointer with the given item.
+
+        Notice that the control does @e not take ownership of the pointer for
+        compatibility with wxListCtrl. I.e. it will @e not delete the pointer
+        (if it is a pointer and not a number) itself, it is up to you to do it.
+
+        @see GetItemData()
+
+        @since 2.9.4
+    */
+    void SetItemData(const wxDataViewItem& item, wxUIntPtr data);
+
     //@}
 };
 
@@ -2626,7 +2687,7 @@ public:
         in number and type. No (default) values are filled in
         automatically.
     */
-    void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
+    void AppendItem( const wxVector<wxVariant> &values, wxUIntPtr data = NULL );
 
     /**
         Prepends an item (=row) and fills it with @a values.
@@ -2635,7 +2696,7 @@ public:
         in number and type. No (default) values are filled in
         automatically.
     */
-    void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
+    void PrependItem( const wxVector<wxVariant> &values, wxUIntPtr data = NULL );
 
     /**
         Inserts an item (=row) and fills it with @a values.
@@ -2644,7 +2705,7 @@ public:
         in number and type. No (default) values are filled in
         automatically.
     */
-    void InsertItem(  unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
+    void InsertItem(  unsigned int row, const wxVector<wxVariant> &values, wxUIntPtr data = NULL );
 
     /**
         Delete the item (=row) at position @a pos.
@@ -2656,6 +2717,22 @@ public:
     */
     void DeleteAllItems();
 
+    /**
+        Returns the number of items (=rows) in the control
+
+        @since 2.9.4
+    */
+    unsigned int GetItemCount() const;
+
+    /**
+        Returns the client data associated with the item.
+
+        @see SetItemData()
+
+        @since 2.9.4
+    */
+    wxUIntPtr GetItemData(const wxDataViewItem& item) const;
+
     /**
         Overridden from wxDataViewModel
     */
@@ -2666,6 +2743,18 @@ public:
     */
     virtual wxString GetColumnType( unsigned int col ) const;
 
+    /**
+        Sets the client data associated with the item.
+
+        Notice that this class does @e not take ownership of the passed in
+        pointer and will not delete it.
+
+        @see GetItemData()
+
+        @since 2.9.4
+    */
+    void SetItemData(const wxDataViewItem& item, wxUIntPtr data);
+
     /**
         Overridden from wxDataViewIndexListModel
     */
@@ -2902,6 +2991,8 @@ public:
            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
     @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
+           Currently this even is only generated when using the native OSX
+           version.
     @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
     @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}