ceguilistheader.h

OGRE开发包的依赖包

/***********************************************************************
	filename: 	CEGUIListHeader.h
	created:	13/4/2004
	author:		Paul D Turner
	
	purpose:	Interface to base class for ListHeader widget
*************************************************************************/
/***************************************************************************
 *   Copyright (C) 2004 - 2006 Paul D Turner & The CEGUI Development Team
 *
 *   Permission is hereby granted, free of charge, to any person obtaining
 *   a copy of this software and associated documentation files (the
 *   "Software"), to deal in the Software without restriction, including
 *   without limitation the rights to use, copy, modify, merge, publish,
 *   distribute, sublicense, and/or sell copies of the Software, and to
 *   permit persons to whom the Software is furnished to do so, subject to
 *   the following conditions:
 *
 *   The above copyright notice and this permission notice shall be
 *   included in all copies or substantial portions of the Software.
 *
 *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 *   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 *   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 *   IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 *   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 *   OTHER DEALINGS IN THE SOFTWARE.
 ***************************************************************************/
#ifndef _CEGUIListHeader_h_
#define _CEGUIListHeader_h_

#include "CEGUIBase.h"
#include "CEGUIWindow.h"
#include "elements/CEGUIListHeaderSegment.h"
#include "elements/CEGUIListHeaderProperties.h"


#if defined(_MSC_VER)
#	pragma warning(push)
#	pragma warning(disable : 4251)
#endif


// Start of CEGUI namespace section
namespace CEGUI
{
/*!
\brief
	EventArgs class used for segment move (sequence changed) events.
*/
class CEGUIEXPORT HeaderSequenceEventArgs : public WindowEventArgs
{
public:
	HeaderSequenceEventArgs(Window* wnd, uint old_idx, uint new_idx) : WindowEventArgs(wnd), d_oldIdx(old_idx), d_newIdx(new_idx) {};

	uint d_oldIdx;		//!< The original column index of the segment that has moved.
	uint d_newIdx;		//!< The new column index of the segment that has moved.
};

/*!
\brief
    Base class for the multi column list header window renderer.
*/
class CEGUIEXPORT ListHeaderWindowRenderer : public WindowRenderer
{
public:
    /*!
    \brief
        Constructor
    */
    ListHeaderWindowRenderer(const String& name);

    /*!
    \brief
        Create and return a pointer to a new ListHeaderSegment based object.

    \param name
        String object holding the name that should be given to the new Window.

    \return
        Pointer to an ListHeaderSegment based object of whatever type is appropriate for
        this ListHeader.
    */
    virtual ListHeaderSegment*  createNewSegment(const String& name) const  = 0;

    /*!
    \brief
        Cleanup and destroy the given ListHeaderSegment that was created via the
        createNewSegment method.

    \param segment
        Pointer to a ListHeaderSegment based object to be destroyed.

    \return
        Nothing.
    */
    virtual void    destroyListSegment(ListHeaderSegment* segment) const = 0;
};


/*!
\brief
	Base class for the multi column list header widget.
*/
class CEGUIEXPORT ListHeader : public Window
{
public:
	static const String EventNamespace;				//!< Namespace for global events
    static const String WidgetTypeName;             //!< Window factory name


	/*************************************************************************
		Constants
	*************************************************************************/
	// Event names
	static const String EventSortColumnChanged;			//!< Event fired when the current sort column changes.
	static const String EventSortDirectionChanged;		//!< Event fired when the sort direction changes.
	static const String EventSegmentSized;				//!< Event fired when a segment has been sized by the user (e.window is the segment).
	static const String EventSegmentClicked;				//!< Event fired when a segment has been clicked by the user (e.window is the segment).
	static const String EventSplitterDoubleClicked;		//!< Event fired when a segment splitter has been double-clicked.  (e.window is the segment).
	static const String EventSegmentSequenceChanged;		//!< Event fired when the order of the segments has changed.  ('e' is a HeaderSequenceEventArgs&)
	static const String EventSegmentAdded;				//!< Event fired when a segment is added to the header.
	static const String EventSegmentRemoved;				//!< Event fired when a segment is removed from the header.
	static const String EventSortSettingChanged;			//!< Event fired when setting that controls user modification to sort configuration changes.
	static const String EventDragMoveSettingChanged;		//!< Event fired when setting that controls user drag & drop of segments changes.
	static const String EventDragSizeSettingChanged;		//!< Event fired when setting that controls user sizing of segments changes.
	static const String EventSegmentRenderOffsetChanged;	//!< Event fired when the rendering offset for the segments changes.

