Fix wrong wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK name in the docs.

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

diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h
index 0c06dae862881751c1d3e7a4d41cf8c1277b34ff..600a1aa7b868be9cfb4faf591431683705f97248 100644 (file)
--- a/interface/wx/dataview.h
+++ b/interface/wx/dataview.h
@@ -183,10 +183,7 @@ public:
         @return
             @true if this item should be enabled, @false otherwise.
 
         @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
+        @note Currently disabling items is not supported by the wxOSX/Carbon

               implementation.
 
         @since 2.9.2
               implementation.
 
         @since 2.9.2


@@ -376,7 +373,7 @@ public:
     */
     int Compare(const wxDataViewItem& item1,
                 const wxDataViewItem& item2,
     */
     int Compare(const wxDataViewItem& item1,
                 const wxDataViewItem& item2,

-                unsigned int column, bool ascending);
+                unsigned int column, bool ascending) const;

 
     /**
         Override this to indicate that the row has special font attributes.
 
     /**
         Override this to indicate that the row has special font attributes.


@@ -580,6 +577,16 @@ public:
     */
     void SetColour(const wxColour& colour);
 
     */
     void SetColour(const wxColour& colour);
 

+    /**
+        Call this to set the background colour to use.
+
+        Currently this attribute is only supported in the generic version of
+        wxDataViewCtrl and ignored by the native GTK+ and OS X implementations.
+
+        @since 2.9.4
+    */
+    void SetBackgroundColour(const wxColour& colour);
+

     /**
         Call this to indicate that the item shall be displayed in italic text.
     */
     /**
         Call this to indicate that the item shall be displayed in italic text.
     */


@@ -631,6 +638,61 @@ public:
 };
 
 
 };
 
 

+// ----------------------------------------------------------------------------
+// wxDataViewCtrl flags
+// ----------------------------------------------------------------------------
+
+// size of a wxDataViewRenderer without contents:
+#define wxDVC_DEFAULT_RENDERER_SIZE     20
+
+// the default width of new (text) columns:
+#define wxDVC_DEFAULT_WIDTH             80
+
+// the default width of new toggle columns:
+#define wxDVC_TOGGLE_DEFAULT_WIDTH      30
+
+// the default minimal width of the columns:
+#define wxDVC_DEFAULT_MINWIDTH          30
+
+// The default alignment of wxDataViewRenderers is to take
+// the alignment from the column it owns.
+#define wxDVR_DEFAULT_ALIGNMENT         -1
+
+#define wxDV_SINGLE                  0x0000     // for convenience
+#define wxDV_MULTIPLE                0x0001     // can select multiple items
+
+#define wxDV_NO_HEADER               0x0002     // column titles not visible
+#define wxDV_HORIZ_RULES             0x0004     // light horizontal rules between rows
+#define wxDV_VERT_RULES              0x0008     // light vertical rules between columns
+
+#define wxDV_ROW_LINES               0x0010     // alternating colour in rows
+#define wxDV_VARIABLE_LINE_HEIGHT    0x0020     // variable line height
+
+// events
+
+wxEventType wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED;
+
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED;
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING;
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED;
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING;
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED;
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_START_EDITING;
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED;
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE;
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED;
+
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU;
+
+wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK;
+wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK;
+wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED;
+wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED;
+wxEventType wxEVT_COMMAND_DATAVIEW_CACHE_HINT;
+
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG;
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE;
+wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP;

 
 /**
     @class wxDataViewCtrl
 
 /**
     @class wxDataViewCtrl


@@ -687,9 +749,9 @@ public:
     @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
     @event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)}
     @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
     @event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)}

-           Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event. This
+           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
            event can be vetoed in order to prevent editing on an item by item

-           basis. Still experimental.
+           basis.

     @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
     @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
     @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
     @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}


@@ -705,9 +767,13 @@ public:
     @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
     @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
     @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
     @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}

-           Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
+           Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event
+           generated when the user right clicks inside the control. Notice that
+           this menu is generated even if the click didn't occur on any valid
+           item, in this case wxDataViewEvent::GetItem() simply returns an
+           invalid item.

     @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
     @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}

-           Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
+           Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK event.

     @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
     @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
     @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
     @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}


@@ -931,6 +997,17 @@ public:
     */
     virtual bool DeleteColumn(wxDataViewColumn* column);
 
     */
     virtual bool DeleteColumn(wxDataViewColumn* column);
 

