widgets/MultiColumnList.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 "../Base.h"
#include "../Window.h"
#include "./ListHeader.h"

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


// Start of CEGUI namespace section
namespace CEGUI
{

struct CEGUIEXPORT MCLGridRef
{
        MCLGridRef(uint r, uint c) : row(r), column(c) {}

        uint    row;            
        uint    column;         

        // 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;
};

class CEGUIEXPORT MultiColumnListWindowRenderer : public WindowRenderer
{
public:
    MultiColumnListWindowRenderer(const String& name);

    virtual Rectf getListRenderArea(void) const = 0;
};

class CEGUIEXPORT MultiColumnList : public Window
{
public:
        static const String EventNamespace;                             
    static const String WidgetTypeName;             

        /*************************************************************************
                Constants
        *************************************************************************/
        // Event names
        static const String EventSelectionModeChanged;
        static const String EventNominatedSelectColumnChanged;
        static const String EventNominatedSelectRowChanged;
        static const String EventVertScrollbarModeChanged;
        static const String EventHorzScrollbarModeChanged;
        static const String EventSelectionChanged;
        static const String EventListContentsChanged;
        static const String EventSortColumnChanged;
        static const String EventSortDirectionChanged;
        static const String EventListColumnSized;
        static const String EventListColumnMoved;

    /*************************************************************************
        Child Widget name constants
    *************************************************************************/
    static const String VertScrollbarName;   
    static const String HorzScrollbarName;   
    static const String ListHeaderName;      

        /*************************************************************************
                Enumerations
        *************************************************************************/
        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
        *************************************************************************/
        bool    isUserSortControlEnabled(void) const;


        bool    isUserColumnSizingEnabled(void) const;


        bool    isUserColumnDraggingEnabled(void) const;


        uint    getColumnCount(void) const;


        uint    getRowCount(void) const;


        uint    getSortColumn(void) const;
        uint    getSortColumnID(void) const;

        uint    getColumnWithID(uint col_id) const;


        uint    getColumnWithHeaderText(const String& text) const;


        UDim getTotalColumnHeadersWidth(void) const;


        UDim getColumnHeaderWidth(uint col_idx) const;


        ListHeaderSegment::SortDirection        getSortDirection(void) const;


        ListHeaderSegment&      getHeaderSegmentForColumn(uint col_idx) const;


        uint    getItemRowIndex(const ListboxItem* item) const;


        uint    getItemColumnIndex(const ListboxItem* item) const;


        MCLGridRef      getItemGridReference(const ListboxItem* item) const;


        ListboxItem*    getItemAtGridReference(const MCLGridRef& grid_ref) const;


        bool    isListboxItemInColumn(const ListboxItem* item, uint col_idx) const;


        bool    isListboxItemInRow(const ListboxItem* item, uint row_idx) const;


        bool    isListboxItemInList(const ListboxItem* item) const;


        ListboxItem*    findColumnItemWithText(const String& text, uint col_idx, const ListboxItem* start_item) const;


        ListboxItem*    findRowItemWithText(const String& text, uint row_idx, const ListboxItem* start_item) const;


        ListboxItem*    findListItemWithText(const String& text, const ListboxItem* start_item) const;


        ListboxItem*    getFirstSelectedItem(void) const;


        ListboxItem*    getNextSelected(const ListboxItem* start_item) const;


        uint    getSelectedCount(void) const;


        bool    isItemSelected(const MCLGridRef& grid_ref) const;


        uint    getNominatedSelectionColumnID(void) const;


        uint    getNominatedSelectionColumn(void) const;


        uint    getNominatedSelectionRow(void) const;


        MultiColumnList::SelectionMode  getSelectionMode(void) const;


        bool    isVertScrollbarAlwaysShown(void) const;


        bool    isHorzScrollbarAlwaysShown(void) const;


        uint    getColumnID(uint col_idx) const;


        uint    getRowID(uint row_idx) const;


        uint    getRowWithID(uint row_id) const;


    Rectf getListRenderArea(void) const;


    Scrollbar* getVertScrollbar() const;

    Scrollbar* getHorzScrollbar() const;

    ListHeader* getListHeader() const;

    float   getTotalRowsHeight(void) const;

    float   getWidestColumnItemWidth(uint col_idx) const;

    float   getHighestRowItemHeight(uint row_idx) const;

    bool getAutoSizeColumnUsesHeader() const;

        /*************************************************************************
                Manipulator Methods
        *************************************************************************/
        virtual void    initialiseComponents(void);


        void    resetList(void);


        void    addColumn(const String& text, uint col_id, const UDim& width);
        void    addColumn(const String& value);

        void    insertColumn(const String& text, uint col_id, const UDim& width, uint position);


        void    removeColumn(uint col_idx);


        void    removeColumnWithID(uint col_id);


