X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/56873923f39af96aac6bfc5776d2637b8c4623ca..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/headercol.h diff --git a/interface/wx/headercol.h b/interface/wx/headercol.h index 3aaee0d30d..60e0a4a3cc 100644 --- a/interface/wx/headercol.h +++ b/interface/wx/headercol.h @@ -3,15 +3,26 @@ // Purpose: interface of wxHeaderColumn // Author: Vadim Zeitlin // Created: 2008-12-01 -// RCS-ID: $Id$ // Copyright: (c) 2008 Vadim Zeitlin -// 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. @@ -38,79 +49,178 @@ enum @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} - - @see wxHeaderCtrl */ 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. - 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. @@ -119,15 +229,7 @@ public: 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. @@ -140,26 +242,7 @@ public: 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 +257,7 @@ public: 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. @@ -213,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; - - /** - 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. + By default, the columns are resizable. - Equivalent to ChangeFlag(wxCOL_RESIZABLE, resizeable). + Equivalent to ChangeFlag(wxCOL_RESIZABLE, resizable). */ - 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; + virtual void SetResizeable(bool resizable); /** Allow clicking the column to sort the control contents by the field in @@ -259,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. @@ -276,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. @@ -295,24 +336,32 @@ public: */ virtual void SetHidden(bool hidden); + /** - Returns @true if the column is currently hidden. + Don't use this column for sorting. - This corresponds to wxCOL_HIDDEN flag which is off by default. + This is the reverse of SetSortOrder() and is called to indicate that + this column is not used for sorting any longer. */ - virtual bool IsHidden() const; + void UnsetAsSortKey(); /** - Sets the sort order for this column. + Sets this column as the sort key for the associated control. - 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 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, + SetSortOrder() can be only called for sortable columns. @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. @@ -324,13 +373,67 @@ public: @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 wxSettableHeaderColumn +{ +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 = wxCOL_WIDTH_DEFAULT, + 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 bool IsSortKey() const; + virtual void SetSortOrder(bool ascending); + virtual bool IsSortOrderAscending() const; + + //@} +};