Tooltips

2006-04-12T06:53:05Z

Slog: /* Setting the ''Tootip'' text to display */

I am not an expert but I would like to share what I have learned and gleaned about the ''Tooltip'' widget.

API References:
[http://www.cegui.org.uk/api_reference/classCEGUI_1_1Tooltip.html Tooltip]
[http://www.cegui.org.uk/api_reference/classCEGUI_1_1System.html System]

As you would expect, the ''Tooltip'' works very similar to most tooltip systems. Basically the user hovers the mouse over a CEGUI widget and when a specified time has elapsed the tooltip is displayed for a specified amount of time. As with most of the CEGUI widgets the ''Tooltip'' widget is based upon the CEGUI ''Window'' class widget.

''Please note that the following example source code was gleaned and edited from project specific code so there may be some syntax errors.''

== Creating the Default System ''Tootip'' widget ==

CEGUI will manage a single default, system wide ''Tooltip'' widget for you that will take care of displaying your tooltip text. You have to initialize it by calling '''CEGUI::System::setTooltip()'' one time, somehwere in your code. I would recommend calling this right after initializing the CEGUI system. Here's a sample call:

<pre>
// Create default ToolTip item
CEGUI::System::getSingleton().setTooltip( (CEGUI::utf8*)"TaharezLook/Tooltip" );
</pre>

Yep, that's all there is too it.

== Setting the ''Tootip'' text to display ==

There are two methods for setting your tooltip text: In your code or in your layout file.

'''Setting the ''Tooltip'' text in your code'''

You can hardcode toolip text in your code by using the ''WindowObject::setTooltipText()'' function like so:
<pre>
CEGUI::PushButton *mPushButton = (CEGUI::PushButton *)mWinMgr->createWindow(
(CEGUI::utf8*)"TaharezLook/PushButton", (CEGUI::utf8*)"PushButton");
// Set other properties like size, position, etc.
mPushButton->setTooltipText("This is a tooltip.");
</pre>

'''Setting the ''Tooltip'' text in your layout (xml) file'''

The prefered method is to set the tooltip text in your layout file and you can do it like so:
<pre>
<Window Type="TaharezLook/Editbox" Name="Login/EditBox/Password">
<Property Name="AbsoluteRect" Value="l:128.000000 t:0.000000 r:486.000000 b:46.000000" />
<Property Name="AlwaysOnTop" Value="True" />
<Property Name="RelativeRect" Value="l:0.250000 t:0.000000 r:0.950000 b:1.000000" />
<Property Name="Text" Value="{Enter Password Here}" />
<Property Name="Tooltip" Value="Enter your password here." />
</Window>

</pre>

'''Ensure that the Tooltip is registered in your .Scheme file'''
<pre>
<WindowSet Filename="CEGUITaharezLook">
....
<WindowFactory Name="TaharezLook/Tooltip" />
....
</WindowSet>
</pre>
'''Ensure that imageset contains graphics for the Tooltip'''
<pre>
<Imageset Name="TaharezLook" Imagefile="TaharezLook.png" NativeHorzRes="800" NativeVertRes="600" AutoScaled="true">
....
<Image Name="TooltipLeftEdge" XPos="217" YPos="225" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipRightEdge" XPos="246" YPos="225" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipTopEdge" XPos="224" YPos="218" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipBottomEdge" XPos="224" YPos="248" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipTopLeft" XPos="217" YPos="218" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipTopRight" XPos="246" YPos="218" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipBottomLeft" XPos="217" YPos="248" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipBottomRight" XPos="246" YPos="248" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipMiddle" XPos="2" YPos="2" Width="64" Height="64" XOffset="0" YOffset="0"/>
...
</Imageset>
</pre>

== How to display the ''Tooltip'' ==

'''Inject Time Pulse'''

''CEGUI::System::injectTimePulse(float timeElapsed)''

This is a very important piece of information that is not well documented in the current CEGUI system: ''Time Pulse Injection''. The CEGUI system, to my knowledge, does not keep track of time for you by itself - it needs help. You must inject into the CEGUI System elapsed time. If you don't do this, then your ''Tooltip'' and other time sensitive window events (like fades, etc) will not work or will not work properly. What is the ''value'' you inject? The ''value'' should be the amount of time that has elapsed since the previous injection call. Refer to the ''CEGUI::System::injectTimePulse()''. The best place to inject a time pulse into the CEGUI system is in a main loop. Here are a couple of examples of how to implement this:

'''Inject Time Pulse: via a MAIN Loop'''

<pre>

#include <time.h>
...
clock_t mLastTimeInjection=clock();
...
// Your main loop
while ( true )
{
...
// Make sure the CEGUI System is initialized and running
// and if it is, inject a time pulse
if ( CEGUI::System::getSingletonPtr() )
{
CEGUI::System::getSingleton().injectTimePulse( ( clock() - mLastTimeInjection ) * 0.001f );
mLastTimeInjection = clock();
} // CEGUI Time pulse
...
} // while
...

</pre>

'''Inject Time Pulse: via an Ogre::FrameListenter'''
<pre>

bool clsMyFrameListener::frameStarted(const Ogre::FrameEvent& evt)
{
...
// Make sure the CEGUI System is initialized and running
// and if it is, inject a time pulse
if ( CEGUI::System::getSingletonPtr() )
CEGUI::System::getSingleton().injectTimePulse( evt.timeSinceLastFrame );
...
return true;
} //frameStarted

</pre>

The finer the resolution of the injection, the better your fades will look. Injecting time every one second or greater will make your ''fades'' just popup instead of ''fading'' in.

== Conclusion ==

That's really all there is to it. My biggest ''gotcha'' was the not knowing about the ''CEGUI::System::injectTimePulse()'' and how important it was. Once I stumbled upon that everything else fell into place.

Some advanced notes. You can have more than one ''Tooltip'' widget. There maybe some scenerios where just one ''Tooltip'' widget won't work (like for a different look and feel from that of the default one, etc.). You can create another ''Tooltip'' widget using the standard CEGUI method for creating all the window widgets then use the ''CEGUI::Window::setToolTip()'' function to set the widget to use the desired ''Tooltip''.

CEGUI Wiki - Crazy Eddie's GUI System (Open Source) - User contributions [en]

Tooltips