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

Revision 692, 12.6 KB checked in by mattausch, 18 years ago (diff)

adding ogre 1.2 and dependencies
Line 
1/************************************************************************
2    filename:   CEGUITooltip.h
3    created:    21/2/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 _CEGUITooltip_h_
25#define _CEGUITooltip_h_
26
27#include "CEGUIWindow.h"
28#include "elements/CEGUITooltipProperties.h"
29
30#if defined(_MSC_VER)
31#       pragma warning(push)
32#       pragma warning(disable : 4251)
33#endif
34
35// Start of CEGUI namespace section
36namespace CEGUI
37{
38    /*!
39    \brief
40        Base class for Tooltip widgets.
41       
42        The Tooltip class shows a simple pop-up window around the mouse position
43        with some text information.  The tool-tip fades in when the user hovers
44        with the mouse over a window which has tool-tip text set, and then fades
45        out after some pre-set time.
46
47    \note
48        For Tooltip to work properly, you must specify a default tool-tip widget
49        type via System::setTooltip, or by setting a custom tool-tip object for
50        your Window(s).  Additionally, you need to ensure that time pulses are
51        properly passed to the system via System::injectTimePulse.
52    */
53    class CEGUIEXPORT Tooltip : public Window
54    {
55    public:
56        /*************************************************************************
57            Constants
58        *************************************************************************/
59        static const String EventNamespace;                 //!< Namespace for global events
60        static const String EventHoverTimeChanged;          //!< Event fired when the hover timeout gets changed.
61        static const String EventDisplayTimeChanged;        //!< Event fired when the display timeout gets changed.
62        static const String EventFadeTimeChanged;           //!< Event fired when the fade timeout gets changed.
63        static const String EventTooltipActive;             //!< Event fired when the tooltip is about to get activated.
64        static const String EventTooltipInactive;           //!< Event fired when the tooltip has been deactivated.
65
66        /************************************************************************
67            Object Construction and Destruction
68        ************************************************************************/
69        /*!
70        \brief
71            Constructor for the Tooltip base class constructor
72         */
73        Tooltip(const String& type, const String& name);
74
75        /*!
76        \brief
77            Destructor for the Tooltip base class.
78         */
79        ~Tooltip(void);
80
81        /************************************************************************
82            Public interface
83        ************************************************************************/
84        /*!
85        \brief
86            Sets the target window for the tooltip.  This used internally to manage tooltips, you
87            should not have to call this yourself.
88
89        \param wnd
90            Window object that the tooltip should be associated with (for now).
91
92        \return
93            Nothing.
94         */
95        void setTargetWindow(Window* wnd);
96
97        /*!
98        \brief
99            return the current target window for this Tooltip.
100
101        \return
102            Pointer to the target window for this Tooltip or 0 for none.
103        */
104        const Window* getTargetWindow();
105
106        /*!
107        \brief
108            Resets the timer on the tooltip when in the Active / Inactive states.  This is used internally
109            to control the tooltip, it is not normally necessary to call this method yourself.
110
111        \return
112            Nothing.
113         */
114        void resetTimer(void);
115
116        /*!
117        \brief
118            Return the number of seconds the mouse should hover stationary over the target window before
119            the tooltip gets activated.
120
121        \return
122            float value representing a number of seconds.
123         */
124        float getHoverTime(void) const;
125
126        /*!
127        \brief
128            Set the number of seconds the tooltip should be displayed for before it automatically
129            de-activates itself.  0 indicates that the tooltip should never timesout and auto-deactivate.
130
131        \param seconds
132            float value representing a number of seconds.
133
134        \return
135            Nothing.
136         */
137        void setDisplayTime(float seconds);
138
139        /*!
140        \brief
141            Return the number of seconds that should be taken to fade the tooltip into and out of
142            visibility.
143
144        \return
145            float value representing a number of seconds.
146         */
147        float getFadeTime(void) const;
148
149        /*!
150        \brief
151            Set the number of seconds the mouse should hover stationary over the target window before
152            the tooltip gets activated.
153
154        \param seconds
155            float value representing a number of seconds.
156
157        \return
158            Nothing.
159         */
160        void setHoverTime(float seconds);
161
162        /*!
163        \brief
164            Return the number of seconds the tooltip should be displayed for before it automatically
165            de-activates itself.  0 indicates that the tooltip never timesout and auto-deactivates.
166
167        \return
168            float value representing a number of seconds.
169         */
170        float getDisplayTime(void) const;
171
172        /*!
173        \brief
174            Set the number of seconds that should be taken to fade the tooltip into and out of
175            visibility.
176
177        \param seconds
178            float value representing a number of seconds.
179
180        \return
181            Nothing.
182         */
183        void setFadeTime(float seconds);
184
185        //
186        /*!
187        \brief
188            Causes the tooltip to position itself appropriately.
189
190        \return
191            Nothing.
192        */
193        void positionSelf(void);
194
195    protected:
196        /*************************************************************************
197            Implementation Methods
198        *************************************************************************/
199        /*!
200        \brief
201            Add ScrollablePane specific events
202        */
203        void addTooltipEvents(void);
204
205        // methods to perform processing for each of the widget states
206        void doActiveState(float elapsed);
207        void doInactiveState(float elapsed);
208        void doFadeInState(float elapsed);
209        void doFadeOutState(float elapsed);
210
211        // methods to switch widget states
212        void switchToInactiveState(void);
213        void switchToActiveState(void);
214        void switchToFadeInState(void);
215        void switchToFadeOutState(void);
216
217
218                /*!
219                \brief
220                        Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
221
222                \param class_name
223                        The class name that is to be checked.
224
225                \return
226                        true if this window was inherited from \a class_name. false if not.
227                */
228                virtual bool    testClassName_impl(const String& class_name) const
229                {
230                        if (class_name==(const utf8*)"Tooltip") return true;
231                        return Window::testClassName_impl(class_name);
232                }
233
234        /*!
235        \brief
236            Return the size of the area that will be occupied by the tooltip text, given
237            any current formatting options.
238
239        \return
240            Size object describing the size of the rendered tooltip text in pixels.
241        */
242        virtual Size getTextSize() const;
243
244        /*************************************************************************
245            Event triggers
246        *************************************************************************/
247        /*!
248        \brief
249            Event trigger method called when the hover timeout gets changed.
250
251        \param e
252            WindowEventArgs object.
253
254        \return
255            Nothing.
256        */
257        virtual void onHoverTimeChanged(WindowEventArgs& e);
258
259        /*!
260        \brief
261            Event trigger method called when the display timeout gets changed.
262
263        \param e
264            WindowEventArgs object.
265
266        \return
267            Nothing.
268        */
269        virtual void onDisplayTimeChanged(WindowEventArgs& e);
270
271        /*!
272        \brief
273            Event trigger method called when the fade timeout gets changed.
274
275        \param e
276            WindowEventArgs object.
277
278        \return
279            Nothing.
280        */
281        virtual void onFadeTimeChanged(WindowEventArgs& e);
282
283        /*!
284        \brief
285            Event trigger method called just before the tooltip becomes active.
286
287        \param e
288            WindowEventArgs object.
289
290        \return
291            Nothing.
292        */
293        virtual void onTooltipActive(WindowEventArgs& e);
294
295        /*!
296        \brief
297            Event trigger method called just after the tooltip is deactivated.
298
299        \param e
300            WindowEventArgs object.
301
302        \return
303            Nothing.
304        */
305        virtual void onTooltipInactive(WindowEventArgs& e);
306
307
308        /************************************************************************
309            Overridden from Window.
310        ************************************************************************/
311        void updateSelf(float elapsed);
312        void onMouseEnters(MouseEventArgs& e);
313        void onTextChanged(WindowEventArgs& e);
314
315        /************************************************************************
316            Enumerations
317        ************************************************************************/
318        /*!
319        \brief
320            states for tooltip
321         */
322        enum TipState
323        {
324            Inactive,   //!< Tooltip is currently inactive.
325            Active,     //!< Tooltip is currently displayed and active.
326            FadeIn,     //!< Tooltip is currently transitioning from Inactive to Active state.
327            FadeOut     //!< Tooltip is currently transitioning from Active to Inactive state.
328        };
329
330        /************************************************************************
331            Data fields
332        ************************************************************************/
333        TipState    d_state;        //!< Current tooltip state.
334        float       d_elapsed;      //!< Used to track state change timings
335        const Window* d_target;     //!< Current target Window for this Tooltip.
336        float       d_hoverTime;    //!< tool-tip hover time (seconds mouse must stay stationary before tip shows).
337        float       d_displayTime;  //!< tool-tip display time (seconds that tip is showsn for).
338        float       d_fadeTime;     //!< tool-tip fade time (seconds it takes for tip to fade in and/or out).
339
340    private:
341        /*************************************************************************
342            Static Properties for this class
343        *************************************************************************/
344        static TooltipProperties::HoverTime      d_hoverTimeProperty;
345        static TooltipProperties::DisplayTime    d_displayTimeProperty;
346        static TooltipProperties::FadeTime       d_fadeTimeProperty;
347
348        /*************************************************************************
349            Private methods
350        *************************************************************************/
351        void addTooltipProperties(void);
352    };
353
354} // End of  CEGUI namespace section
355
356
357#if defined(_MSC_VER)
358#       pragma warning(pop)
359#endif
360
361#endif  // end of guard _CEGUITooltip_h_
Note: See TracBrowser for help on using the repository browser.