// 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.
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}
{
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.
*/
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.
*/
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.
*/
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
*/
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.
-
- 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.
@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;
};
/**
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");
@library{wxcore}
@category{ctrl}
*/
-class wxHeaderColumnSimple : public wxHeaderColumn
+class wxHeaderColumnSimple : public wxSettableHeaderColumn
{
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);
//@}
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