+    /**
+        Programmatically starts editing given cell of @a item.
+
+        Doesn't do anything if the item or this column is not editable.
+
+        @note Currently not implemented in wxOSX/Carbon.
+
+        @since 2.9.4
+    */
+    virtual void EditItem(const wxDataViewItem& item, const wxDataViewColumn *column);
+

     /**
        Enable drag operations using the given @a format.
     */
     /**
        Enable drag operations using the given @a format.
     */


@@ -994,19 +1071,45 @@ public:
         item may be selected or not but under OS X the current item is always
         selected.
 
         item may be selected or not but under OS X the current item is always
         selected.
 

-        @see SetCurrentItem()
+        @see SetCurrentItem(), GetCurrentColumn()

 
         @since 2.9.2
      */
     wxDataViewItem GetCurrentItem() const;
 
 
         @since 2.9.2
      */
     wxDataViewItem GetCurrentItem() const;
 

+    /**
+        Returns the column that currently has focus.
+
+        If the focus is set to individual cell within the currently focused
+        item (as opposed to being on the item as a whole), then this is the
+        column that the focus is on.
+
+        Returns NULL if no column currently has focus.
+
+        @see GetCurrentItem()
+
+        @since 2.9.4
+     */
+    wxDataViewColumn *GetCurrentColumn() const;
+

     /**
         Returns indentation.
     */
     int GetIndent() const;
 
     /**
     /**
         Returns indentation.
     */
     int GetIndent() const;
 
     /**

-        Returns item rect.
+        Returns item rectangle.
+
+        This method is currently not implemented at all in wxGTK and only
+        implemented for non-@NULL @a col argument in wxOSX. It is fully
+        implemented in the generic version of the control.
+
+        @param item
+            A valid item.
+        @param col
+            If non-@NULL, the rectangle returned corresponds to the
+            intersection of the item with the specified column. If @NULL, the
+            rectangle spans all the columns.

     */
     virtual wxRect GetItemRect(const wxDataViewItem& item,
                                const wxDataViewColumn* col = NULL) const;
     */
     virtual wxRect GetItemRect(const wxDataViewItem& item,
                                const wxDataViewColumn* col = NULL) const;


@@ -1132,14 +1235,6 @@ public:
     */
     virtual void SetSelections(const wxDataViewItemArray& sel);
 
     */
     virtual void SetSelections(const wxDataViewItemArray& sel);
 

-    /** 
-        Programmatically starts editing the given item on the given column.
-        Currently not implemented on wxOSX Carbon.
-        @since 2.9.2
-    */
-    
-    virtual void StartEditor(const wxDataViewItem & item, unsigned int column);
-

     /**
         Unselect the given item.
     */
     /**
         Unselect the given item.
     */


@@ -1209,34 +1304,46 @@ public:
 
     /**
         Called by owning model.
 
     /**
         Called by owning model.

+
+        @return Always return @true from this function in derived classes.

     */
     virtual bool ItemAdded(const wxDataViewItem& parent,
                            const wxDataViewItem& item) = 0;
 
     /**
         Called by owning model.
     */
     virtual bool ItemAdded(const wxDataViewItem& parent,
                            const wxDataViewItem& item) = 0;
 
     /**
         Called by owning model.

+
+        @return Always return @true from this function in derived classes.

     */
     virtual bool ItemChanged(const wxDataViewItem& item) = 0;
 
     /**
         Called by owning model.
     */
     virtual bool ItemChanged(const wxDataViewItem& item) = 0;
 
     /**
         Called by owning model.

+
+        @return Always return @true from this function in derived classes.

     */
     virtual bool ItemDeleted(const wxDataViewItem& parent,
                              const wxDataViewItem& item) = 0;
 
     /**
         Called by owning model.
     */
     virtual bool ItemDeleted(const wxDataViewItem& parent,
                              const wxDataViewItem& item) = 0;
 
     /**
         Called by owning model.

+
+        @return Always return @true from this function in derived classes.

     */
     virtual bool ItemsAdded(const wxDataViewItem& parent,
                             const wxDataViewItemArray& items);
 
     /**
         Called by owning model.
     */
     virtual bool ItemsAdded(const wxDataViewItem& parent,
                             const wxDataViewItemArray& items);
 
     /**
         Called by owning model.

+
+        @return Always return @true from this function in derived classes.

     */
     virtual bool ItemsChanged(const wxDataViewItemArray& items);
 
     /**
         Called by owning model.
     */
     virtual bool ItemsChanged(const wxDataViewItemArray& items);
 
     /**
         Called by owning model.

+
+        @return Always return @true from this function in derived classes.

     */
     virtual bool ItemsDeleted(const wxDataViewItem& parent,
                               const wxDataViewItemArray& items);
     */
     virtual bool ItemsDeleted(const wxDataViewItem& parent,
                               const wxDataViewItemArray& items);


