patch from Utensil Candel which refactors and documents the AutoCaptureMechanism...

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

diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h
index c5f69353bd3597d860c4cee96590e84c0b88a559..aa54468bcf36a662523c703c9a430a50fdf4f529 100644 (file)
--- a/interface/wx/dataview.h
+++ b/interface/wx/dataview.h
@@ -1,129 +1,11 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dataview.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dataview.h

-// Purpose:     interface of wxDataViewIconText
+// Purpose:     interface of wxDataView* classes

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

-/**
-    @class wxDataViewIconText
-
-    wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
-    This class can be converted to and from a wxVariant.
-
-    @library{wxadv}
-    @category{dvc}
-*/
-class wxDataViewIconText : public wxObject
-{
-public:
-    //@{
-    /**
-        Constructor.
-    */
-    wxDataViewIconText(const wxString& text = wxEmptyString,
-                       const wxIcon& icon = wxNullIcon);
-    wxDataViewIconText(const wxDataViewIconText& other);
-    //@}
-
-    /**
-        Gets the icon.
-    */
-    const wxIcon& GetIcon() const;
-
-    /**
-        Gets the text.
-    */
-    wxString GetText() const;
-
-    /**
-        Set the icon.
-    */
-    void SetIcon(const wxIcon& icon);
-
-    /**
-        Set the text.
-    */
-    void SetText(const wxString& text);
-};
-
-
-
-/**
-    @class wxDataViewEvent
-
-    This is the event class for the wxDataViewCtrl notifications.
-
-    @library{wxadv}
-    @category{events,dvc}
-*/
-class wxDataViewEvent : public wxNotifyEvent
-{
-public:
-    //@{
-    /**
-        Constructor. Typically used by wxWidgets internals only.
-    */
-    wxDataViewEvent(wxEventType commandType = wxEVT_NULL,
-                    int winid = 0);
-    wxDataViewEvent(const wxDataViewEvent& event);
-    //@}
-
-    /**
-        Used to clone the event.
-    */
-    wxEvent* Clone() const;
-
-    /**
-        Returns the position of the column in the control or -1
-        if no column field was set by the event emitter.
-    */
-    int GetColumn() const;
-
-    /**
-        Returns a pointer to the wxDataViewColumn from which
-        the event was emitted or @NULL.
-    */
-    wxDataViewColumn* GetDataViewColumn() const;
-
-    /**
-        Returns the wxDataViewModel associated with the event.
-    */
-    wxDataViewModel* GetModel() const;
-
-    /**
-        Returns a the position of a context menu event in screen coordinates.
-    */
-    wxPoint GetPosition() const;
-
-    /**
-        Returns a reference to a value.
-    */
-    const wxVariant& GetValue() const;
-
-    /**
-        Sets the column index associated with this event.
-    */
-    void SetColumn(int col);
-
-    /**
-        For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
-    */
-    void SetDataViewColumn(wxDataViewColumn* col);
-
-    /**
-        Sets the dataview model associated with this event.
-    */
-    void SetModel(wxDataViewModel* model);
-
-    /**
-        Sets the value associated with this event.
-    */
-    void SetValue(const wxVariant& value);
-};
-
-

 
 /**
     @class wxDataViewModel
 
 /**
     @class wxDataViewModel


@@ -203,11 +85,6 @@ public:
     */
     wxDataViewModel();
 
     */
     wxDataViewModel();
 

-    /**
-        Destructor. This should not be called directly. Use DecRef() instead.
-    */
-    virtual ~wxDataViewModel();
-

     /**
         Adds a wxDataViewModelNotifier to the model.
     */
     /**
         Adds a wxDataViewModelNotifier to the model.
     */


@@ -232,7 +109,7 @@ public:
                         bool ascending);
 
     /**
                         bool ascending);
 
     /**

-        Oberride this to indicate that the item has special font attributes.
+        Override this to indicate that the item has special font attributes.

         This only affects the wxDataViewTextRendererText renderer.
 
         @see wxDataViewItemAttr.
         This only affects the wxDataViewTextRendererText renderer.
 
         @see wxDataViewItemAttr.


@@ -369,6 +246,13 @@ public:
     */
     virtual bool ValueChanged(const wxDataViewItem& item,
                               unsigned int col);
     */
     virtual bool ValueChanged(const wxDataViewItem& item,
                               unsigned int col);

+
+protected:
+
+    /**
+        Destructor. This should not be called directly. Use DecRef() instead.
+    */
+    virtual ~wxDataViewModel();

 };
 
 
 };
 
 


