ceguimulticolumnlist.h

OGRE开发包的依赖包

/***********************************************************************
	filename: 	CEGUIMultiColumnList.h
	created:	13/4/2004
	author:		Paul D Turner
	
	purpose:	Interface to base class for MultiColumnList 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 _CEGUIMultiColumnList_h_
#define _CEGUIMultiColumnList_h_

#include "CEGUIBase.h"
#include "CEGUIWindow.h"
#include "CEGUIListHeader.h"
#include "elements/CEGUIMultiColumnListProperties.h"


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


// Start of CEGUI namespace section
namespace CEGUI
{

/*!
\brief
	Simple grid index structure.
*/
struct CEGUIEXPORT MCLGridRef
{
	MCLGridRef(uint r, uint c) : row(r), column(c) {}

	uint	row;		//!< Zero based row index.
	uint	column;		//!< Zero based column index.

	// operators
	MCLGridRef& operator=(const MCLGridRef& rhs);
	bool operator<(const MCLGridRef& rhs) const;
	bool operator<=(const MCLGridRef& rhs) const;
	bool operator>(const MCLGridRef& rhs) const;
	bool operator>=(const MCLGridRef& rhs) const;
	bool operator==(const MCLGridRef& rhs) const;
	bool operator!=(const MCLGridRef& rhs) const;
};

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

    /*!
    \brief
        Return a Rect object describing, in un-clipped pixels, the window relative area
        that is to be used for rendering list items.

    \return
        Rect object describing the area of the Window to be used for rendering
        list box items.
    */
    virtual Rect    getListRenderArea(void) const = 0;
};

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

	/*************************************************************************
		Constants
	*************************************************************************/
	// Event names
	static const String EventSelectionModeChanged;		//!< Event fired when the selection mode for the list box changes.
	static const String EventNominatedSelectColumnChanged;//!< Event fired when the nominated select column changes.
	static const String EventNominatedSelectRowChanged;	//!< Event fired when the nominated select row changes.
	static const String EventVertScrollbarModeChanged;	//!< Event fired when the vertical scroll bar 'force' setting changes.
	static const String EventHorzScrollbarModeChanged;	//!< Event fired when the horizontal scroll bar 'force' setting changes.
	static const String EventSelectionChanged;			//!< Event fired when the current selection(s) within the list box changes.
	static const String EventListContentsChanged;			//!< Event fired when the contents of the list box changes.
	static const String EventSortColumnChanged;			//!< Event fired when the sort column changes.
	static const String EventSortDirectionChanged;		//!< Event fired when the sort direction changes.
	static const String EventListColumnSized;				//!< Event fired when the width of a column in the list changes.
	static const String EventListColumnMoved;				//!< Event fired when the column order changes.

    /*************************************************************************
        Child Widget name suffix constants
    *************************************************************************/
    static const String VertScrollbarNameSuffix;   //!< Widget name suffix for the vertical scrollbar component.
    static const String HorzScrollbarNameSuffix;   //!< Widget name suffix for the horizontal scrollbar component.
    static const String ListHeaderNameSuffix;      //!< Widget name suffix for the list header component.

	/*************************************************************************
		Enumerations
	*************************************************************************/
	/*!
	\brief
		Enumerated values for the selection modes possible with a Multi-column list
	*/
	enum SelectionMode
	{
		RowSingle,					// Any single row may be selected.  All items in the row are selected.
		RowMultiple,				// Multiple rows may be selected.  All items in the row are selected.
		CellSingle,					// Any single cell may be selected.
		CellMultiple,				// Multiple cells bay be selected.
		NominatedColumnSingle,		// Any single item in a nominated column may be selected.
		NominatedColumnMultiple,	// Multiple items in a nominated column may be selected.
		ColumnSingle,				// Any single column may be selected.  All items in the column are selected.
		ColumnMultiple,				// Multiple columns may be selected.  All items in the column are selected.
		NominatedRowSingle,			// Any single item in a nominated row may be selected.
		NominatedRowMultiple		// Multiple items in a nominated row may be selected.
	};


	/*************************************************************************
		Accessor Methods
	*************************************************************************/
	/*!
	\brief
		Return whether user manipulation of the sort column and 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	isUserSortControlEnabled(void) const;


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

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


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

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


	/*!
	\brief
		Return the number of columns in the multi-column list

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


	/*!
	\brief
		Return the number of rows in the multi-column list.

	\return
		uint value equal to the number of rows currently in the list.
	*/
	uint	getRowCount(void) const;


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

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

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

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

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

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

	\exception	InvalidRequestException		thrown if no attached column has the requested ID.
	*/
	uint	getColumnWithID(uint col_id) const;


	/*!
	\brief
		Return the zero based index of the column whos header text matches the specified text.

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

	\return
		Zero based column index of the column whos header has the specified text.

	\exception InvalidRequestException	thrown if no columns header has the requested text.
	*/
	uint	getColumnWithHeaderText(const String& text) const;


	/*!
	\brief
		Return the total width of all column headers.

	\return
		Sum total of all the column header widths as a UDim.
	*/
	UDim getTotalColumnHeadersWidth(void) const;


	/*!
	\brief
		Return the width of the specified column header (and therefore the column itself).

	\param col_idx
		Zero based column index of the column whos width is to be returned.

	\return
		Width of the column header at the zero based column index specified by \a col_idx, as a UDim

	\exception InvalidRequestException	thrown if \a column is out of range.
	*/
	UDim getColumnHeaderWidth(uint col_idx) 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 the ListHeaderSegment object for the specified column

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

	\return
		ListHeaderSegment object for the column at the requested index.

	\exception InvalidRequestException	thrown if \a col_idx is out of range.
	*/
	ListHeaderSegment&	getHeaderSegmentForColumn(uint col_idx) const;


	/*!
	\brief
		Return the zero based index of the Row that contains \a item.

	\param item
		Pointer to the ListboxItem that the row index is to returned for.

	\return
		Zero based index of the row that contains ListboxItem \a item.

	\exception InvalidRequestException	thrown if \a item is not attached to the list box.
	*/
	uint	getItemRowIndex(const ListboxItem* item) const;


	/*!
	\brief
		Return the current zero based index of the column that contains \a item.

	\param item
		Pointer to the ListboxItem that the column index is to returned for.

	\return
		Zero based index of the column that contains ListboxItem \a item.

	\exception InvalidRequestException	thrown if \a item is not attached to the list box.
	*/
	uint	getItemColumnIndex(const ListboxItem* item) const;


	/*!
	\brief
		Return the grid reference for \a item.

	\param item
		Pointer to the ListboxItem whos current grid reference is to be returned.

	\return
		MCLGridRef object describing the current grid reference of ListboxItem \a item.

	\exception InvalidRequestException	thrown if \a item is not attached to the list box.
	*/
	MCLGridRef	getItemGridReference(const ListboxItem* item) const;

	
	/*!
	\brief
		Return a pointer to the ListboxItem at the specified grid reference.

	\param grid_ref
		MCLGridRef object that describes the position of the ListboxItem to be returned.

	\return
		Pointer to the ListboxItem at grid reference \a grid_ref.

	\exception InvalidRequestException	thrown if \a grid_ref is invalid for this list box.
	*/
	ListboxItem*	getItemAtGridReference(const MCLGridRef& grid_ref) const;


	/*!
	\brief
		return whether ListboxItem \a item is attached to the column at index \a col_idx.

	\param item
		Pointer to the ListboxItem to look for.

	\param col_idx
		Zero based index of the column that is to be searched.

	\return
		- true if \a item is attached to list box column \a col_idx.
		- false if \a item is not attached to list box column \a col_idx.

	\exception InvalidRequestException	thrown if \a col_idx is out of range.
	*/
	bool	isListboxItemInColumn(const ListboxItem* item, uint col_idx) const;


	/*!
	\brief
		return whether ListboxItem \a item is attached to the row at index \a row_idx.

	\param item
		Pointer to the ListboxItem to look for.

	\param row_idx
		Zero based index of the row that is to be searched.

	\return
		- true if \a item is attached to list box row \a row_idx.
		- false if \a item is not attached to list box row \a row_idx.

	\exception InvalidRequestException	thrown if \a row_idx is out of range.
	*/
	bool	isListboxItemInRow(const ListboxItem* item, uint row_idx) const;


	/*!
	\brief
		return whether ListboxItem \a item is attached to the list box.

	\param item
		Pointer to the ListboxItem to look for.

	\return