@@ -1253,6 +1360,8 @@ public:
 
     /**
         Called by owning model.
 
     /**
         Called by owning model.

+
+        @return Always return @true from this function in derived classes.

     */
     virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col) = 0;
 };
     */
     virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col) = 0;
 };


@@ -1263,18 +1372,54 @@ public:
 */
 enum wxDataViewCellMode
 {
 */
 enum wxDataViewCellMode
 {

+    /**
+        The cell only displays information and cannot be manipulated or
+        otherwise interacted with in any way.
+
+        Note that this doesn't mean that the row being drawn can't be selected,
+        just that a particular element of it cannot be individually modified.
+     */

     wxDATAVIEW_CELL_INERT,
 
     /**
     wxDATAVIEW_CELL_INERT,
 
     /**

-        Indicates that the user can double click the cell and something will
-        happen (e.g. a window for editing a date will pop up).
+        Indicates that the cell can be @em activated by clicking it or using
+        keyboard.
+
+        Activating a cell is an alternative to showing inline editor when the
+        value can be edited in a simple way that doesn't warrant full editor
+        control. The most typical use of cell activation is toggling the
+        checkbox in wxDataViewToggleRenderer; others would be e.g. an embedded
+        volume slider or a five-star rating column.
+
+        The exact means of activating a cell are platform-dependent, but they
+        are usually similar to those used for inline editing of values.
+        Typically, a cell would be activated by Space or Enter keys or by left
+        mouse click.
+
+        @note Do not confuse this with item activation in wxDataViewCtrl
+              and the wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. That one is
+              used for activating the item (or, to put it differently, the
+              entire row) similarly to analogous messages in wxTreeCtrl and
+              wxListCtrl, and the effect differs (play a song, open a file
+              etc.). Cell activation, on the other hand, is all about
+              interacting with the individual cell.
+
+        @see wxDataViewCustomRenderer::ActivateCell()

     */
     wxDATAVIEW_CELL_ACTIVATABLE,
 
     /**
     */
     wxDATAVIEW_CELL_ACTIVATABLE,
 
     /**

-        Indicates that the user can edit the data in-place, i.e. an control
-        will show up after a slow click on the cell. This behaviour is best
-        known from changing the filename in most file managers etc.
+        Indicates that the user can edit the data in-place in an inline editor
+        control that will show up when the user wants to edit the cell.
+
+        A typical example of this behaviour is changing the filename in a file
+        managers.
+
+        Editing is typically triggered by slowly double-clicking the cell or by
+        a platform-dependent keyboard shortcut (F2 is typical on Windows, Space
+        and/or Enter is common elsewhere and supported on Windows too).
+
+        @see wxDataViewCustomRenderer::CreateEditorCtrl()

     */
     wxDATAVIEW_CELL_EDITABLE
 };
     */
     wxDATAVIEW_CELL_EDITABLE
 };