        void    moveColumn(uint col_idx, uint position);


        void    moveColumnWithID(uint col_id, uint position);


        uint    addRow(uint row_id = 0);


        uint    addRow(ListboxItem* item, uint col_id, uint row_id = 0);


        uint    insertRow(uint row_idx, uint row_id = 0);


        uint    insertRow(ListboxItem* item, uint col_id, uint row_idx, uint row_id = 0);


        void    removeRow(uint row_idx);


        void    setItem(ListboxItem* item, const MCLGridRef& position);


        void    setItem(ListboxItem* item, uint col_id, uint row_idx);


        void    setSelectionMode(MultiColumnList::SelectionMode sel_mode);


        void    setNominatedSelectionColumnID(uint col_id);


        void    setNominatedSelectionColumn(uint col_idx);


        void    setNominatedSelectionRow(uint row_idx);


        void    setSortDirection(ListHeaderSegment::SortDirection direction);


        void    setSortColumn(uint col_idx);


        void    setSortColumnByID(uint col_id);


        void    setShowVertScrollbar(bool setting);


        void    setShowHorzScrollbar(bool setting);


        void    clearAllSelections(void);


        void    setItemSelectState(ListboxItem* item, bool state);


        void    setItemSelectState(const MCLGridRef& grid_ref, bool state);


        void    handleUpdatedItemData(void);


        void    setColumnHeaderWidth(uint col_idx, const UDim& width);


        void    setUserSortControlEnabled(bool setting);


        void    setUserColumnSizingEnabled(bool setting);


        void    setUserColumnDraggingEnabled(bool setting);


        void    autoSizeColumnHeader(uint col_idx);


        void    setRowID(uint row_idx, uint row_id);

    void ensureItemIsVisible(const ListboxItem* item);

    void ensureItemIsVisible(const MCLGridRef& grid_ref);

    void ensureItemRowIsVisible(const ListboxItem* item);

    void ensureItemColumnIsVisible(const ListboxItem* item);

    void ensureRowIsVisible(uint row_idx);

    void ensureColumnIsVisible(uint column_idx);

    void setAutoSizeColumnUsesHeader(bool include_header);


        /*************************************************************************
                Construction and Destruction
        *************************************************************************/
        MultiColumnList(const String& type, const String& name);


        virtual ~MultiColumnList(void);


protected:
        /*************************************************************************
                Implementation Functions (abstract interface)
        *************************************************************************/
        //virtual       Rect    getListRenderArea_impl(void) const              = 0;


        /*************************************************************************
                Implementation Functions
        *************************************************************************/
        void    configureScrollbars(void);


        bool    selectRange(const MCLGridRef& start, const MCLGridRef& end);


        bool    clearAllSelections_impl(void);


        ListboxItem*    getItemAtPoint(const Vector2f& pt) const;


        bool    setItemSelectState_impl(const MCLGridRef grid_ref, bool state);


        void    setSelectForItemsInRow(uint row_idx, bool state);


        void    setSelectForItemsInColumn(uint col_idx, bool state);


        void    moveColumn_impl(uint col_idx, uint position);


        bool    resetList_impl(void);

    // overrides function in base class.
    virtual bool validateWindowRenderer(const WindowRenderer* renderer) const;

    // overrides function in base class.
    int writePropertiesXML(XMLSerializer& xml_stream) const;

    void resortList();

        /*************************************************************************
                New event handlers for multi column list
        *************************************************************************/
        virtual void    onSelectionModeChanged(WindowEventArgs& e);


        virtual void    onNominatedSelectColumnChanged(WindowEventArgs& e);


        virtual void    onNominatedSelectRowChanged(WindowEventArgs& e);


        virtual void    onVertScrollbarModeChanged(WindowEventArgs& e);


        virtual void    onHorzScrollbarModeChanged(WindowEventArgs& e);


        virtual void    onSelectionChanged(WindowEventArgs& e);


        virtual void    onListContentsChanged(WindowEventArgs& e);


        virtual void    onSortColumnChanged(WindowEventArgs& e);


        virtual void    onSortDirectionChanged(WindowEventArgs& e);


        virtual void    onListColumnSized(WindowEventArgs& e);


        virtual void    onListColumnMoved(WindowEventArgs& e);


        /*************************************************************************
                Overridden Event handlers
        *************************************************************************/
        virtual void    onFontChanged(WindowEventArgs& e);
        virtual void    onSized(ElementEventArgs& e);
        virtual void    onMouseButtonDown(MouseEventArgs& e);
        virtual void    onMouseWheel(MouseEventArgs& e);


