Correct decoding of 4-byte integers in png2c script.

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

diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h
index f678bb7f23e65e41eb549753aa4eec7a4f93affe..f8961f82745e04b5c829bcfaed81a6ae2c7640f2 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 committed.
+    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.

 
 

-    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,
     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


@@ -75,6 +78,19 @@
         // add columns now
     @endcode
 
         // 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}
 */
     @library{wxadv}
     @category{dvc}
 */


@@ -151,6 +167,33 @@ public:
     virtual bool GetAttr(const wxDataViewItem& item, unsigned int col,
                          wxDataViewItemAttr& attr) const;
 
     virtual bool GetAttr(const wxDataViewItem& item, unsigned int col,
                          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.
         Returns the number of items.
     /**
         Override this so the control can query the child items of an item.
         Returns the number of items.


@@ -227,41 +270,41 @@ 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);
 
     /**
         Call this to inform the model that an item has changed.
 
                            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.
     */
         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);
 
     /**
         Call this to inform the model that several items have changed.
 
                             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.
     */
         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);
 
     /**


@@ -294,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 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,
         event to the user.
     */
     virtual bool ValueChanged(const wxDataViewItem& item,


@@ -311,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}
 */
 
     @library{wxadv}
     @category{dvc}
 */

-class wxDataViewIndexListModel : public wxDataViewModel
+class wxDataViewListModel : public wxDataViewModel

 {
 public:
 {
 public:

-    /**
-        Constructor.
-    */
-    wxDataViewIndexListModel(unsigned int initial_size = 0);

 
     /**
         Destructor.
 
     /**
         Destructor.


@@ -366,6 +398,28 @@ public:
     virtual bool GetAttrByRow(unsigned int row, unsigned int col,
                          wxDataViewItemAttr& attr) const;
 
     virtual bool GetAttrByRow(unsigned int row, unsigned int col,
                          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.
     */
     /**
         Returns the number of items (i.e. rows) in the list.
     */


@@ -439,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
 
 /**
     @class wxDataViewVirtualListModel


@@ -448,15 +530,15 @@ 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
     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}
 */
 
     @library{wxadv}
     @category{dvc}
 */

-class wxDataViewVirtualListModel : public wxDataViewModel
+
+class wxDataViewVirtualListModel : public wxDataViewListModel

 {
 public:
     /**
 {
 public:
     /**


@@ -464,10 +546,6 @@ public:
     */
     wxDataViewVirtualListModel(unsigned int initial_size = 0);
 
     */
     wxDataViewVirtualListModel(unsigned int initial_size = 0);
 

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

 };
 
 
 };
 
 


@@ -589,6 +667,8 @@ public:
            Multiple selection mode.
     @style{wxDV_ROW_LINES}
            Use alternating colours for rows if supported by platform and theme.
            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}
     @style{wxDV_HORIZ_RULES}
            Display fine rules between row if supported.
     @style{wxDV_VERT_RULES}


@@ -660,7 +740,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.


@@ -841,7 +922,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.


@@ -897,6 +979,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.
     */


@@ -947,6 +1049,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);
 


@@ -960,6 +1066,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.
     */


@@ -1114,6 +1239,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.


@@ -1353,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
 
 /**
     @class wxDataViewDateRenderer


@@ -1705,6 +1863,64 @@ 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
     */


@@ -2476,7 +2692,7 @@ public:
     void SetColumn(int col);
 
     /**
     void SetColumn(int col);
 
     /**

-        For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
+        For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.

     */
     void SetDataViewColumn(wxDataViewColumn* col);
 
     */
     void SetDataViewColumn(wxDataViewColumn* col);