// 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.
@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.
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.
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;
/**
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.
*/
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
*/
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.
*/
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.
*/
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.
*/
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;
/**
- 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 equivalent to calling SetAsSortKey() with @false argument.
*/
- bool IsShown() const;
+ void UnsetAsSortKey();
/**
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.
*/
- virtual void SetSortOrder(bool ascending);
+ virtual void SetSortOrder(bool ascending) = 0;
/**
Inverses the sort order.
@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;
+ //@}
+};
projects / wxWidgets.git / blobdiff