@@ -410,7 +294,7 @@ public:
                 unsigned int column, bool ascending);
 
     /**
                 unsigned int column, bool ascending);
 
     /**

-        Oberride this to indicate that the row has special font attributes.
+        Override this to indicate that the row has special font attributes.

         This only affects the wxDataViewTextRendererText() renderer.
 
         @see wxDataViewItemAttr.
         This only affects the wxDataViewTextRendererText() renderer.
 
         @see wxDataViewItemAttr.


@@ -605,7 +489,7 @@ public:
 
     A wxDataViewItem is used to represent a (visible) item in the control.
 
 
     A wxDataViewItem is used to represent a (visible) item in the control.
 

-    Unlike wxListCtrl wxDataViewCtrl doesn't get its data from the user through
+    Unlike wxListCtrl, wxDataViewCtrl doesn't get its data from the user through

     virtual functions or by setting it directly. Instead you need to write your own
     wxDataViewModel and associate it with this control.
     Then you need to add a number of wxDataViewColumn to this control to define
     virtual functions or by setting it directly. Instead you need to write your own
     wxDataViewModel and associate it with this control.
     Then you need to add a number of wxDataViewColumn to this control to define


@@ -614,7 +498,7 @@ public:
 
     A number of standard renderers for rendering text, dates, images, toggle,
     a progress bar etc. are provided. Additionally, the user can write custom
 
     A number of standard renderers for rendering text, dates, images, toggle,
     a progress bar etc. are provided. Additionally, the user can write custom

-    renderes deriving from wxDataViewCustomRenderer for displaying anything.
+    renderers deriving from wxDataViewCustomRenderer for displaying anything.

 
     All data transfer from the control to the model and the user code is done
     through wxVariant which can be extended to support more data formats as necessary.
 
     All data transfer from the control to the model and the user code is done
     through wxVariant which can be extended to support more data formats as necessary.


@@ -745,13 +629,13 @@ public:
                                        unsigned int model_column,
                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
                                        int width = -1,
                                        unsigned int model_column,
                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
                                        int width = -1,

-                                       wxAlignment align = wxALIGN_CENTER,
+                                       wxAlignment align = wxALIGN_NOT,

                                        int flags = wxDATAVIEW_COL_RESIZABLE);
     wxDataViewColumn* AppendDateColumn(const wxBitmap& label,
                                        unsigned int model_column,
                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
                                        int width = -1,
                                        int flags = wxDATAVIEW_COL_RESIZABLE);
     wxDataViewColumn* AppendDateColumn(const wxBitmap& label,
                                        unsigned int model_column,
                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
                                        int width = -1,

-                                       wxAlignment align = wxALIGN_CENTER,
+                                       wxAlignment align = wxALIGN_NOT,

                                        int flags = wxDATAVIEW_COL_RESIZABLE);
     //@}
 
                                        int flags = wxDATAVIEW_COL_RESIZABLE);
     //@}
 


@@ -768,13 +652,13 @@ public:
                                            unsigned int model_column,
                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
                                            int width = -1,
                                            unsigned int model_column,
                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
                                            int width = -1,

-                                           wxAlignment align = wxALIGN_LEFT,
+                                           wxAlignment align = wxALIGN_NOT,

                                            int flags = wxDATAVIEW_COL_RESIZABLE);
     wxDataViewColumn* AppendIconTextColumn(const wxBitmap& label,
                                            unsigned int model_column,
                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
                                            int width = -1,
                                            int flags = wxDATAVIEW_COL_RESIZABLE);
     wxDataViewColumn* AppendIconTextColumn(const wxBitmap& label,
                                            unsigned int model_column,
                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
                                            int width = -1,

-                                           wxAlignment align = wxALIGN_LEFT,
+                                           wxAlignment align = wxALIGN_NOT,

                                            int flags = wxDATAVIEW_COL_RESIZABLE);
     //@}
 
                                            int flags = wxDATAVIEW_COL_RESIZABLE);
     //@}
 


@@ -812,13 +696,13 @@ public:
                                        unsigned int model_column,
                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
                                        int width = -1,
                                        unsigned int model_column,
                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
                                        int width = -1,

-                                       wxAlignment align = wxALIGN_LEFT,
+                                       wxAlignment align = wxALIGN_NOT,

                                        int flags = wxDATAVIEW_COL_RESIZABLE);
     wxDataViewColumn* AppendTextColumn(const wxBitmap& label,
                                        unsigned int model_column,
                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
                                        int width = -1,
                                        int flags = wxDATAVIEW_COL_RESIZABLE);
     wxDataViewColumn* AppendTextColumn(const wxBitmap& label,
                                        unsigned int model_column,
                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
                                        int width = -1,

-                                       wxAlignment align = wxALIGN_LEFT,
+                                       wxAlignment align = wxALIGN_NOT,

                                        int flags = wxDATAVIEW_COL_RESIZABLE);
     //@}
 
                                        int flags = wxDATAVIEW_COL_RESIZABLE);
     //@}
 


@@ -855,11 +739,6 @@ public:
     */
     virtual bool ClearColumns();
 
     */
     virtual bool ClearColumns();
 

