source: GTP/trunk/App/Demos/Geom/OgreStuff/include/CEGUI/elements/CEGUIScrollablePane.h @ 1812

Revision 1812, 20.1 KB checked in by gumbau, 18 years ago (diff)
Line 
1/************************************************************************
2        filename:       CEGUIScrollablePane.h
3        created:        1/3/2005
4        author:         Paul D Turner
5*************************************************************************/
6/*************************************************************************
7    Crazy Eddie's GUI System (http://www.cegui.org.uk)
8    Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
9
10    This library is free software; you can redistribute it and/or
11    modify it under the terms of the GNU Lesser General Public
12    License as published by the Free Software Foundation; either
13    version 2.1 of the License, or (at your option) any later version.
14
15    This library is distributed in the hope that it will be useful,
16    but WITHOUT ANY WARRANTY; without even the implied warranty of
17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18    Lesser General Public License for more details.
19
20    You should have received a copy of the GNU Lesser General Public
21    License along with this library; if not, write to the Free Software
22    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
23*************************************************************************/
24#ifndef _CEGUIScrollablePane_h_
25#define _CEGUIScrollablePane_h_
26
27#include "CEGUIBase.h"
28#include "CEGUIWindow.h"
29#include "elements/CEGUIScrollablePaneProperties.h"
30
31#if defined(_MSC_VER)
32#       pragma warning(push)
33#       pragma warning(disable : 4251)
34#endif
35
36// Start of CEGUI namespace section
37namespace CEGUI
38{
39    /*!
40    \brief
41        Base class for the ScrollablePane widget.
42
43        The ScrollablePane widget allows child windows to be attached which cover an area
44        larger than the ScrollablePane itself and these child windows can be scrolled into
45        view using the scrollbars of the scrollable pane.
46    */
47    class CEGUIEXPORT ScrollablePane : public Window
48    {
49    public:
50        /*************************************************************************
51            Constants
52        *************************************************************************/
53        static const String EventNamespace;                 //!< Namespace for global events
54        static const String EventContentPaneChanged;        //!< Event fired when an area on the content pane has been updated.
55        static const String EventVertScrollbarModeChanged;      //!< Event triggered when the vertical scroll bar 'force' setting changes.
56        static const String EventHorzScrollbarModeChanged;      //!< Event triggered when the horizontal scroll bar 'force' setting changes.
57        static const String EventAutoSizeSettingChanged;    //!< Event fired when the auto size setting changes.
58        static const String EventContentPaneScrolled;       //!< Event fired when the pane gets scrolled.
59
60        /*************************************************************************
61            Construction / Destruction
62        *************************************************************************/
63        /*!
64        \brief
65            Constructor for the ScrollablePane base class.
66        */
67        ScrollablePane(const String& type, const String& name);
68
69        /*!
70        \brief
71            Destructor for the ScrollablePane base class.
72        */
73        ~ScrollablePane(void);
74
75        /*************************************************************************
76                Public interface
77        *************************************************************************/
78        /*!
79        \brief
80            Returns a pointer to the window holding the pane contents.
81
82            The purpose of this is so that attached windows may be inspected,
83            client code may not modify the returned window in any way.
84
85        \return
86            Pointer to the ScrolledContainer that is acting as the container for the
87            scrollable pane content.  The returned window is const, client code should
88            not modify the ScrolledContainer settings directly.
89        */
90        const ScrolledContainer* getContentPane(void) const;
91
92        /*!
93        \brief
94            Return whether the vertical scroll bar is always shown.
95
96        \return
97            - true if the scroll bar will always be shown even if it is not required.
98            - false if the scroll bar will only be shown when it is required.
99        */
100        bool    isVertScrollbarAlwaysShown(void) const;
101        /*!
102        \brief
103            Set whether the vertical scroll bar should always be shown.
104
105        \param setting
106            - true if the vertical scroll bar should be shown even when it is not required.
107            - false if the vertical scroll bar should only be shown when it is required.
108
109        \return
110            Nothing.
111        */
112        void    setShowVertScrollbar(bool setting);
113
114        /*!
115        \brief
116            Return whether the horizontal scroll bar is always shown.
117
118        \return
119            - true if the scroll bar will always be shown even if it is not required.
120            - false if the scroll bar will only be shown when it is required.
121        */
122        bool    isHorzScrollbarAlwaysShown(void) const;
123
124        /*!
125        \brief
126            Set whether the horizontal scroll bar should always be shown.
127
128        \param setting
129            - true if the horizontal scroll bar should be shown even when it is not required.
130            - false if the horizontal scroll bar should only be shown when it is required.
131
132        \return
133            Nothing.
134        */
135        void    setShowHorzScrollbar(bool setting);
136
137        /*!
138        \brief
139            Return whether the content pane is auto sized.
140
141        \return
142            - true to indicate the content pane will automatically resize itself.
143            - false to indicate the content pane will not automatically resize itself.
144        */
145        bool isContentPaneAutoSized(void) const;
146
147        /*!
148        \brief
149            Set whether the content pane should be auto-sized.
150
151        \param setting
152            - true to indicate the content pane should automatically resize itself.
153            - false to indicate the content pane should not automatically resize itself.
154
155        \return
156            Nothing.
157        */
158        void setContentPaneAutoSized(bool setting);
159
160        /*!
161        \brief
162            Return the current content pane area for the ScrollablePane.
163
164        \return
165            Rect object that details the current pixel extents of the content
166            pane attached to this ScrollablePane.
167        */
168        const Rect& getContentPaneArea(void) const;
169
170        /*!
171        \brief
172            Set the current content pane area for the ScrollablePane.
173
174        \note
175            If the ScrollablePane is configured to auto-size the content pane
176            this call will have no effect.
177
178        \param area
179            Rect object that details the pixel extents to use for the content
180            pane attached to this ScrollablePane.
181
182        \return
183            Nothing.
184        */
185        void setContentPaneArea(const Rect& area);
186
187        /*!
188        \brief
189            Returns the horizontal scrollbar step size as a fraction of one
190            complete view page.
191
192        \return
193            float value specifying the step size where 1.0f would be the width of
194            the viewing area.
195        */
196        float getHorizontalStepSize(void) const;
197
198        /*!
199        \brief
200            Sets the horizontal scrollbar step size as a fraction of one
201            complete view page.
202
203        \param step
204            float value specifying the step size, where 1.0f would be the width of
205            the viewing area.
206
207        \return
208            Nothing.
209        */
210        void setHorizontalStepSize(float step);
211
212        /*!
213        \brief
214            Returns the horizontal scrollbar overlap size as a fraction of one
215            complete view page.
216
217        \return
218            float value specifying the overlap size where 1.0f would be the width of
219            the viewing area.
220        */
221        float getHorizontalOverlapSize(void) const;
222
223        /*!
224        \brief
225            Sets the horizontal scrollbar overlap size as a fraction of one
226            complete view page.
227
228        \param overlap
229            float value specifying the overlap size, where 1.0f would be the width of
230            the viewing area.
231
232        \return
233            Nothing.
234        */
235        void setHorizontalOverlapSize(float overlap);
236
237        /*!
238        \brief
239            Returns the horizontal scroll position as a fraction of the
240            complete scrollable width.
241
242        \return
243            float value specifying the scroll position.
244        */
245        float getHorizontalScrollPosition(void) const;
246
247        /*!
248        \brief
249            Sets the horizontal scroll position as a fraction of the
250            complete scrollable width.
251
252        \param position
253            float value specifying the new scroll position.
254
255        \return
256            Nothing.
257        */
258        void setHorizontalScrollPosition(float position);
259
260        /*!
261        \brief
262            Returns the vertical scrollbar step size as a fraction of one
263            complete view page.
264
265        \return
266            float value specifying the step size where 1.0f would be the height of
267            the viewing area.
268        */
269        float getVerticalStepSize(void) const;
270
271        /*!
272        \brief
273            Sets the vertical scrollbar step size as a fraction of one
274            complete view page.
275
276        \param step
277            float value specifying the step size, where 1.0f would be the height of
278            the viewing area.
279
280        \return
281            Nothing.
282        */
283        void setVerticalStepSize(float step);
284
285        /*!
286        \brief
287            Returns the vertical scrollbar overlap size as a fraction of one
288            complete view page.
289
290        \return
291            float value specifying the overlap size where 1.0f would be the height of
292            the viewing area.
293        */
294        float getVerticalOverlapSize(void) const;
295
296        /*!
297        \brief
298            Sets the vertical scrollbar overlap size as a fraction of one
299            complete view page.
300
301        \param overlap
302            float value specifying the overlap size, where 1.0f would be the height of
303            the viewing area.
304
305        \return
306            Nothing.
307        */
308        void setVerticalOverlapSize(float overlap);
309
310        /*!
311        \brief
312            Returns the vertical scroll position as a fraction of the
313            complete scrollable height.
314
315        \return
316            float value specifying the scroll position.
317        */
318        float getVerticalScrollPosition(void) const;
319
320        /*!
321        \brief
322            Sets the vertical scroll position as a fraction of the
323            complete scrollable height.
324
325        \param position
326            float value specifying the new scroll position.
327
328        \return
329            Nothing.
330        */
331        void setVerticalScrollPosition(float position);
332
333        /*************************************************************************
334            Overridden from Window
335        *************************************************************************/
336        void initialise(void);
337
338    protected:
339        /*************************************************************************
340                Abstract interface
341        *************************************************************************/
342        /*!
343        \brief
344            Create a Scrollbar based widget to be used as the horizontal scrollbar.
345
346        \param name
347            String object holding the name that must be used when creating the widget.
348
349        \return
350            Scrollbar based object.
351        */
352        virtual Scrollbar* createHorizontalScrollbar(const String& name) const = 0;
353
354        /*!
355        \brief
356            Create a Scrollbar based widget to be used as the vertical scrollbar.
357
358        \param name
359            String object holding the name that must be used when creating the widget.
360
361        \return
362            Scrollbar based object.
363        */
364        virtual Scrollbar* createVerticalScrollbar(const String& name) const = 0;
365
366        /*!
367        \brief
368            Return a Rect that described the pane's viewable area, relative
369            to this Window, in pixels.
370
371        \return
372            Rect object describing the ScrollablePane's viewable area.
373        */
374        virtual Rect getViewableArea(void) const = 0;
375
376        /*************************************************************************
377                Implementation Methods
378        *************************************************************************/
379        /*!
380        \brief
381            Add ScrollablePane specific events
382        */
383        void addScrollablePaneEvents(void);
384
385        /*!
386            \brief
387                    display required integrated scroll bars according to current size of
388            the ScrollablePane view area and the size of the attached ScrolledContainer.
389            */
390            void configureScrollbars(void);
391
392        /*!
393        \brief
394            Return whether the vertical scrollbar is needed.
395
396        \return
397            - true if the scrollbar is either needed or forced via setting.
398            - false if the scrollbar should not be shown.
399        */
400        bool isVertScrollbarNeeded(void) const;
401
402        /*!
403        \brief
404            Return whether the horizontal scrollbar is needed.
405
406        \return
407            - true if the scrollbar is either needed or forced via setting.
408            - false if the scrollbar should not be shown.
409        */
410        bool isHorzScrollbarNeeded(void) const;
411
412        /*!
413        \brief
414            Update the content container position according to the current
415            state of the widget (like scrollbar positions, etc).
416        */
417        void updateContainerPosition(void);
418
419
420                /*!
421                \brief
422                        Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
423
424                \param class_name
425                        The class name that is to be checked.
426
427                \return
428                        true if this window was inherited from \a class_name. false if not.
429                */
430                virtual bool    testClassName_impl(const String& class_name) const
431                {
432                        if (class_name==(const utf8*)"ScrollablePane")  return true;
433                        return Window::testClassName_impl(class_name);
434                }
435
436
437        /*************************************************************************
438                Event triggers
439        *************************************************************************/
440        /*!
441        \brief
442            Event trigger method called when some pane content has changed size
443            or location.
444
445        \param e
446            WindowEventArgs object.
447
448        \return
449            Nothing.
450        */
451        virtual void onContentPaneChanged(WindowEventArgs& e);
452
453        /*!
454        \brief
455            Event trigger method called when the setting that controls whether the
456            vertical scrollbar is always shown or not, is changed.
457
458        \param e
459            WindowEventArgs object.
460
461        \return
462            Nothing.
463        */
464        virtual void onVertScrollbarModeChanged(WindowEventArgs& e);
465
466        /*!
467        \brief
468            Event trigger method called when the setting that controls whether the
469            horizontal scrollbar is always shown or not, is changed.
470
471        \param e
472            WindowEventArgs object.
473
474        \return
475            Nothing.
476        */
477        virtual void onHorzScrollbarModeChanged(WindowEventArgs& e);
478
479        /*!
480        \brief
481            Notification method called whenever the setting that controls whether
482            the content pane is automatically sized is changed.
483
484        \param e
485            WindowEventArgs object.
486
487        \return
488            Nothing.
489        */
490        virtual void onAutoSizeSettingChanged(WindowEventArgs& e);
491
492        /*!
493        \brief
494            Notification method called whenever the content pane is scrolled via
495            changes in the scrollbar positions.
496
497        \param e
498            WindowEventArgs object.
499
500        \return
501            Nothing.
502        */
503        virtual void onContentPaneScrolled(WindowEventArgs& e);
504
505        /*************************************************************************
506                Event handler methods
507        *************************************************************************/
508        /*!
509        \brief
510            Handler method which gets subscribed to the scrollbar position change
511            events.
512        */
513        bool handleScrollChange(const EventArgs&  e);
514
515        /*!
516        \brief
517            Handler method which gets subscribed to the ScrolledContainer content
518            change events.
519        */
520        bool handleContentAreaChange(const EventArgs& e);
521
522        /*!
523        \brief
524            Handler method which gets subscribed to the ScrolledContainer auto-size
525            setting changes.
526        */
527        bool handleAutoSizePaneChanged(const EventArgs& e);
528
529        /*************************************************************************
530                Overridden from Window
531        *************************************************************************/
532        void addChild_impl(Window* wnd);
533        void removeChild_impl(Window* wnd);
534        void onSized(WindowEventArgs& e);
535        void onMouseWheel(MouseEventArgs& e);
536
537        /*************************************************************************
538                Data fields
539        *************************************************************************/
540        bool    d_forceVertScroll;              //!< true if vertical scrollbar should always be displayed
541        bool    d_forceHorzScroll;              //!< true if horizontal scrollbar should always be displayed
542        Rect    d_contentRect;          //!< holds content area so we can track changes.
543        float   d_vertStep;             //!< vertical scroll step fraction.
544        float   d_vertOverlap;          //!< vertical scroll overlap fraction.
545        float   d_horzStep;             //!< horizontal scroll step fraction.
546        float   d_horzOverlap;          //!< horizontal scroll overlap fraction.
547
548        // component widgets
549        Scrollbar*  d_vertScrollbar;        //!< Scrollbar widget used for vertical scrolling.
550        Scrollbar*  d_horzScrollbar;        //!< Scrollbar widget used for horizontal scrolling.
551        ScrolledContainer*  d_container;    //!< ScrolledContainer widget holding the attached widgets.
552
553    private:
554            /*************************************************************************
555                    Static Properties for this class
556            *************************************************************************/
557        static ScrollablePaneProperties::ForceHorzScrollbar     d_horzScrollbarProperty;
558        static ScrollablePaneProperties::ForceVertScrollbar     d_vertScrollbarProperty;
559            static ScrollablePaneProperties::ContentPaneAutoSized       d_autoSizedProperty;
560            static ScrollablePaneProperties::ContentArea            d_contentAreaProperty;
561        static ScrollablePaneProperties::HorzStepSize           d_horzStepProperty;
562        static ScrollablePaneProperties::HorzOverlapSize        d_horzOverlapProperty;
563        static ScrollablePaneProperties::HorzScrollPosition     d_horzScrollPositionProperty;
564        static ScrollablePaneProperties::VertStepSize           d_vertStepProperty;
565        static ScrollablePaneProperties::VertOverlapSize        d_vertOverlapProperty;
566        static ScrollablePaneProperties::VertScrollPosition     d_vertScrollPositionProperty;
567
568            /*************************************************************************
569                    Private methods
570            *************************************************************************/
571            void addScrollablePaneProperties(void);
572    };
573
574} // End of  CEGUI namespace section
575
576
577#if defined(_MSC_VER)
578#       pragma warning(pop)
579#endif
580
581#endif  // end of guard _CEGUIScrollablePane_h_
Note: See TracBrowser for help on using the repository browser.