source: OGRE/trunk/ogre_dependencies/Dependencies/include/CEGUI/elements/CEGUIScrollbar.h @ 692

Revision 692, 15.6 KB checked in by mattausch, 19 years ago (diff)

adding ogre 1.2 and dependencies
Line 
1/************************************************************************
2        filename:       CEGUIScrollbar.h
3        created:        13/4/2004
4        author:         Paul D Turner
5       
6        purpose:        Interface to base class for Scrollbar widget
7*************************************************************************/
8/*************************************************************************
9    Crazy Eddie's GUI System (http://www.cegui.org.uk)
10    Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
11
12    This library is free software; you can redistribute it and/or
13    modify it under the terms of the GNU Lesser General Public
14    License as published by the Free Software Foundation; either
15    version 2.1 of the License, or (at your option) any later version.
16
17    This library is distributed in the hope that it will be useful,
18    but WITHOUT ANY WARRANTY; without even the implied warranty of
19    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
20    Lesser General Public License for more details.
21
22    You should have received a copy of the GNU Lesser General Public
23    License along with this library; if not, write to the Free Software
24    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
25*************************************************************************/
26#ifndef _CEGUIScrollbar_h_
27#define _CEGUIScrollbar_h_
28
29#include "CEGUIBase.h"
30#include "CEGUIWindow.h"
31#include "elements/CEGUIScrollbarProperties.h"
32
33
34#if defined(_MSC_VER)
35#       pragma warning(push)
36#       pragma warning(disable : 4251)
37#endif
38
39
40// Start of CEGUI namespace section
41namespace CEGUI
42{
43/*!
44\brief
45        Base scroll bar class.
46
47        This base class for scroll bars does not have any idea of direction - a derived class would
48        add whatever meaning is appropriate according to what that derived class
49        represents to the user.
50*/
51class CEGUIEXPORT Scrollbar : public Window
52{
53public:
54        static const String EventNamespace;                             //!< Namespace for global events
55
56        /*************************************************************************
57                Event name constants
58        *************************************************************************/
59        static const String EventScrollPositionChanged;         //!< Name of the event fired when the scroll bar position value changes
60        static const String EventThumbTrackStarted;                     //!< Name of the event fired when the user begins dragging the thumb.
61        static const String EventThumbTrackEnded;                               //!< Name of the event fired when the user releases the thumb.
62        static const String EventScrollConfigChanged;                   //!< Name of the event fired when the scroll bar configuration data changes.
63
64
65        /*************************************************************************
66                Accessor functions
67        *************************************************************************/
68        /*!
69        \brief
70                Return the size of the document or data.
71               
72                The document size should be thought of as the total size of the data that
73                is being scrolled through (the number of lines in a text file for example).
74
75        \note
76                The returned value has no meaning within the Gui system, it is left up to the
77                application to assign appropriate values for the application specific use of
78                the scroll bar.
79
80        \return
81                float value specifying the currently set document size.
82        */
83        float   getDocumentSize(void) const                     {return d_documentSize;}
84
85
86        /*!
87        \brief
88                Return the page size for this scroll bar.
89               
90                The page size is typically the amount of data that can be displayed at one
91                time.  This value is also used when calculating the amount the position will
92                change when you click either side of the scroll bar thumb - the amount the
93                position changes will is (pageSize - overlapSize).
94
95        \note
96                The returned value has no meaning within the Gui system, it is left up to the
97                application to assign appropriate values for the application specific use of
98                the scroll bar.
99
100        \return
101                float value specifying the currently set page size.
102        */
103        float   getPageSize(void) const                         {return d_pageSize;}
104
105
106        /*!
107        \brief
108                Return the step size for this scroll bar.
109               
110                The step size is typically a single unit of data that can be displayed, this is the
111                amount the position will change when you click either of the arrow buttons on the
112                scroll bar.  (this could be 1 for a single line of text, for example).
113
114        \note
115                The returned value has no meaning within the Gui system, it is left up to the
116                application to assign appropriate values for the application specific use of
117                the scroll bar.
118
119        \return
120                float value specifying the currently set step size.
121        */
122        float   getStepSize(void) const                         {return d_stepSize;}
123
124
125        /*!
126        \brief
127                Return the overlap size for this scroll bar.
128               
129                The overlap size is the amount of data from the end of a 'page' that will
130                remain visible when the position is moved by a page.  This is usually used
131                so that the user keeps some context of where they were within the document's
132                data when jumping a page at a time.
133
134        \note
135                The returned value has no meaning within the Gui system, it is left up to the
136                application to assign appropriate values for the application specific use of
137                the scroll bar.
138
139        \return
140                float value specifying the currently set overlap size.
141        */
142        float   getOverlapSize(void) const                      {return d_overlapSize;}
143
144
145        /*!
146        \brief
147                Return the current position of scroll bar within the document.
148
149                The range of the scroll bar is from 0 to the size of the document minus the
150                size of a page (0 <= position <= (documentSize - pageSize)).
151
152        \note
153                The returned value has no meaning within the Gui system, it is left up to the
154                application to assign appropriate values for the application specific use of
155                the scroll bar.
156
157        \return
158                float value specifying the current position of the scroll bar within its
159                document.
160        */
161        float   getScrollPosition(void) const           {return d_position;}
162
163
164        /*************************************************************************
165                Manipulator Commands
166        *************************************************************************/
167        /*!
168        \brief
169                Initialises the Scrollbar object ready for use.
170
171        \note
172                This must be called for every window created.  Normally this is handled automatically by the WindowFactory for each Window type.
173
174        \return
175                Nothing
176        */
177        virtual void    initialise(void);
178
179
180        /*!
181        \brief
182                Set the size of the document or data.
183               
184                The document size should be thought of as the total size of the data that
185                is being scrolled through (the number of lines in a text file for example).
186
187        \note
188                The value set has no meaning within the Gui system, it is left up to the
189                application to assign appropriate values for the application specific use of
190                the scroll bar.
191
192        \param document_size
193                float value specifying the document size.
194
195        \return
196                Nothing.
197        */
198        void    setDocumentSize(float document_size);
199
200
201        /*!
202        \brief
203                Set the page size for this scroll bar.
204               
205                The page size is typically the amount of data that can be displayed at one
206                time.  This value is also used when calculating the amount the position will
207                change when you click either side of the scroll bar thumb - the amount the
208                position changes will is (pageSize - overlapSize).
209
210        \note
211                The value set has no meaning within the Gui system, it is left up to the
212                application to assign appropriate values for the application specific use of
213                the scroll bar.
214
215        \param page_size
216                float value specifying the page size.
217
218        \return
219                Nothing.
220        */
221        void    setPageSize(float page_size);
222
223
224        /*!
225        \brief
226                Set the step size for this scroll bar.
227               
228                The step size is typically a single unit of data that can be displayed, this is the
229                amount the position will change when you click either of the arrow buttons on the
230                scroll bar.  (this could be 1 for a single line of text, for example).
231
232        \note
233                The value set has no meaning within the Gui system, it is left up to the
234                application to assign appropriate values for the application specific use of
235                the scroll bar.
236
237        \param step_size
238                float value specifying the step size.
239
240        \return
241                Nothing.
242        */
243        void    setStepSize(float step_size);
244
245
246        /*!
247        \brief
248                Set the overlap size for this scroll bar.
249               
250                The overlap size is the amount of data from the end of a 'page' that will
251                remain visible when the position is moved by a page.  This is usually used
252                so that the user keeps some context of where they were within the document's
253                data when jumping a page at a time.
254
255        \note
256                The value set has no meaning within the Gui system, it is left up to the
257                application to assign appropriate values for the application specific use of
258                the scroll bar.
259
260        \param overlap_size
261                float value specifying the overlap size.
262
263        \return
264                Nothing.
265        */
266        void    setOverlapSize(float overlap_size);
267
268
269        /*!
270        \brief
271                Set the current position of scroll bar within the document.
272
273                The range of the scroll bar is from 0 to the size of the document minus the
274                size of a page (0 <= position <= (documentSize - pageSize)), any attempt to
275                set the position outside this range will be adjusted so that it falls within
276                the legal range.
277
278        \note
279                The returned value has no meaning within the Gui system, it is left up to the
280                application to assign appropriate values for the application specific use of
281                the scroll bar.
282
283        \param position
284                float value specifying the position of the scroll bar within its
285                document.
286
287        \return
288                Nothing.
289        */
290        void    setScrollPosition(float position);
291
292
293        /*************************************************************************
294                Construction / Destruction
295        *************************************************************************/
296        /*!
297        \brief
298                Constructor for Scrollbar objects
299        */
300        Scrollbar(const String& type, const String& name);
301
302
303        /*!
304        \brief
305                Destructor for Scrollbar objects
306        */
307        virtual ~Scrollbar(void);
308
309
310protected:
311        /*************************************************************************
312                Implementation Methods
313        *************************************************************************/
314        /*!
315        \brief
316                Add scroll bar specific events
317        */
318        void    addScrollbarEvents(void);
319
320
321        /*!
322        \brief
323                create a PushButton based widget to use as the increase button for this scroll bar.
324
325    \param name
326        String holding the name that must be passed when creating the component widget.
327        */
328        virtual PushButton*     createIncreaseButton(const String& name) const          = 0;
329
330
331        /*!
332        \brief
333                create a PushButton based widget to use as the decrease button for this scroll bar.
334
335    \param name
336        String holding the name that must be passed when creating the component widget.
337        */
338        virtual PushButton*     createDecreaseButton(const String& name) const          = 0;
339
340
341        /*!
342        \brief
343                create a Thumb based widget to use as the thumb for this scroll bar.
344
345    \param name
346        String holding the name that must be passed when creating the component widget.
347        */
348        virtual Thumb*  createThumb(const String& name) const           = 0;
349
350
351        /*!
352        \brief
353                update the size and location of the thumb to properly represent the current state of the scroll bar
354        */
355        virtual void    updateThumb(void)       = 0;
356
357
358        /*!
359        \brief
360                return value that best represents current scroll bar position given the current location of the thumb.
361
362        \return
363                float value that, given the thumb widget position, best represents the current position for the scroll bar.
364        */
365        virtual float   getValueFromThumb(void) const   = 0;
366
367
368        /*!
369        \brief
370                Given window location \a pt, return a value indicating what change should be
371                made to the scroll bar.
372
373        \param pt
374                Point object describing a pixel position in window space.
375
376        \return
377                - -1 to indicate scroll bar position should be moved to a lower value.
378                -  0 to indicate scroll bar position should not be changed.
379                - +1 to indicate scroll bar position should be moved to a higher value.
380        */
381        virtual float   getAdjustDirectionFromPoint(const Point& pt) const      = 0;
382
383
384        /*!
385        \brief
386                handler function for when thumb moves.
387        */
388        bool    handleThumbMoved(const EventArgs& e);
389
390
391        /*!
392        \brief
393                handler function for when the increase button is clicked.
394        */
395        bool    handleIncreaseClicked(const EventArgs& e);
396
397
398        /*!
399        \brief
400                handler function for when the decrease button is clicked.
401        */
402        bool    handleDecreaseClicked(const EventArgs& e);
403
404
405        /*!
406        \brief
407                handler function for when thumb tracking begins
408        */
409        bool    handleThumbTrackStarted(const EventArgs& e);
410
411
412        /*!
413        \brief
414                handler function for when thumb tracking begins
415        */
416        bool    handleThumbTrackEnded(const EventArgs& e);
417
418
419        /*!
420        \brief
421                Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
422
423        \param class_name
424                The class name that is to be checked.
425
426        \return
427                true if this window was inherited from \a class_name. false if not.
428        */
429        virtual bool    testClassName_impl(const String& class_name) const
430        {
431                if (class_name==(const utf8*)"Scrollbar")       return true;
432                return Window::testClassName_impl(class_name);
433        }
434
435
436        /*************************************************************************
437                New event handlers for slider widget
438        *************************************************************************/
439        /*!
440        \brief
441                Handler triggered when the scroll position changes
442        */
443        virtual void    onScrollPositionChanged(WindowEventArgs& e);
444
445
446        /*!
447        \brief
448                Handler triggered when the user begins to drag the scroll bar thumb.
449        */
450        virtual void    onThumbTrackStarted(WindowEventArgs& e);
451
452
453        /*!
454        \brief
455                Handler triggered when the scroll bar thumb is released
456        */
457        virtual void    onThumbTrackEnded(WindowEventArgs& e);
458
459
460        /*!
461        \brief
462                Handler triggered when the scroll bar data configuration changes
463        */
464        virtual void    onScrollConfigChanged(WindowEventArgs& e);
465
466
467        /*************************************************************************
468                Overridden event handlers
469        *************************************************************************/
470        virtual void    onMouseButtonDown(MouseEventArgs& e);
471        virtual void    onMouseWheel(MouseEventArgs& e);
472
473
474        /*************************************************************************
475                Implementation Data
476        *************************************************************************/
477        float   d_documentSize;         //!< The size of the document / data being scrolled thorugh.
478        float   d_pageSize;                     //!< The size of a single 'page' of data.
479        float   d_stepSize;                     //!< Step size used for increase / decrease button clicks.
480        float   d_overlapSize;          //!< Amount of overlap when jumping by a page.
481        float   d_position;                     //!< Current scroll position.
482
483        // Pointers to the controls that make up the scroll bar
484        Thumb*          d_thumb;                //!< widget used to represent the 'thumb' of the scroll bar.
485        PushButton*     d_increase;             //!< Widget used for the increase button of the scroll bar.
486        PushButton*     d_decrease;             //!< Widget used for the decrease button of the scroll bar.
487
488
489private:
490        /*************************************************************************
491                Static Properties for this class
492        *************************************************************************/
493        static ScrollbarProperties::DocumentSize        d_documentSizeProperty;
494        static ScrollbarProperties::PageSize            d_pageSizeProperty;
495        static ScrollbarProperties::StepSize            d_stepSizeProperty;
496        static ScrollbarProperties::OverlapSize         d_overlapSizeProperty;
497        static ScrollbarProperties::ScrollPosition      d_scrollPositionProperty;
498
499
500        /*************************************************************************
501                Private methods
502        *************************************************************************/
503        void    addScrollbarProperties(void);
504};
505
506
507} // End of  CEGUI namespace section
508
509#if defined(_MSC_VER)
510#       pragma warning(pop)
511#endif
512
513#endif  // end of guard _CEGUIScrollbar_h_
Note: See TracBrowser for help on using the repository browser.