@@ -1633,20 +1778,72 @@ public:
     virtual ~wxDataViewCustomRenderer();
 
     /**
     virtual ~wxDataViewCustomRenderer();
 
     /**

-        Override this to react to double clicks or ENTER.
-        This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
+        Override this to react to cell @em activation. Activating a cell is an
+        alternative to showing inline editor when the value can be edited in a
+        simple way that doesn't warrant full editor control. The most typical
+        use of cell activation is toggling the checkbox in
+        wxDataViewToggleRenderer; others would be e.g. an embedded volume
+        slider or a five-star rating column.
+
+        The exact means of activating a cell are platform-dependent, but they
+        are usually similar to those used for inline editing of values.
+        Typically, a cell would be activated by Space or Enter keys or by left
+        mouse click.
+
+        This method will only be called if the cell has the
+        wxDATAVIEW_CELL_ACTIVATABLE mode.
+
+        @param cell
+            Coordinates of the activated cell's area.
+        @param model
+            The model to manipulate in response.
+        @param item
+            Activated item.
+        @param col
+            Activated column of @a item.
+        @param mouseEvent
+            If the activation was triggered by mouse click, contains the
+            corresponding event. Is @NULL otherwise (for keyboard activation).
+            Mouse coordinates are adjusted to be relative to the cell.
+
+        @since 2.9.3
+
+        @note Do not confuse this method with item activation in wxDataViewCtrl
+              and the wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. That one is
+              used for activating the item (or, to put it differently, the
+              entire row) similarly to analogous messages in wxTreeCtrl and
+              wxListCtrl, and the effect differs (play a song, open a file
+              etc.). Cell activation, on the other hand, is all about
+              interacting with the individual cell.
+
+        @see CreateEditorCtrl()

     */
     */

-    virtual bool Activate( const wxRect& cell,
-                           wxDataViewModel* model,
-                           const wxDataViewItem & item,
-                           unsigned int col );
+    virtual bool ActivateCell(const wxRect& cell,
+                              wxDataViewModel* model,
+                              const wxDataViewItem & item,
+                              unsigned int col,
+                              const wxMouseEvent *mouseEvent);

 
     /**
         Override this to create the actual editor control once editing
         is about to start.
 
 
     /**
         Override this to create the actual editor control once editing
         is about to start.
 

-        @a parent is the parent of the editor control, @a labelRect indicates the
-        position and size of the editor control and @a value is its initial value:
+        This method will only be called if the cell has the
+        wxDATAVIEW_CELL_EDITABLE mode. Editing is typically triggered by slowly
+        double-clicking the cell or by a platform-dependent keyboard shortcut
+        (F2 is typical on Windows, Space and/or Enter is common elsewhere and
+        supported on Windows too).
+
+        @param parent
+            The parent of the editor control.
+        @param labelRect
+            Indicates the position and size of the editor control. The control
+            should be created in place of the cell and @a labelRect should be
+            respected as much as possible.
+        @param value
+            Initial value of the editor.
+
+        An example:

         @code
         {
             long l = value;
         @code
         {
             long l = value;


@@ -1654,6 +1851,8 @@ public:
                         labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
         }
         @endcode
                         labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
         }
         @endcode

+
+        @see ActivateCell()

     */
     virtual wxWindow* CreateEditorCtrl(wxWindow* parent,
                                        wxRect labelRect,
     */
     virtual wxWindow* CreateEditorCtrl(wxWindow* parent,
                                        wxRect labelRect,


@@ -1996,7 +2195,7 @@ public:
         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.
     */

-    virtual void AppendColumn( wxDataViewColumn *column );
+    virtual bool AppendColumn( wxDataViewColumn *column );

 
     /**
         Appends a column to the control and additionally appends a
 
     /**
         Appends a column to the control and additionally appends a


@@ -2052,7 +2251,7 @@ public:
         Inserts a column to the control and additionally inserts a
         column to the store with the type string.
     */
         Inserts a column to the control and additionally inserts a
         column to the store with the type string.
     */

-    virtual void InsertColumn( unsigned int pos, wxDataViewColumn *column );
+    virtual bool InsertColumn( unsigned int pos, wxDataViewColumn *column );

 
     /**
         Inserts a column to the control and additionally inserts a
 
     /**
         Inserts a column to the control and additionally inserts a


@@ -2065,7 +2264,7 @@ public:
         Prepends a column to the control and additionally prepends a
         column to the store with the type string.
     */
         Prepends a column to the control and additionally prepends a
         column to the store with the type string.
     */

-    virtual void PrependColumn( wxDataViewColumn *column );
+    virtual bool PrependColumn( wxDataViewColumn *column );

 
     /**
         Prepends a column to the control and additionally prepends a
 
     /**
         Prepends a column to the control and additionally prepends a


@@ -2696,7 +2895,7 @@ public:
     @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
     @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
     @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
     @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}

-           Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
+           Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK event.

     @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
     @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
     @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
     @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}


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

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

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