-    /**
-        Unselects all rows.
-    */
-    void ClearSelection();
-

     /**
         Collapses the item.
     */
     /**
         Collapses the item.
     */


@@ -890,6 +769,13 @@ public:
     */
     virtual void Expand(const wxDataViewItem& item);
 
     */
     virtual void Expand(const wxDataViewItem& item);
 

+    /**
+       Expands all ancestors of the @a item. This method also
+       ensures that the item itself as well as all ancestor
+       items have been read from the model by the control.
+    */
+    virtual void ExpandAncestors( const wxDataViewItem & item );
+

     /**
         Returns pointer to the column. @a pos refers to the position in the
         control which may change after reordering columns by the user.
     /**
         Returns pointer to the column. @a pos refers to the position in the
         control which may change after reordering columns by the user.


@@ -949,6 +835,11 @@ public:
     virtual void HitTest(const wxPoint& point, wxDataViewItem& item,
                          wxDataViewColumn*& col) const;
 
     virtual void HitTest(const wxPoint& point, wxDataViewItem& item,
                          wxDataViewColumn*& col) const;
 

+    /**
+        Return @true if the item is expanded.
+    */
+    virtual bool IsExpanded(const wxDataViewItem& item) const;
+

     /**
         Return @true if the item is selected.
     */
     /**
         Return @true if the item is selected.
     */


@@ -1516,7 +1407,7 @@ public:
     */
     wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap",
                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
     */
     wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap",
                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,

-                             int align = wxDVR_DEFAULT_ALIGNMENT,
+                             int align = wxDVR_DEFAULT_ALIGNMENT);

 };
 
 
 };
 
 


@@ -1535,7 +1426,7 @@ enum wxDataViewColumnFlags
     @class wxDataViewColumn
 
     This class represents a column in a wxDataViewCtrl.
     @class wxDataViewColumn
 
     This class represents a column in a wxDataViewCtrl.

-    One wxDataViewColumn is bound to one column in the data model, to which the
+    One wxDataViewColumn is bound to one column in the data model to which the

     wxDataViewCtrl has been associated.
 
     An instance of wxDataViewRenderer is used by this class to render its data.
     wxDataViewCtrl has been associated.
 
     An instance of wxDataViewRenderer is used by this class to render its data.


@@ -1543,7 +1434,7 @@ enum wxDataViewColumnFlags
     @library{wxadv}
     @category{dvc}
 */
     @library{wxadv}
     @category{dvc}
 */

-class wxDataViewColumn : public wxObject
+class wxDataViewColumn : public wxHeaderColumn

 {
 public:
     //@{
 {
 public:
     //@{


@@ -1554,26 +1445,16 @@ public:
                      wxDataViewRenderer* renderer,
                      unsigned int model_column,
                      int width = wxDVC_DEFAULT_WIDTH,
                      wxDataViewRenderer* renderer,
                      unsigned int model_column,
                      int width = wxDVC_DEFAULT_WIDTH,

-                     wxAlignment align = wxALIGN_CENTRE,
+                     wxAlignment align = wxALIGN_CENTER,

                      int flags = wxDATAVIEW_COL_RESIZABLE);
     wxDataViewColumn(const wxBitmap& bitmap,
                      wxDataViewRenderer* renderer,
                      unsigned int model_column,
                      int width = wxDVC_DEFAULT_WIDTH,
                      int flags = wxDATAVIEW_COL_RESIZABLE);
     wxDataViewColumn(const wxBitmap& bitmap,
                      wxDataViewRenderer* renderer,
                      unsigned int model_column,
                      int width = wxDVC_DEFAULT_WIDTH,

-                     wxAlignment align = wxALIGN_CENTRE,
+                     wxAlignment align = wxALIGN_CENTER,

                      int flags = wxDATAVIEW_COL_RESIZABLE);
     //@}
 
                      int flags = wxDATAVIEW_COL_RESIZABLE);
     //@}
 

-    /**
-        Destructor.
-    */
-    virtual ~wxDataViewColumn();
-
-    /**
-        Returns the bitmap in the header of the column, if any.
-    */
-    const wxBitmap& GetBitmap() const;
-

     /**
         Returns the index of the column of the model, which this
         wxDataViewColumn is displaying.
     /**
         Returns the index of the column of the model, which this
         wxDataViewColumn is displaying.


@@ -1591,68 +1472,6 @@ public:
         @see wxDataViewRenderer.
     */
     wxDataViewRenderer* GetRenderer() const;
         @see wxDataViewRenderer.
     */
     wxDataViewRenderer* GetRenderer() const;