	// values
	static const float	ScrollSpeed;				//!< Speed to scroll at when dragging outside header.
	static const float	MinimumSegmentPixelWidth;	//!< Miniumum width of a segment in pixels.

    /*************************************************************************
        Child Widget name suffix constants
    *************************************************************************/
    static const char SegmentNameSuffix[];          //!< Widget name suffix for header segments.


	/*************************************************************************
		Accessor Methods
	*************************************************************************/
	/*!
	\brief
		Return the number of columns or segments attached to the header.

	\return
		uint value equal to the number of columns / segments currently in the header.
	*/
	uint	getColumnCount(void) const;

	
	/*!
	\brief
		Return the ListHeaderSegment object for the specified column

	\param column
		zero based column index of the ListHeaderSegment to be returned.

	\return
		ListHeaderSegment object at the requested index.

	\exception InvalidRequestException	thrown if column is out of range.
	*/
	ListHeaderSegment&	getSegmentFromColumn(uint column) const;


	/*!
	\brief
		Return the ListHeaderSegment object with the specified ID.

	\param id
		id code of the ListHeaderSegment to be returned.

	\return
		ListHeaderSegment object with the ID \a id.  If more than one segment has the same ID, only the first one will
		ever be returned.

	\exception	InvalidRequestException		thrown if no segment with the requested ID is attached.
	*/
	ListHeaderSegment&	getSegmentFromID(uint id) const;


	/*!
	\brief
		Return the ListHeaderSegment that is marked as being the 'sort key' segment.  There must be at least one segment
		to successfully call this method.

	\return
		ListHeaderSegment object which is the sort-key segment.

	\exception	InvalidRequestException		thrown if no segments are attached to the ListHeader.
	*/
	ListHeaderSegment&	getSortSegment(void) const;


	/*!
	\brief
		Return the zero based column index of the specified segment.

	\param segment
		ListHeaderSegment whos zero based index is to be returned.

	\return
		Zero based column index of the ListHeaderSegment \a segment.

	\exception	InvalidRequestException		thrown if \a segment is not attached to this ListHeader.
	*/
	uint	getColumnFromSegment(const ListHeaderSegment& segment) const;


	/*!
	\brief
		Return the zero based column index of the segment with the specified ID.

	\param id
		ID code of the segment whos column index is to be returned.

	\return
		Zero based column index of the first ListHeaderSegment whos ID matches \a id.

	\exception	InvalidRequestException		thrown if no attached segment has the requested ID.
	*/
	uint	getColumnFromID(uint id) const;


	/*!
	\brief
		Return the zero based index of the current sort column.  There must be at least one segment/column to successfully call this
		method.

	\return
		Zero based column index that is the current sort column.

	\exception	InvalidRequestException		thrown if there are no segments / columns in this ListHeader.
	*/
	uint	getSortColumn(void) const;


	/*!
	\brief
		Return the zero based column index of the segment with the specified text.

	\param text
		String object containing the text to be searched for.

	\return
		Zero based column index of the segment with the specified text.

	\exception InvalidRequestException	thrown if no attached segments have the requested text.
	*/
	uint	getColumnWithText(const String& text) const;


	/*!
	\brief
		Return the pixel offset to the given ListHeaderSegment.

	\param segment
		ListHeaderSegment object that the offset to is to be returned.

	\return
		The number of pixels up-to the begining of the ListHeaderSegment described by \a segment.

	\exception InvalidRequestException	thrown if \a segment is not attached to the ListHeader.
	*/
	float	getPixelOffsetToSegment(const ListHeaderSegment& segment) const;


