/************************************************************************ filename: CEGUIScrollbar.h created: 13/4/2004 author: Paul D Turner purpose: Interface to base class for Scrollbar widget *************************************************************************/ /************************************************************************* Crazy Eddie's GUI System (http://www.cegui.org.uk) Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk) This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA *************************************************************************/ #ifndef _CEGUIScrollbar_h_ #define _CEGUIScrollbar_h_ #include "CEGUIBase.h" #include "CEGUIWindow.h" #include "elements/CEGUIScrollbarProperties.h" #if defined(_MSC_VER) # pragma warning(push) # pragma warning(disable : 4251) #endif // Start of CEGUI namespace section namespace CEGUI { /*! \brief Base scroll bar class. This base class for scroll bars does not have any idea of direction - a derived class would add whatever meaning is appropriate according to what that derived class represents to the user. */ class CEGUIEXPORT Scrollbar : public Window { public: static const String EventNamespace; //!< Namespace for global events /************************************************************************* Event name constants *************************************************************************/ static const String EventScrollPositionChanged; //!< Name of the event fired when the scroll bar position value changes static const String EventThumbTrackStarted; //!< Name of the event fired when the user begins dragging the thumb. static const String EventThumbTrackEnded; //!< Name of the event fired when the user releases the thumb. static const String EventScrollConfigChanged; //!< Name of the event fired when the scroll bar configuration data changes. /************************************************************************* Accessor functions *************************************************************************/ /*! \brief Return the size of the document or data. The document size should be thought of as the total size of the data that is being scrolled through (the number of lines in a text file for example). \note The returned value has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar. \return float value specifying the currently set document size. */ float getDocumentSize(void) const {return d_documentSize;} /*! \brief Return the page size for this scroll bar. The page size is typically the amount of data that can be displayed at one time. This value is also used when calculating the amount the position will change when you click either side of the scroll bar thumb - the amount the position changes will is (pageSize - overlapSize). \note The returned value has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar. \return float value specifying the currently set page size. */ float getPageSize(void) const {return d_pageSize;} /*! \brief Return the step size for this scroll bar. The step size is typically a single unit of data that can be displayed, this is the amount the position will change when you click either of the arrow buttons on the scroll bar. (this could be 1 for a single line of text, for example). \note The returned value has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar. \return float value specifying the currently set step size. */ float getStepSize(void) const {return d_stepSize;} /*! \brief Return the overlap size for this scroll bar. The overlap size is the amount of data from the end of a 'page' that will remain visible when the position is moved by a page. This is usually used so that the user keeps some context of where they were within the document's data when jumping a page at a time. \note The returned value has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar. \return float value specifying the currently set overlap size. */ float getOverlapSize(void) const {return d_overlapSize;} /*! \brief Return the current position of scroll bar within the document. The range of the scroll bar is from 0 to the size of the document minus the size of a page (0 <= position <= (documentSize - pageSize)). \note The returned value has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar. \return float value specifying the current position of the scroll bar within its document. */ float getScrollPosition(void) const {return d_position;} /************************************************************************* Manipulator Commands *************************************************************************/ /*! \brief Initialises the Scrollbar object ready for use. \note This must be called for every window created. Normally this is handled automatically by the WindowFactory for each Window type. \return Nothing */ virtual void initialise(void); /*! \brief Set the size of the document or data. The document size should be thought of as the total size of the data that is being scrolled through (the number of lines in a text file for example). \note The value set has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar. \param document_size float value specifying the document size. \return Nothing. */ void setDocumentSize(float document_size); /*! \brief Set the page size for this scroll bar. The page size is typically the amount of data that can be displayed at one time. This value is also used when calculating the amount the position will change when you click either side of the scroll bar thumb - the amount the position changes will is (pageSize - overlapSize). \note The value set has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar. \param page_size float value specifying the page size. \return Nothing. */ void setPageSize(float page_size); /*! \brief Set the step size for this scroll bar. The step size is typically a single unit of data that can be displayed, this is the amount the position will change when you click either of the arrow buttons on the scroll bar. (this could be 1 for a single line of text, for example). \note The value set has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar. \param step_size float value specifying the step size. \return Nothing. */ void setStepSize(float step_size); /*! \brief Set the overlap size for this scroll bar. The overlap size is the amount of data from the end of a 'page' that will remain visible when the position is moved by a page. This is usually used so that the user keeps some context of where they were within the document's data when jumping a page at a time. \note The value set has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar. \param overlap_size float value specifying the overlap size. \return Nothing. */ void setOverlapSize(float overlap_size); /*! \brief Set the current position of scroll bar within the document. The range of the scroll bar is from 0 to the size of the document minus the size of a page (0 <= position <= (documentSize - pageSize)), any attempt to set the position outside this range will be adjusted so that it falls within the legal range. \note The returned value has no meaning within the Gui system, it is left up to the application to assign appropriate values for the application specific use of the scroll bar. \param position float value specifying the position of the scroll bar within its document. \return Nothing. */ void setScrollPosition(float position); /************************************************************************* Construction / Destruction *************************************************************************/ /*! \brief Constructor for Scrollbar objects */ Scrollbar(const String& type, const String& name); /*! \brief Destructor for Scrollbar objects */ virtual ~Scrollbar(void); protected: /************************************************************************* Implementation Methods *************************************************************************/ /*! \brief Add scroll bar specific events */ void addScrollbarEvents(void); /*! \brief create a PushButton based widget to use as the increase button for this scroll bar. \param name String holding the name that must be passed when creating the component widget. */ virtual PushButton* createIncreaseButton(const String& name) const = 0; /*! \brief create a PushButton based widget to use as the decrease button for this scroll bar. \param name String holding the name that must be passed when creating the component widget. */ virtual PushButton* createDecreaseButton(const String& name) const = 0; /*! \brief create a Thumb based widget to use as the thumb for this scroll bar. \param name String holding the name that must be passed when creating the component widget. */ virtual Thumb* createThumb(const String& name) const = 0; /*! \brief update the size and location of the thumb to properly represent the current state of the scroll bar */ virtual void updateThumb(void) = 0; /*! \brief return value that best represents current scroll bar position given the current location of the thumb. \return float value that, given the thumb widget position, best represents the current position for the scroll bar. */ virtual float getValueFromThumb(void) const = 0; /*! \brief Given window location \a pt, return a value indicating what change should be made to the scroll bar. \param pt Point object describing a pixel position in window space. \return - -1 to indicate scroll bar position should be moved to a lower value. - 0 to indicate scroll bar position should not be changed. - +1 to indicate scroll bar position should be moved to a higher value. */ virtual float getAdjustDirectionFromPoint(const Point& pt) const = 0; /*! \brief handler function for when thumb moves. */ bool handleThumbMoved(const EventArgs& e); /*! \brief handler function for when the increase button is clicked. */ bool handleIncreaseClicked(const EventArgs& e); /*! \brief handler function for when the decrease button is clicked. */ bool handleDecreaseClicked(const EventArgs& e); /*! \brief handler function for when thumb tracking begins */ bool handleThumbTrackStarted(const EventArgs& e); /*! \brief handler function for when thumb tracking begins */ bool handleThumbTrackEnded(const EventArgs& e); /*! \brief Return whether this window was inherited from the given class name at some point in the inheritance heirarchy. \param class_name The class name that is to be checked. \return true if this window was inherited from \a class_name. false if not. */ virtual bool testClassName_impl(const String& class_name) const { if (class_name==(const utf8*)"Scrollbar") return true; return Window::testClassName_impl(class_name); } /************************************************************************* New event handlers for slider widget *************************************************************************/ /*! \brief Handler triggered when the scroll position changes */ virtual void onScrollPositionChanged(WindowEventArgs& e); /*! \brief Handler triggered when the user begins to drag the scroll bar thumb. */ virtual void onThumbTrackStarted(WindowEventArgs& e); /*! \brief Handler triggered when the scroll bar thumb is released */ virtual void onThumbTrackEnded(WindowEventArgs& e); /*! \brief Handler triggered when the scroll bar data configuration changes */ virtual void onScrollConfigChanged(WindowEventArgs& e); /************************************************************************* Overridden event handlers *************************************************************************/ virtual void onMouseButtonDown(MouseEventArgs& e); virtual void onMouseWheel(MouseEventArgs& e); /************************************************************************* Implementation Data *************************************************************************/ float d_documentSize; //!< The size of the document / data being scrolled thorugh. float d_pageSize; //!< The size of a single 'page' of data. float d_stepSize; //!< Step size used for increase / decrease button clicks. float d_overlapSize; //!< Amount of overlap when jumping by a page. float d_position; //!< Current scroll position. // Pointers to the controls that make up the scroll bar Thumb* d_thumb; //!< widget used to represent the 'thumb' of the scroll bar. PushButton* d_increase; //!< Widget used for the increase button of the scroll bar. PushButton* d_decrease; //!< Widget used for the decrease button of the scroll bar. private: /************************************************************************* Static Properties for this class *************************************************************************/ static ScrollbarProperties::DocumentSize d_documentSizeProperty; static ScrollbarProperties::PageSize d_pageSizeProperty; static ScrollbarProperties::StepSize d_stepSizeProperty; static ScrollbarProperties::OverlapSize d_overlapSizeProperty; static ScrollbarProperties::ScrollPosition d_scrollPositionProperty; /************************************************************************* Private methods *************************************************************************/ void addScrollbarProperties(void); }; } // End of CEGUI namespace section #if defined(_MSC_VER) # pragma warning(pop) #endif #endif // end of guard _CEGUIScrollbar_h_