]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/headercol.h
Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / headercol.h
index 906f32409d12b96ada3b4050af54f7848b892f81..60e0a4a3cc24a5b07849dc9639be46e6b73b155a 100644 (file)
@@ -3,15 +3,26 @@
 // Purpose:     interface of wxHeaderColumn
 // Author:      Vadim Zeitlin
 // 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.
+
+        @note On OS X, this style is only implemented in the Cocoa build on
+              OS X >= 10.5; it behaves identically to wxCOL_WIDTH_DEFAULT otherwise.
+     */
+    wxCOL_WIDTH_AUTOSIZE = -2
+};
 
 /**
     Bit flags used as wxHeaderColumn flags.
@@ -42,9 +53,18 @@ enum
 
     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. You may use wxHeaderCtrlSimple which uses
-    concrete wxHeaderColumnSimple if you don't already store the column
-    information somewhere.
+    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}
@@ -53,51 +73,154 @@ class wxHeaderColumn
 {
 public:
     /**
-        Set the text to display in the column header.
+        Get the text shown in the column header.
      */
-    virtual void SetTitle(const wxString& title) = 0;
+    virtual wxString GetTitle() const = 0;
 
     /**
-        Get the text shown in the column header.
+        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.
      */
-    virtual wxString GetTitle() const = 0;
+    virtual int GetMinWidth() const = 0;
 
     /**
-        Set the bitmap to be displayed in the column header.
+        Returns the current column alignment.
 
-        Notice that the bitmaps displayed in different columns of the same
-        control must all be of the same size.
+        @return
+            One of wxALIGN_CENTRE, wxALIGN_LEFT or wxALIGN_RIGHT.
      */
-    virtual void SetBitmap(const wxBitmap& bitmap) = 0;
+    virtual wxAlignment GetAlignment() const = 0;
+
 
     /**
-        Returns the bitmap in the header of the column, if any.
+        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 int GetFlags() const = 0;
+
+    /**
+        Return @true if the specified flag is currently set for this column.
+     */
+    bool HasFlag(int flag) const;
 
-        If the column has no associated bitmap, wxNullBitmap is returned.
+
+    /**
+        Return true if the column can be resized by the user.
+
+        Equivalent to HasFlag(wxCOL_RESIZABLE).
+     */
+    virtual bool IsResizeable() const;
+
+    /**
+        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.
     */
-    virtual wxBitmap GetBitmap() const = 0;
+    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) = 0;
+    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 = 0;
+    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.
 
-        This method can be used with resizeable columns (i.e. those for which
+        This method can be used with resizable columns (i.e. those for which
         wxCOL_RESIZABLE flag is set in GetFlags() or, alternatively,
         IsResizeable() returns @true) to prevent the user from making them
         narrower than the given width.
@@ -108,14 +231,6 @@ public:
      */
     virtual void SetMinWidth(int minWidth) = 0;
 
-    /**
-        Return the minimal column width.
-
-        @return
-            The value previously set by SetMinWidth() or 0 by default.
-     */
-    virtual int GetMinWidth() const = 0;
-
     /**
         Set the alignment of the column header.
 
@@ -129,14 +244,6 @@ public:
     */
     virtual void SetAlignment(wxAlignment align) = 0;
 
-    /**
-        Returns the current column alignment.
-
-        @return
-            One of wxALIGN_CENTRE, wxALIGN_LEFT or wxALIGN_RIGHT.
-     */
-    virtual wxAlignment GetAlignment() const = 0;
-
 
     /**
         Set the column flags.
@@ -189,39 +296,16 @@ public:
      */
     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 = 0;
-
-    /**
-        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
         the user.
 
-        By default, the columns are resizeable.
-
-        Equivalent to ChangeFlag(wxCOL_RESIZABLE, resizeable).
-     */
-    virtual void SetResizeable(bool resizeable);
-
-    /**
-        Return true if the column can be resized by the user.
+        By default, the columns are resizable.
 
-        Equivalent to HasFlag(wxCOL_RESIZABLE).
+        Equivalent to ChangeFlag(wxCOL_RESIZABLE, resizable).
      */
-    virtual bool IsResizeable() const;
+    virtual void SetResizeable(bool resizable);
 
     /**
         Allow clicking the column to sort the control contents by the field in
@@ -235,16 +319,6 @@ public:
      */
     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.
 
@@ -252,15 +326,6 @@ public:
      */
     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.
 
@@ -271,64 +336,27 @@ public:
      */
     virtual void SetHidden(bool hidden);
 
-    /**
-        Returns @true if the column is currently hidden.
-
-        This corresponds to wxCOL_HIDDEN flag which is off by default.
-     */
-    virtual bool IsHidden() const;
 
     /**
-        Returns @true if the column is currently shown.
+        Don't use this column for sorting.
 
-        This corresponds to the absence of wxCOL_HIDDEN flag.
+        This is the reverse of SetSortOrder() and is called to indicate that
+        this column is not used for sorting any longer.
      */
-    bool IsShown() const;
-
-
+    void UnsetAsSortKey();
 
     /**
         Sets this column as the sort key for the associated control.
 
-        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).
+        This function indicates that this column is currently used for sorting
+        the control and also sets the sorting direction. Notice that actual
+        sorting is only done in the control associated with the header, this
+        function doesn't do any sorting on its own.
 
         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 void SetAsSortKey(bool sort = true) = 0;
-
-    /**
-        Don't use this column for sorting.
-
-        This is equivalent to calling SetAsSortKey() with @false argument.
-     */
-    void UnsetAsSortKey();
-
-    /**
-        Returns @true if the column is currently used for sorting.
-
-        Notice that this function simply returns the value last passed to
-        SetAsSortKey() (or @false if SetAsSortKey() had never been called), it
-        is up to the associated control to use this information to actually
-        sort its contents.
-     */
-    virtual bool IsSortKey() const = 0;
-
-    /**
-        Sets the sort order for this column.
-
-        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.
+        SetSortOrder() can be only called for sortable columns.
 
         @param ascending
             If @true, sort in ascending order, otherwise in descending order.
@@ -345,16 +373,6 @@ public:
         @see SetSortOrder(), IsSortOrderAscending()
      */
     void ToggleSortOrder();
-
-    /**
-        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.
-
-        @see SetSortOrder()
-    */
-    virtual bool IsSortOrderAscending() const = 0;
 };
 
 /**
@@ -362,9 +380,9 @@ public:
 
     Simple container for the information about the column.
 
-    This is a concrete class implementing all base wxHeaderColumn 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.
+    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");
@@ -376,7 +394,7 @@ public:
     @library{wxcore}
     @category{ctrl}
  */
-class wxHeaderColumnSimple : public wxHeaderColumn
+class wxHeaderColumnSimple : public wxSettableHeaderColumn
 {
 public:
     //@{
@@ -392,7 +410,7 @@ public:
                          int flags = wxCOL_DEFAULT_FLAGS);
 
     wxHeaderColumnSimple(const wxBitmap &bitmap,
-                         int width = wxDVC_DEFAULT_WIDTH,
+                         int width = wxCOL_WIDTH_DEFAULT,
                          wxAlignment align = wxALIGN_CENTER,
                          int flags = wxCOL_DEFAULT_FLAGS);
     //@}
@@ -413,7 +431,6 @@ public:
     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;