Difference between revisions of "Tooltips"

Revision as of 13:04, 6 March 2008

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

API References: Tooltip 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::setDefaultTooltip() one time, somehwere in your code. I would recommend calling this right after initializing the CEGUI system. Here's a sample call:

  // Create default ToolTip item
  CEGUI::System::getSingleton().setDefaultTooltip( (CEGUI::utf8*)"TaharezLook/Tooltip" );

Yep, that's all there is too it. In newer versions of CEGUI the method has been renamed to setDefaultTooltip for consistency.

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:

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.");

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:

<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>

Ensure that the Tooltip is registered in your .Scheme file

<WindowSet Filename="CEGUITaharezLook">
....
<WindowFactory Name="TaharezLook/Tooltip" />
....
</WindowSet>

Ensure that imageset contains graphics for the Tooltip

<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>

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

#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
...

Inject Time Pulse: via an Ogre::FrameListenter

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

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.