X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/5b99d5d8eae1091046d3fd475c48fa43073e03b3..f99af6c05204b93eca9b0f21bc803f98e1a9c6bb:/interface/dataview.h

diff --git a/interface/dataview.h b/interface/dataview.h
index fd58d96c90..08be7734b1 100644
--- a/interface/dataview.h
+++ b/interface/dataview.h
@@ -16,7 +16,7 @@
     a wxVariant.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewIconText : public wxObject
 {
@@ -60,7 +60,7 @@ public:
     wxDataViewEvent - the event class for the wxDataViewCtrl notifications
 
     @library{wxadv}
-    @category{FIXME}
+    @category{events,dvc}
 */
 class wxDataViewEvent : public wxNotifyEvent
 {
@@ -129,153 +129,6 @@ public:
 
 
 
-/**
-    @class wxDataViewIconTextRenderer
-    @wxheader{dataview.h}
-
-    The wxDataViewIconTextRenderer class is used to display text with
-    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 a from a wxVariant using the left shift
-    operator.
-
-    @library{wxadv}
-    @category{FIXME}
-*/
-class wxDataViewIconTextRenderer : public wxDataViewRenderer
-{
-public:
-    /**
-
-    */
-    wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText",
-                               wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
-};
-
-
-
-/**
-    @class wxDataViewIndexListModel
-    @wxheader{dataview.h}
-
-    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 special in the it is implemented differently under OS X
-    and other platforms. Under OS X a wxDataViewItem is always persistent
-    and this is also the case for this class. Under other platforms, the
-    meaning of a wxDataViewItem is changed to reflect a row number for
-    wxDataViewIndexListModel. The consequence of this is that
-    wxDataViewIndexListModel can be used as a virtual model with an
-    almost infinate number of items on platforms other than OS X.
-
-    @library{wxbase}
-    @category{FIXME}
-*/
-class wxDataViewIndexListModel : public wxDataViewModel
-{
-public:
-    /**
-        Constructor.
-    */
-    wxDataViewIndexListModel(unsigned int initial_size = 0);
-
-    /**
-        Destructor.
-    */
-    ~wxDataViewIndexListModel();
-
-    /**
-        Compare method that sorts the items by their index.
-    */
-    int Compare(const wxDataViewItem& item1,
-                const wxDataViewItem& item2,
-                unsigned int column, bool ascending);
-
-    /**
-        Oberride this to indicate that the row has special font attributes.
-        This only affects the
-        wxDataViewTextRendererText() renderer.
-        See also wxDataViewItemAttr.
-    */
-    bool GetAttr(unsigned int row, unsigned int col,
-                 wxDataViewItemAttr& attr);
-
-    /**
-        Returns the wxDataViewItem at the given @e row.
-    */
-    wxDataViewItem GetItem(unsigned int row) const;
-
-    /**
-        Returns the position of given @e item.
-    */
-    unsigned int GetRow(const wxDataViewItem& item) const;
-
-    /**
-        Override this to allow getting values from the model.
-    */
-    void GetValue(wxVariant& variant, unsigned int row,
-                  unsigned int col) const;
-
-    /**
-        Call this after if the data has to be read again from
-        the model. This is useful after major changes when
-        calling the methods below (possibly thousands of times)
-        doesn't make sense.
-    */
-    void Reset(unsigned int new_size);
-
-    /**
-        Call this after a row has been appended to the model.
-    */
-    void RowAppended();
-
-    /**
-        Call this after a row has been changed.
-    */
-    void RowChanged(unsigned int row);
-
-    /**
-        Call this after a row has been deleted.
-    */
-    void RowDeleted(unsigned int row);
-
-    /**
-        Call this after a row has been inserted at the given position.
-    */
-    void RowInserted(unsigned int before);
-
-    /**
-        Call this after a row has been prepended to the model.
-    */
-    void RowPrepended();
-
-    /**
-        Call this after a value has been changed.
-    */
-    void RowValueChanged(unsigned int row, unsigned int col);
-
-    /**
-        Call this after rows have been deleted. The array will internally
-        get copied and sorted in descending order so that the rows with
-        the highest position will be deleted first.
-    */
-    void RowsDeleted(const wxArrayInt& rows);
-
-    /**
-        Called in order to set a value in the model.
-    */
-    bool SetValue(const wxVariant& variant, unsigned int row,
-                  unsigned int col);
-};
-
-
-
 /**
     @class wxDataViewModel
     @wxheader{dataview.h}
@@ -341,6 +194,7 @@ public:
     Currently wxWidgets provides the following models apart
     from the base model:
     wxDataViewIndexListModel,
+    wxDataViewVirtualListModel,
     wxDataViewTreeStore.
 
     Note that wxDataViewModel is reference counted, derives from
@@ -359,7 +213,7 @@ public:
 
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewModel : public wxObjectRefData
 {
@@ -541,6 +395,151 @@ public:
 
 
 
+/**
+    @class wxDataViewIndexListModel
+    @wxheader{dataview.h}
+
+    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.
+
+    @library{wxbase}
+    @category{dvc}
+*/
+class wxDataViewIndexListModel : public wxDataViewModel
+{
+public:
+    /**
+        Constructor.
+    */
+    wxDataViewIndexListModel(unsigned int initial_size = 0);
+
+    /**
+        Destructor.
+    */
+    ~wxDataViewIndexListModel();
+
+    /**
+        Compare method that sorts the items by their index.
+    */
+    int Compare(const wxDataViewItem& item1,
+                const wxDataViewItem& item2,
+                unsigned int column, bool ascending);
+
+    /**
+        Oberride this to indicate that the row has special font attributes.
+        This only affects the
+        wxDataViewTextRendererText() renderer.
+        See also wxDataViewItemAttr.
+    */
+    bool GetAttr(unsigned int row, unsigned int col,
+                 wxDataViewItemAttr& attr);
+
+    /**
+        Returns the wxDataViewItem at the given @e row.
+    */
+    wxDataViewItem GetItem(unsigned int row) const;
+
+    /**
+        Returns the position of given @e item.
+    */
+    unsigned int GetRow(const wxDataViewItem& item) const;
+
+    /**
+        Override this to allow getting values from the model.
+    */
+    void GetValue(wxVariant& variant, unsigned int row,
+                  unsigned int col) const;
+
+    /**
+        Call this after if the data has to be read again from
+        the model. This is useful after major changes when
+        calling the methods below (possibly thousands of times)
+        doesn't make sense.
+    */
+    void Reset(unsigned int new_size);
+
+    /**
+        Call this after a row has been appended to the model.
+    */
+    void RowAppended();
+
+    /**
+        Call this after a row has been changed.
+    */
+    void RowChanged(unsigned int row);
+
+    /**
+        Call this after a row has been deleted.
+    */
+    void RowDeleted(unsigned int row);
+
+    /**
+        Call this after a row has been inserted at the given position.
+    */
+    void RowInserted(unsigned int before);
+
+    /**
+        Call this after a row has been prepended to the model.
+    */
+    void RowPrepended();
+
+    /**
+        Call this after a value has been changed.
+    */
+    void RowValueChanged(unsigned int row, unsigned int col);
+
+    /**
+        Call this after rows have been deleted. The array will internally
+        get copied and sorted in descending order so that the rows with
+        the highest position will be deleted first.
+    */
+    void RowsDeleted(const wxArrayInt& rows);
+
+    /**
+        Called in order to set a value in the model.
+    */
+    bool SetValue(const wxVariant& variant, unsigned int row,
+                  unsigned int col);
+};
+
+
+
+/**
+    @class wxDataViewVirtualListModel
+    @wxheader{dataview.h}
+
+    wxDataViewVirtualListModel is a specialized data model which lets
+    you address an item by its position (row) rather than its
+    wxDataViewItem and as such offers the exact same interface as
+    wxDataViewIndexListModel. The important difference is that under
+    platforms other than OS X, using this model will result in a
+    truely 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).
+
+    @see wxDataViewIndexListModel for the API.
+
+    @library{wxbase}
+    @category{dvc}
+*/
+class wxDataViewVirtualListModel : public wxDataViewModel
+{
+public:
+    /**
+        Constructor.
+    */
+    wxDataViewVirtualListModel(unsigned int initial_size = 0);
+};
+
+
 
 /**
     @class wxDataViewItemAttr
@@ -555,7 +554,7 @@ public:
     wxDataViewTextRendererText().
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewItemAttr
 {
@@ -605,7 +604,7 @@ public:
     wxDataViewModel::GetChildren.
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewItem
 {
@@ -677,11 +676,13 @@ public:
            Display fine rules between row if supported.
     @style{wxDV_VERT_RULES}
            Display fine rules between columns is supported.
+    @style{wxDV_VARIABLE_LINE_HEIGHT}
+           Allow variable line heights. This can be inefficient when displaying large number of items.
     @endStyleTable
 
     @library{wxadv}
-    @category{ctrl}
-    @appearance{dataviewctrl.png}
+    @category{ctrl,dvc}
+    <!-- @appearance{dataviewctrl.png} -->
 */
 class wxDataViewCtrl : public wxControl
 {
@@ -703,6 +704,14 @@ public:
     */
     ~wxDataViewCtrl();
 
+    /**
+        Add a wxDataViewColumn to the control. Returns
+        @e @true on success.
+        Note that there is a number of short cut methods which implicitly create
+        a wxDataViewColumn and a wxDataViewRenderer for it (see below).
+    */
+    virtual bool AppendColumn(wxDataViewColumn* col);
+
     //@{
     /**
         Appends a column for rendering a bitmap. Returns the wxDataViewColumn
@@ -722,19 +731,13 @@ public:
                                          int flags = wxDATAVIEW_COL_RESIZABLE);
     //@}
 
-    /**
-        Add a wxDataViewColumn to the control. Returns
-        @e @true on success.
-        Note that there is a number of short cut methods which implicitly create
-        a wxDataViewColumn and a
-        wxDataViewRenderer for it (see below).
-    */
-    virtual bool AppendColumn(wxDataViewColumn* col);
-
     //@{
     /**
         Appends a column for rendering a date. Returns the wxDataViewColumn
         created in the function or @NULL on failure.
+        
+        NB: The @e align parameter is applied to both the column header and
+        the column renderer.
     */
     wxDataViewColumn* AppendDateColumn(const wxString& label,
                                        unsigned int model_column,
@@ -753,8 +756,11 @@ public:
     //@{
     /**
         Appends a column for rendering text with an icon. Returns the wxDataViewColumn
-        created in the function or @NULL on failure. This uses the
-        wxDataViewIconTextRenderer.
+        created in the function or @NULL on failure. This method uses the
+        wxDataViewIconTextRenderer class.
+        
+        NB: The @e align parameter is applied to both the column header and
+        the column renderer.
     */
     wxDataViewColumn* AppendIconTextColumn(const wxString& label,
                                            unsigned int model_column,
@@ -773,8 +779,10 @@ public:
     //@{
     /**
         Appends a column for rendering a progress indicator. Returns the
-        wxDataViewColumn
-        created in the function or @NULL on failure.
+        wxDataViewColumn created in the function or @NULL on failure.
+        
+        NB: The @e align parameter is applied to both the column header and
+        the column renderer.
     */
     wxDataViewColumn* AppendProgressColumn(const wxString& label,
                                            unsigned int model_column,
@@ -794,6 +802,9 @@ public:
     /**
         Appends a column for rendering text. Returns the wxDataViewColumn
         created in the function or @NULL on failure.
+        
+        NB: The @e align parameter is applied to both the column header and
+        the column renderer.
     */
     wxDataViewColumn* AppendTextColumn(const wxString& label,
                                        unsigned int model_column,
@@ -813,6 +824,9 @@ public:
     /**
         Appends a column for rendering a toggle. Returns the wxDataViewColumn
         created in the function or @NULL on failure.
+        
+        NB: The @e align parameter is applied to both the column header and
+        the column renderer.
     */
     wxDataViewColumn* AppendToggleColumn(const wxString& label,
                                          unsigned int model_column,
@@ -829,8 +843,8 @@ public:
     //@}
 
     /**
-        Associates a wxDataViewModel with the
-        control. This increases the reference count of the model by 1.
+        Associates a wxDataViewModel with the control. This increases the reference
+        count of the model by 1.
     */
     virtual bool AssociateModel(wxDataViewModel* model);
 
@@ -991,7 +1005,7 @@ public:
     information.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewModelNotifier
 {
@@ -1014,7 +1028,7 @@ public:
     /**
         Get owning wxDataViewModel.
     */
-    wxDataViewModel* GetOwner();
+    wxDataViewModel* GetOwner() const;
 
     /**
         Called by owning model.
@@ -1084,11 +1098,6 @@ public:
     wxDataViewDateRenderer.
     wxDataViewSpinRenderer.
 
-    Note that the @e alignment parameter is ignored under OS X and
-    the alignment is controlled by wxDataViewColumn::GetAlignment()
-    so that under OS X, column header alignment and column content
-    alignment are always the same and cannot be set independently.
-    
     Additionally, the user can write own renderers by deriving from
     wxDataViewCustomRenderer.
 
@@ -1127,7 +1136,7 @@ public:
 
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewRenderer : public wxObject
 {
@@ -1137,10 +1146,10 @@ public:
     */
     wxDataViewRenderer(const wxString& varianttype,
                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
-                       int align = wxALIGN_LEFT|wxALIGN_CENTRE_VERTICAL);
+                       int align = wxDVR_DEFAULT_ALIGNMENT );
 
     /**
-        Returns the alignment.
+        Returns the alignment. See SetAlignment()
     */
     virtual int GetAlignment() const;
 
@@ -1152,7 +1161,7 @@ public:
     /**
         Returns pointer to the owning wxDataViewColumn.
     */
-    virtual wxDataViewColumn* GetOwner();
+    virtual wxDataViewColumn* GetOwner() const;
 
     /**
         This methods retrieves the value from the renderer in order to
@@ -1168,7 +1177,12 @@ public:
     virtual wxString GetVariantType();
 
     /**
-        Sets the alignment.
+        Sets the alignment of the renderer's content. The default value
+        of wxDVR_DEFAULT_ALIGMENT indicates that the content should 
+        have the same alignment as the column header. The method is
+        not implemented under OS X and the renderer always aligns its
+        contents as the column header on that platform. The other platforms
+        support both vertical and horizontal alignment.
     */
     virtual void SetAlignment( int align );
     /**
@@ -1207,7 +1221,7 @@ public:
     in-place editing if desired.
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewTextRenderer : public wxDataViewRenderer
 {
@@ -1222,6 +1236,33 @@ public:
 
 
 
+/**
+    @class wxDataViewIconTextRenderer
+    @wxheader{dataview.h}
+
+    The wxDataViewIconTextRenderer class is used to display text with
+    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 a from a wxVariant using the left shift
+    operator.
+
+    @library{wxadv}
+    @category{dvc}
+*/
+class wxDataViewIconTextRenderer : public wxDataViewRenderer
+{
+public:
+    /**
+
+    */
+    wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText",
+                               wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
+                               int align = wxDVR_DEFAULT_ALIGNMENT );
+};
+
+
+
 /**
     @class wxDataViewProgressRenderer
     @wxheader{dataview.h}
@@ -1229,7 +1270,7 @@ public:
     wxDataViewProgressRenderer
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewProgressRenderer : public wxDataViewRenderer
 {
@@ -1254,7 +1295,7 @@ public:
     The renderer only support variants of type @e long.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewSpinRenderer : public wxDataViewCustomRenderer
 {
@@ -1277,7 +1318,7 @@ public:
     wxDataViewToggleRenderer
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewToggleRenderer : public wxDataViewRenderer
 {
@@ -1298,7 +1339,7 @@ public:
     wxDataViewDateRenderer
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewDateRenderer : public wxDataViewRenderer
 {
@@ -1324,7 +1365,7 @@ public:
     wxDataViewItemAttr.
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewTextRendererAttr : public wxDataViewTextRenderer
 {
@@ -1338,6 +1379,7 @@ public:
 };
 
 
+
 /**
     @class wxDataViewCustomRenderer
     @wxheader{dataview.h}
@@ -1359,7 +1401,7 @@ public:
     in order to end the editing.
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewCustomRenderer : public wxDataViewRenderer
 {
@@ -1463,7 +1505,7 @@ public:
     wxDataViewBitmapRenderer
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewBitmapRenderer : public wxDataViewRenderer
 {
@@ -1478,7 +1520,6 @@ public:
 
 
 
-
 /**
     @class wxDataViewColumn
     @wxheader{dataview.h}
@@ -1491,7 +1532,7 @@ public:
     this class to render its data.
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewColumn : public wxObject
 {
@@ -1533,7 +1574,7 @@ public:
     /**
         Returns the owning wxDataViewCtrl.
     */
-    wxDataViewCtrl* GetOwner();
+    wxDataViewCtrl* GetOwner() const;
 
     /**
         Returns the renderer of this wxDataViewColumn.
@@ -1619,8 +1660,8 @@ public:
     to the wxDataViewCtrl class simpler.
 
     @library{wxbase}
-    @category{ctrl}
-    @appearance{dataviewtreectrl.png}
+    @category{ctrl,dvc}
+    <!-- @appearance{dataviewtreectrl.png} -->
 */
 class wxDataViewTreeCtrl : public wxDataViewCtrl
 {
@@ -1810,7 +1851,7 @@ public:
     This comes at the price of much reduced flexibility.
 
     @library{wxadv}
-    @category{FIXME}
+    @category{dvc}
 */
 class wxDataViewTreeStore : public wxDataViewModel
 {
@@ -1941,5 +1982,3 @@ public:
     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
 };
 
-
-