-
-    /**
-        Returns @true if the column is reorderable.
-    */
-    bool GetReorderable();
-
-    /**
-        Returns @true if the column is sortable.
-
-        @see SetSortable()
-    */
-    bool GetSortable();
-
-    /**
-        Returns the width of the column.
-    */
-    virtual int GetWidth() const;
-
-    /**
-        Returns @true, if the sort order is ascending.
-
-        @see SetSortOrder()
-    */
-    virtual bool IsSortOrderAscending() const;
-
-    /**
-        Set the alignment of the column header.
-    */
-    virtual void SetAlignment(wxAlignment align);
-
-    /**
-        Set the bitmap of the column header.
-    */
-    virtual void SetBitmap(const wxBitmap& bitmap);
-
-    /**
-        Indicate wether the column can be reordered by the user using the mouse.
-        This is typically implemented visually by dragging the header button around.
-    */
-    virtual void SetReorderable(bool reorderable);
-
-    /**
-        Indicate the sort order if the implementation of the wxDataViewCtrl supports
-        it, most commonly by showing a little arrow.
-    */
-    virtual void SetSortOrder(bool ascending);
-
-    /**
-        Indicate that the column is sortable.
-        This does not show any sorting indicate yet, but it does make the column
-        header clickable. Call SetSortOrder() afterwards to actually make the sort
-        indicator appear.
-
-        If @a sortable is @false, the column header is no longer clickable and
-        the sort indicator (little arrow) will disappear.
-    */
-    virtual void SetSortable(bool sortable);
-
-    /**
-        Set the title of the column header to @a title.
-    */
-    virtual void SetTitle(const wxString& title);

 };
 
 
 };
 
 


@@ -1774,7 +1593,7 @@ public:
     /**
         Returns the store.
     */
     /**
         Returns the store.
     */

-    wxDataViewTreeStore* GetStore() const;
+    wxDataViewTreeStore* GetStore();

     const wxDataViewTreeStore* GetStore() const;
     //@}
 
     const wxDataViewTreeStore* GetStore() const;
     //@}
 


@@ -1991,3 +1810,116 @@ public:
     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
 };
 
     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
 };
 

+
+/**
+    @class wxDataViewIconText
+
+    wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
+    This class can be converted to and from a wxVariant.
+
+    @library{wxadv}
+    @category{dvc}
+*/
+class wxDataViewIconText : public wxObject
+{
+public:
+    //@{
+    /**
+        Constructor.
+    */
+    wxDataViewIconText(const wxString& text = wxEmptyString,
+                       const wxIcon& icon = wxNullIcon);
+    wxDataViewIconText(const wxDataViewIconText& other);
+    //@}
+
+    /**
+        Gets the icon.
+    */
+    const wxIcon& GetIcon() const;
+
+    /**
+        Gets the text.
+    */
+    wxString GetText() const;
+
+    /**
+        Set the icon.
+    */
+    void SetIcon(const wxIcon& icon);
+
+    /**
+        Set the text.
+    */
+    void SetText(const wxString& text);
+};
+
+
+
+/**
+    @class wxDataViewEvent
+
+    This is the event class for the wxDataViewCtrl notifications.
+
+    @library{wxadv}
+    @category{events,dvc}
+*/
+class wxDataViewEvent : public wxNotifyEvent
+{
+public:
+    //@{
+    /**
+        Constructor. Typically used by wxWidgets internals only.
+    */
+    wxDataViewEvent(wxEventType commandType = wxEVT_NULL,
+                    int winid = 0);
+    wxDataViewEvent(const wxDataViewEvent& event);
+    //@}
+
+    /**
+        Returns the position of the column in the control or -1
+        if no column field was set by the event emitter.
+    */
+    int GetColumn() const;
+
+    /**
+        Returns a pointer to the wxDataViewColumn from which
+        the event was emitted or @NULL.
+    */
+    wxDataViewColumn* GetDataViewColumn() const;
+
+    /**
+        Returns the wxDataViewModel associated with the event.
+    */
+    wxDataViewModel* GetModel() const;
+
+    /**
+        Returns a the position of a context menu event in screen coordinates.
+    */
+    wxPoint GetPosition() const;
+
+    /**
+        Returns a reference to a value.
+    */
+    const wxVariant& GetValue() const;
+
+    /**
+        Sets the column index associated with this event.
+    */
+    void SetColumn(int col);
+
+    /**
+        For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
+    */
+    void SetDataViewColumn(wxDataViewColumn* col);
+
+    /**
+        Sets the dataview model associated with this event.
+    */
+    void SetModel(wxDataViewModel* model);
+
+    /**
+        Sets the value associated with this event.
+    */
+    void SetValue(const wxVariant& value);
+};
+