        /*************************************************************************
                Handlers for subscribed events
        *************************************************************************/
        bool    handleHeaderScroll(const EventArgs& e);
        bool    handleHeaderSegMove(const EventArgs& e);
        bool    handleColumnSizeChange(const EventArgs& e);
        bool    handleHorzScrollbar(const EventArgs& e);
        bool    handleVertScrollbar(const EventArgs& e);
        bool    handleSortColumnChange(const EventArgs& e);
        bool    handleSortDirectionChange(const EventArgs& e);
        bool    handleHeaderSegDblClick(const EventArgs& e);

        struct ListRow
        {
                typedef std::vector<ListboxItem*
            CEGUI_VECTOR_ALLOC(ListboxItem*)> RowItems;
                RowItems        d_items;
                uint            d_sortColumn;
                uint            d_rowID;

                // operators
                ListboxItem* const& operator[](uint idx) const  {return d_items[idx];}
                ListboxItem*&   operator[](uint idx) {return d_items[idx];}
                bool    operator<(const ListRow& rhs) const;
                bool    operator>(const ListRow& rhs) const;
        };


        static bool pred_descend(const ListRow& a, const ListRow& b);


        /*************************************************************************
                Implementation Data
        *************************************************************************/
        // scrollbar settings.
        bool    d_forceVertScroll;              
        bool    d_forceHorzScroll;              

        // selection abilities.
        SelectionMode   d_selectMode;   
        uint    d_nominatedSelectCol;   
        uint    d_nominatedSelectRow;   
        bool    d_multiSelect;                  
        bool    d_fullRowSelect;                
        bool    d_fullColSelect;                
        bool    d_useNominatedRow;              
        bool    d_useNominatedCol;              
        ListboxItem*    d_lastSelected; 

    uint    d_columnCount;          

        // storage of items in the list box.
        typedef std::vector<ListRow
        CEGUI_VECTOR_ALLOC(ListRow)> ListItemGrid;
        ListItemGrid    d_grid;                 

    bool d_autoSizeColumnUsesHeader;

    friend class MultiColumnListWindowRenderer;


private:
        /*************************************************************************
                Private methods
        *************************************************************************/
        void    addMultiColumnListProperties(void);
};


template<>
class PropertyHelper<MultiColumnList::SelectionMode>
{
public:
    typedef MultiColumnList::SelectionMode return_type;
    typedef return_type safe_method_return_type;
    typedef MultiColumnList::SelectionMode pass_type;
    typedef String string_return_type;

    static const String& getDataTypeName()
    {
        static String type("SelectionMode");

        return type;
    }

    static return_type fromString(const String& str)
    {
        MultiColumnList::SelectionMode mode;

        if (str == "RowMultiple")
        {
            mode = MultiColumnList::RowMultiple;
        }
        else if (str == "ColumnSingle")
        {
            mode = MultiColumnList::ColumnSingle;
        }
        else if (str == "ColumnMultiple")
        {
            mode = MultiColumnList::ColumnMultiple;
        }
        else if (str == "CellSingle")
        {
            mode = MultiColumnList::CellSingle;
        }
        else if (str == "CellMultiple")
        {
            mode = MultiColumnList::CellMultiple;
        }
        else if (str == "NominatedColumnSingle")
        {
            mode = MultiColumnList::NominatedColumnSingle;
        }
        else if (str == "NominatedColumnMultiple")
        {
            mode = MultiColumnList::NominatedColumnMultiple;
        }
        else if (str == "NominatedRowSingle")
        {
            mode = MultiColumnList::NominatedRowSingle;
        }
        else if (str == "NominatedRowMultiple")
        {
            mode = MultiColumnList::NominatedRowMultiple;
        }
        else
        {
            mode = MultiColumnList::RowSingle;
        }
        return mode;
    }

    static string_return_type toString(pass_type val)
    {
        switch(val)
        {
        case MultiColumnList::RowMultiple:
            return String("RowMultiple");
            break;

        case MultiColumnList::ColumnSingle:
            return String("ColumnSingle");
            break;

        case MultiColumnList::ColumnMultiple:
            return String("ColumnMultiple");
            break;

        case MultiColumnList::CellSingle:
            return String("CellSingle");
            break;

        case MultiColumnList::CellMultiple:
            return String("CellMultiple");
            break;

        case MultiColumnList::NominatedColumnSingle:
            return String("NominatedColumnSingle");
            break;

        case MultiColumnList::NominatedColumnMultiple:
            return String("NominatedColumnMultiple");
            break;

        case MultiColumnList::NominatedRowSingle:
            return String("NominatedRowSingle");
            break;

        case MultiColumnList::NominatedRowMultiple:
            return String("NominatedRowMultiple");
            break;

        default:
            return String("RowSingle");
            break;
        }
    }
};


} // End of  CEGUI namespace section

#if defined(_MSC_VER)
#       pragma warning(pop)
#endif

#endif  // end of guard _CEGUIMultiColumnList_h_