Correct wxID_SEPARATOR description in menu documentation.

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

diff --git a/interface/wx/headercol.h b/interface/wx/headercol.h
index 3aaee0d30d8f7d03b5f72c1f21cb04340f93f5ed..e0a65b9e62815faf7d109eb1813fdd9ac6af6e5d 100644 (file)
--- a/interface/wx/headercol.h
+++ b/interface/wx/headercol.h
@@ -5,13 +5,20 @@
 // Created:     2008-12-01
 // RCS-ID:      $Id$
 // Copyright:   (c) 2008 Vadim Zeitlin <vadim@wxwidgets.org>
 // Created:     2008-12-01
 // RCS-ID:      $Id$
 // Copyright:   (c) 2008 Vadim Zeitlin <vadim@wxwidgets.org>

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**

-    Special value used for column width meaning unspecified or default.
+    Column width special values.

  */
  */

-enum { wxCOL_WIDTH_DEFAULT = -1 };
+enum
+{
+    /// Special value used for column width meaning unspecified or default.
+    wxCOL_WIDTH_DEFAULT = -1,
+
+    /// Size the column automatically to fit all values.
+    wxCOL_WIDTH_AUTOSIZE = -2
+};

 
 /**
     Bit flags used as wxHeaderColumn flags.
 
 /**
     Bit flags used as wxHeaderColumn flags.


@@ -38,74 +45,173 @@ enum
     @class wxHeaderColumn
 
     Represents a column header in controls displaying tabular data such as
     @class wxHeaderColumn
 
     Represents a column header in controls displaying tabular data such as

-    wxHeaderCtrl, wxDataViewCtrl or wxGrid.
+    wxDataViewCtrl or wxGrid.
+
+    Notice that this is an abstract base class which is implemented (usually
+    using the information stored in the associated control) by the different
+    controls using wxHeaderCtrl. As the control only needs to retrieve the
+    information about the column, this class defines only the methods for
+    accessing the various column properties but not for changing them as the
+    setters might not be needed at all, e.g. if the column attributes can only
+    be changed via the methods of the main associated control (this is the case
+    for wxGrid for example). If you do want to allow changing them directly
+    using the column itself, you should inherit from wxSettableHeaderColumn
+    instead of this class.
+
+    Finally, if you don't already store the column information at all anywhere,
+    you should use the concrete wxHeaderColumnSimple class and
+    wxHeaderCtrlSimple.

 
     @library{wxcore}
     @category{ctrl}
 
     @library{wxcore}
     @category{ctrl}

-
-    @see wxHeaderCtrl

  */
 class wxHeaderColumn
 {
 public:
  */
 class wxHeaderColumn
 {
 public:

-    //@{

     /**
     /**

-        Constructor for a column header.
+        Get the text shown in the column header.
+     */
+    virtual wxString GetTitle() const = 0;

 
 

-        The first constructor creates a header showing the given text @a title
-        while the second one creates one showing the specified @a bitmap image.
+    /**
+        Returns the bitmap in the header of the column, if any.
+
+        If the column has no associated bitmap, wxNullBitmap should be returned.
+    */
+    virtual wxBitmap GetBitmap() const = 0;
+
+    /**
+        Returns the current width of the column.
+
+        @return
+            Width of the column in pixels, never wxCOL_WIDTH_DEFAULT or
+            wxCOL_WIDTH_AUTOSIZE.
+    */
+    virtual int GetWidth() const = 0;
+
+    /**
+        Return the minimal column width.
+
+        @return
+            The minimal width such that the user can't resize the column to
+            lesser size (notice that it is still possible to set the column
+            width to smaller value from the program code). Return 0 from here
+            to allow resizing the column to arbitrarily small size.

      */
      */

-    wxHeaderColumn(const wxString& title,
-                   int width = wxCOL_WIDTH_DEFAULT,
-                   wxAlignment align = wxALIGN_NOT,
-                   int flags = wxCOL_DEFAULT_FLAGS);
-    wxHeaderColumn(const wxBitmap &bitmap,
-                   int width = wxDVC_DEFAULT_WIDTH,
-                   wxAlignment align = wxALIGN_CENTER,
-                   int flags = wxCOL_DEFAULT_FLAGS);
-    //@}
+    virtual int GetMinWidth() const = 0;

 
     /**
 
     /**

-        Set the text to display in the column header.
+        Returns the current column alignment.
+
+        @return
+            One of wxALIGN_CENTRE, wxALIGN_LEFT or wxALIGN_RIGHT.

      */
      */

-    virtual void SetTitle(const wxString& title);
+    virtual wxAlignment GetAlignment() const = 0;
+

 
     /**
 
     /**

-        Get the text shown in the column header.
+        Get the column flags.
+
+        This method retrieves all the flags at once, you can also use HasFlag()
+        to test for any individual flag or IsResizeable(), IsSortable(),
+        IsReorderable() and IsHidden() to test for particular flags.

      */
      */

-    virtual wxString GetTitle() const;
+    virtual int GetFlags() const = 0;

 
     /**
 
     /**

-        Set the bitmap to be displayed in the column header.
+        Return @true if the specified flag is currently set for this column.
+     */
+    bool HasFlag(int flag) const;

 
 

-        Notice that the bitmaps displayed in different columns of the same
-        control must all be of the same size.
+
+    /**
+        Return true if the column can be resized by the user.
+
+        Equivalent to HasFlag(wxCOL_RESIZABLE).

      */
      */

-    virtual void SetBitmap(const wxBitmap& bitmap);
+    virtual bool IsResizeable() const;

 
     /**
 
     /**

-        Returns the bitmap in the header of the column, if any.
+        Returns @true if the column can be clicked by user to sort the control
+        contents by the field in this column.

 
 

-        If the column has no associated bitmap, wxNullBitmap is returned.
+        This corresponds to wxCOL_SORTABLE flag which is off by default.

     */
     */

-    virtual wxBitmap GetBitmap() const;                                   \
+    virtual bool IsSortable() const;

 
     /**
 
     /**

-        Set the column width.
+        Returns @true if the column can be dragged by user to change its order.

 
 

-        @param width
-            The column width in pixels or the special wxCOL_WIDTH_DEFAULT value
-            meaning to use default width.
+        This corresponds to wxCOL_REORDERABLE flag which is on by default.
+    */
+    virtual bool IsReorderable() const;
+
+    /**
+        Returns @true if the column is currently hidden.
+
+        This corresponds to wxCOL_HIDDEN flag which is off by default.

      */
      */

-    virtual void SetWidth(int width);
+    virtual bool IsHidden() const;

 
     /**
 
     /**

-        Returns the current width of the column.
+        Returns @true if the column is currently shown.

 
 

-        @return
-            Width of the column in pixels, never wxCOL_WIDTH_DEFAULT.
+        This corresponds to the absence of wxCOL_HIDDEN flag.
+     */
+    bool IsShown() const;
+
+
+    /**
+        Returns @true if the column is currently used for sorting.
+     */
+    virtual bool IsSortKey() const = 0;
+
+    /**
+        Returns @true, if the sort order is ascending.
+
+        Notice that it only makes sense to call this function if the column is
+        used for sorting at all, i.e. if IsSortKey() returns @true.

     */
     */

-    virtual int GetWidth() const;
+    virtual bool IsSortOrderAscending() const = 0;
+};
+
+/**
+    @class wxSettableHeaderColumn
+
+    Adds methods to set the column attributes to wxHeaderColumn.
+
+    This class adds setters for the column attributes defined by
+    wxHeaderColumn. It is still an abstract base class and needs to be
+    implemented before using it with wxHeaderCtrl.
+
+    @library{wxcore}
+    @category{ctrl}
+ */
+class wxSettableHeaderColumn : public wxHeaderColumn
+{
+public:
+    /**
+        Set the text to display in the column header.
+     */
+    virtual void SetTitle(const wxString& title) = 0;
+
+    /**
+        Set the bitmap to be displayed in the column header.
+
+        Notice that the bitmaps displayed in different columns of the same
+        control must all be of the same size.
+     */
+    virtual void SetBitmap(const wxBitmap& bitmap) = 0;
+
+    /**
+        Set the column width.
+
+        @param width
+            The column width in pixels or the special wxCOL_WIDTH_DEFAULT
+            (meaning to use default width) or wxCOL_WIDTH_AUTOSIZE (size to
+            fit the content) value.
+     */
+    virtual void SetWidth(int width) = 0;

 
     /**
         Set the minimal column width.
 
     /**
         Set the minimal column width.


@@ -119,15 +225,7 @@ public:
             The minimal column width in pixels, may be 0 to remove any
             previously set restrictions.
      */
             The minimal column width in pixels, may be 0 to remove any
             previously set restrictions.
      */

-    virtual void SetMinWidth(int minWidth);
-
-    /**
-        Return the minimal column width.
-
-        @return
-            The value previously set by SetMinWidth() or 0 by default.
-     */
-    virtual int GetMinWidth() const;
+    virtual void SetMinWidth(int minWidth) = 0;

 
     /**
         Set the alignment of the column header.
 
     /**
         Set the alignment of the column header.


@@ -140,26 +238,7 @@ public:
             wxALIGN_CENTRE for consistency (but notice that GetAlignment()
             never returns it).
     */
             wxALIGN_CENTRE for consistency (but notice that GetAlignment()
             never returns it).
     */

-    virtual void SetAlignment(wxAlignment align);
-
-    /**
-        Returns the current column alignment.
-
-        @return
-            One of wxALIGN_CENTRE, wxALIGN_LEFT or wxALIGN_RIGHT.
-     */
-    virtual wxAlignment GetAlignment() const;
-
-
-    // not documented because I'm not sure if it should be in the public API at
-    // all
-#if 0
-    // arbitrary client data associated with the column (currently only
-    // implemented in MSW because it is used in MSW wxDataViewCtrl
-    // implementation)
-    virtual void SetClientData(wxUIntPtr data);
-    virtual wxUIntPtr GetClientData() const;
-#endif
+    virtual void SetAlignment(wxAlignment align) = 0;

 
 
     /**
 
 
     /**


@@ -174,7 +253,7 @@ public:
             Combination of wxCOL_RESIZABLE, wxCOL_SORTABLE, wxCOL_REORDERABLE
             and wxCOL_HIDDEN bit flags.
      */
             Combination of wxCOL_RESIZABLE, wxCOL_SORTABLE, wxCOL_REORDERABLE
             and wxCOL_HIDDEN bit flags.
      */

-    virtual void SetFlags(int flags);
+    virtual void SetFlags(int flags) = 0;

 
     /**
         Set or clear the given flag.
 
     /**
         Set or clear the given flag.


@@ -213,22 +292,6 @@ public:
      */
     void ToggleFlag(int flag);
 
      */
     void ToggleFlag(int flag);
 

-    /**
-        Get the column flags.
-
-        This method retrieves all the flags at once, you can also use HasFlag()
-        to test for any individual flag or IsResizeable(), IsSortable(),
-        IsReorderable() and IsHidden() to test for particular flags.
-
-        @see SetFlags()
-     */
-    virtual int GetFlags() const;
-
-    /**
-        Return @true if the specified flag is currently set for this column.
-     */
-    bool HasFlag(int flag) const;
-

 
     /**
         Call this to enable or disable interactive resizing of the column by
 
     /**
         Call this to enable or disable interactive resizing of the column by


@@ -240,13 +303,6 @@ public:
      */
     virtual void SetResizeable(bool resizeable);
 
      */
     virtual void SetResizeable(bool resizeable);
 

-    /**
-        Return true if the column can be resized by the user.
-
-        Equivalent to HasFlag(wxCOL_RESIZABLE).
-     */
-    virtual bool IsResizeable() const;
-

     /**
         Allow clicking the column to sort the control contents by the field in
         this column.
     /**
         Allow clicking the column to sort the control contents by the field in
         this column.


@@ -259,16 +315,6 @@ public:
      */
     virtual void SetSortable(bool sortable);
 
      */
     virtual void SetSortable(bool sortable);
 

-    /**
-        Returns @true if the column can be clicked by user to sort the control
-        contents by the field in this column.
-
-        This corresponds to wxCOL_SORTABLE flag which is off by default.
-
-        @see SetSortable()
-    */
-    virtual bool IsSortable() const;
-

     /**
         Allow changing the column order by dragging it.
 
     /**
         Allow changing the column order by dragging it.
 


@@ -276,15 +322,6 @@ public:
      */
     virtual void SetReorderable(bool reorderable);
 
      */
     virtual void SetReorderable(bool reorderable);
 

-    /**
-        Returns @true if the column can be dragged by user to change its order.
-
-        This corresponds to wxCOL_REORDERABLE flag which is on by default.
-
-        @see SetReorderable()
-    */
-    virtual bool IsReorderable() const;
-

     /**
         Hide or show the column.
 
     /**
         Hide or show the column.
 


@@ -295,24 +332,44 @@ public:
      */
     virtual void SetHidden(bool hidden);
 
      */
     virtual void SetHidden(bool hidden);
 

+

     /**
     /**

-        Returns @true if the column is currently hidden.
+        Sets this column as the sort key for the associated control.

 
 

-        This corresponds to wxCOL_HIDDEN flag which is off by default.
+        Calling this function with @true argument means that this column is
+        currently used for sorting the control contents and so should typically
+        display an arrow indicating it (the direction of the arrow depends on
+        IsSortOrderAscending() return value).
+
+        Don't confuse this function with SetSortable() which should be used to
+        indicate that the column @em may be used for sorting while this one is
+        used to indicate that it currently @em is used for sorting. Of course,
+        SetAsSortKey() can be only called for sortable columns.
+
+        @param sort
+            Sort (default) or don't sort the control contents by this column.

      */
      */

-    virtual bool IsHidden() const;
+    virtual void SetAsSortKey(bool sort = true) = 0;
+
+    /**
+        Don't use this column for sorting.
+
+        This is equivalent to calling SetAsSortKey() with @false argument.
+     */
+    void UnsetAsSortKey();

 
     /**
         Sets the sort order for this column.
 
 
     /**
         Sets the sort order for this column.
 

-        This only makes sense for sortable columns and is only taken into
-        account by the control in which this column is inserted, this function
-        just stores the sort order in the wxHeaderColumn object.
+        This only makes sense for sortable columns which are currently used as
+        sort key, i.e. for which IsSortKey() returns @true and is only taken
+        into account by the control in which this column is inserted, this
+        function just stores the sort order in the wxHeaderColumn object.

 
         @param ascending
             If @true, sort in ascending order, otherwise in descending order.
      */
 
         @param ascending
             If @true, sort in ascending order, otherwise in descending order.
      */

-    virtual void SetSortOrder(bool ascending);
+    virtual void SetSortOrder(bool ascending) = 0;

 
     /**
         Inverses the sort order.
 
     /**
         Inverses the sort order.


@@ -324,13 +381,68 @@ public:
         @see SetSortOrder(), IsSortOrderAscending()
      */
     void ToggleSortOrder();
         @see SetSortOrder(), IsSortOrderAscending()
      */
     void ToggleSortOrder();

+};
+
+/**
+    @class wxHeaderColumnSimple
+
+    Simple container for the information about the column.

 
 

+    This is a concrete class implementing all wxSettableHeaderColumn class
+    methods in a trivial way, i.e. by just storing the information in the
+    object itself. It is used by and with wxHeaderCtrlSimple, e.g.
+    @code
+        wxHeaderCtrlSimple * header = new wxHeaderCtrlSimple(...);
+        wxHeaderColumnSimple col("Title");
+        col.SetWidth(100);
+        col.SetSortable(100);
+        header->AppendColumn(col);
+    @endcode
+
+    @library{wxcore}
+    @category{ctrl}
+ */
+class wxHeaderColumnSimple : public wxHeaderColumn
+{
+public:
+    //@{

     /**
     /**

-        Returns @true, if the sort order is ascending.
+        Constructor for a column header.

 
 

-        @see SetSortOrder()
-    */
-    virtual bool IsSortOrderAscending() const;
-};
+        The first constructor creates a header showing the given text @a title
+        while the second one creates one showing the specified @a bitmap image.
+     */
+    wxHeaderColumnSimple(const wxString& title,
+                         int width = wxCOL_WIDTH_DEFAULT,
+                         wxAlignment align = wxALIGN_NOT,
+                         int flags = wxCOL_DEFAULT_FLAGS);
+
+    wxHeaderColumnSimple(const wxBitmap &bitmap,
+                         int width = wxDVC_DEFAULT_WIDTH,
+                         wxAlignment align = wxALIGN_CENTER,
+                         int flags = wxCOL_DEFAULT_FLAGS);
+    //@}
+
+    //@{

 
 

+    /// Trivial implementations of the base class pure virtual functions.

 
 

+    virtual void SetTitle(const wxString& title);
+    virtual wxString GetTitle() const;
+    virtual void SetBitmap(const wxBitmap& bitmap);
+    virtual wxBitmap GetBitmap() const;
+    virtual void SetWidth(int width);
+    virtual int GetWidth() const;
+    virtual void SetMinWidth(int minWidth);
+    virtual int GetMinWidth() const;
+    virtual void SetAlignment(wxAlignment align);
+    virtual wxAlignment GetAlignment() const;
+    virtual void SetFlags(int flags);
+    virtual int GetFlags() const;
+    virtual void SetAsSortKey(bool sort = true);
+    virtual bool IsSortKey() const;
+    virtual void SetSortOrder(bool ascending);
+    virtual bool IsSortOrderAscending() const;
+
+    //@}
+};