	/*!
	\brief
		Return the pixel offset to the ListHeaderSegment at the given zero based column index.

	\param column
		Zero based column index of the ListHeaderSegment whos pixel offset it to be returned.

	\return
		The number of pixels up-to the begining of the ListHeaderSegment located at zero based column
		index \a column.

	\exception InvalidRequestException	thrown if \a column is out of range.
	*/
	float	getPixelOffsetToColumn(uint column) const;


	/*!
	\brief
		Return the total pixel width of all attached segments.

	\return
		Sum of the pixel widths of all attached ListHeaderSegment objects.
	*/
	float	getTotalSegmentsPixelExtent(void) const;


	/*!
	\brief
		Return the width of the specified column.

	\param column
		Zero based column index of the segment whose width is to be returned.

	\return
		UDim describing the width of the ListHeaderSegment at the zero based
        column index specified by \a column.

	\exception InvalidRequestException	thrown if \a column is out of range.
	*/
	UDim getColumnWidth(uint column) const;


	/*!
	\brief
		Return the currently set sort direction.

	\return
		One of the ListHeaderSegment::SortDirection enumerated values specifying the current sort direction.
	*/
	ListHeaderSegment::SortDirection	getSortDirection(void) const;


	/*!
	\brief
		Return whether user manipulation of the sort column & direction are enabled.

	\return
		true if the user may interactively modify the sort column and direction.  false if the user may not
		modify the sort column and direction (these can still be set programmatically).
	*/
	bool	isSortingEnabled(void) const;


	/*!
	\brief
		Return whether the user may size column segments.

	\return
		true if the user may interactively modify the width of column segments, false if they may not.
	*/
	bool	isColumnSizingEnabled(void) const;


	/*!
	\brief
		Return whether the user may modify the order of the segments.

	\return
		true if the user may interactively modify the order of the column segments, false if they may not.
	*/
	bool	isColumnDraggingEnabled(void) const;


	/*!
	\brief
		Return the current segment offset value.  This value is used to implement scrolling of the header segments within
		the ListHeader area.

	\return
		float value specifying the current segment offset value in whatever metrics system is active for the ListHeader.
	*/
	float	getSegmentOffset(void) const	{return d_segmentOffset;}


	/*************************************************************************
		Manipulator Methods
	*************************************************************************/
	/*!
	\brief
		Set whether user manipulation of the sort column and direction is enabled.

	\param setting
		- true to allow interactive user manipulation of the sort column and direction.
		- false to disallow interactive user manipulation of the sort column and direction.

	\return
		Nothing.
	*/
	void	setSortingEnabled(bool setting);


	/*!
	\brief
		Set the current sort direction.

	\param direction
		One of the ListHeaderSegment::SortDirection enumerated values indicating the sort direction to be used.

	\return
		Nothing.
	*/
	void	setSortDirection(ListHeaderSegment::SortDirection direction);


	/*!
	\brief
		Set the column segment to be used as the sort column.

	\param segment
		ListHeaderSegment object indicating the column to be sorted.

	\return
		Nothing.

	\exception InvalidRequestException	thrown if \a segment is not attached to this ListHeader.
	*/
	void	setSortSegment(const ListHeaderSegment& segment);


	/*!
	\brief
		Set the column to be used as the sort column.

	\param column
		Zero based column index indicating the column to be sorted.

	\return
		Nothing.

	\exception InvalidRequestException	thrown if \a column is out of range for this ListHeader.
	*/
	void	setSortColumn(uint column);


	/*!
	\brief
		Set the column to to be used for sorting via its ID code.

	\param id
		ID code of the column segment that is to be used as the sort column.

	\return
		Nothing.

	\exception InvalidRequestException	thrown if no segment with ID \a id is attached to the ListHeader.
	*/
	void	setSortColumnFromID(uint id);


	/*!
	\brief
		Set whether columns may be sized by the user.

	\param setting
		- true to indicate that the user may interactively size segments.
		- false to indicate that the user may not interactively size segments.

	\return
		Nothing.
	*/
	void	setColumnSizingEnabled(bool setting);


	/*!
	\brief
		Set whether columns may be reordered by the user via drag and drop.

	\param setting
		- true to indicate the user may change the order of the column segments via drag and drop.
		- false to indicate the user may not change the column segment order.

	\return
		Nothing.
	*/
	void	setColumnDraggingEnabled(bool setting);