widgets/Listbox.h

/***********************************************************************
        created:        13/4/2004
        author:         Paul D Turner

        purpose:        Interface to base class for Listbox 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 _CEGUIListbox_h_
#define _CEGUIListbox_h_

#include "../Base.h"
#include "../Window.h"
#include <vector>


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


// Start of CEGUI namespace section
namespace CEGUI
{

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

    virtual Rectf getListRenderArea(void) const = 0;

    virtual void resizeListToContent(bool fit_width,
                                     bool fit_height) const = 0;
};

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

        /*************************************************************************
                Constants
        *************************************************************************/
        // event names
        static const String EventListContentsChanged;
        static const String EventSelectionChanged;
        static const String EventSortModeChanged;
        static const String EventMultiselectModeChanged;
        static const String EventVertScrollbarModeChanged;
        static const String EventHorzScrollbarModeChanged;

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

        /*************************************************************************
                Accessor Methods
        *************************************************************************/
        size_t  getItemCount(void) const                {return d_listItems.size();}


        size_t  getSelectedCount(void) const;


        ListboxItem*    getFirstSelectedItem(void) const;


        ListboxItem*    getNextSelected(const ListboxItem* start_item) const;


        ListboxItem*    getListboxItemFromIndex(size_t index) const;


        size_t  getItemIndex(const ListboxItem* item) const;


        bool    isSortEnabled(void) const               {return d_sorted;}

        bool    isMultiselectEnabled(void) const        {return d_multiselect;}

        bool    isItemTooltipsEnabled(void) const       {return d_itemTooltips;}

        bool    isItemSelected(size_t index) const;


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


        bool    isListboxItemInList(const ListboxItem* item) const;


        bool    isVertScrollbarAlwaysShown(void) const;


        bool    isHorzScrollbarAlwaysShown(void) const;


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


        void    resetList(void);


        void    addItem(ListboxItem* item);


        void    insertItem(ListboxItem* item, const ListboxItem* position);


        void    removeItem(const ListboxItem* item);


        void    clearAllSelections(void);


        void    setSortingEnabled(bool setting);


        void    setMultiselectEnabled(bool setting);


        void    setShowVertScrollbar(bool setting);


        void    setShowHorzScrollbar(bool setting);

        void    setItemTooltipsEnabled(bool setting);
        void    setItemSelectState(ListboxItem* item, bool state);


        void    setItemSelectState(size_t item_index, bool state);


        void    handleUpdatedItemData(void);


        void    ensureItemIsVisible(size_t item_index);


        void    ensureItemIsVisible(const ListboxItem* item);


    virtual Rectf getListRenderArea(void) const;


    Scrollbar* getVertScrollbar() const;

    Scrollbar* getHorzScrollbar() const;


    float   getTotalItemsHeight(void) const;


    float   getWidestItemWidth(void) const;


    ListboxItem* getItemAtPoint(const Vector2f& pt) const;


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


        virtual ~Listbox(void);


protected:
        /*************************************************************************
                Abstract Implementation Functions (must be provided by derived class)
        *************************************************************************/
        //virtual       Rect    getListRenderArea_impl(void) const = 0;


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

        void    selectRange(size_t start, size_t end);


        bool    clearAllSelections_impl(void);


        bool    resetList_impl(void);

    bool handle_scrollChange(const EventArgs& args);


    // validate window renderer
    virtual bool validateWindowRenderer(const WindowRenderer* renderer) const;

    void resortList();

        /*************************************************************************
                New event handlers
        *************************************************************************/
        virtual void    onListContentsChanged(WindowEventArgs& e);


        virtual void    onSelectionChanged(WindowEventArgs& e);


        virtual void    onSortModeChanged(WindowEventArgs& e);


        virtual void    onMultiselectModeChanged(WindowEventArgs& e);


        virtual void    onVertScrollbarModeChanged(WindowEventArgs& e);


        virtual void    onHorzScrollbarModeChanged(WindowEventArgs& e);


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


        /*************************************************************************
                Implementation Data
        *************************************************************************/
        typedef std::vector<ListboxItem*
        CEGUI_VECTOR_ALLOC(ListboxItem*)> LBItemList;
        bool    d_sorted;                               
        bool    d_multiselect;                  
        bool    d_forceVertScroll;              
        bool    d_forceHorzScroll;              
        bool    d_itemTooltips;                 
        LBItemList      d_listItems;            
        ListboxItem*    d_lastSelected; 

    friend class ListboxWindowRenderer;

private:

        /*************************************************************************
                Private methods
        *************************************************************************/
        void    addListboxProperties(void);
};


bool lbi_less(const ListboxItem* a, const ListboxItem* b);


bool lbi_greater(const ListboxItem* a, const ListboxItem* b);

} // End of  CEGUI namespace section


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

#endif  // end of guard _CEGUIListbox_h_