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

Formatting Tags in CEGUI

2015-04-03T15:17:04Z

Bertram: Actually, this doc is working for CEGUI 0.8.x now... :) + Precised a bit what image embedding code is for which version.

{{VersionBadge|0.8}}
{{VersionBadge|0.7}}

== Some Basics ==
CEGUI has a nice feature that allows for formatted text in a widget, called "formatting tags". Basically, you insert tags like:

[tag-name='value']

into your strings and CEGUI does the necessary parsing (see [http://www.cegui.org.uk/docs/current/classCEGUI_1_1BasicRenderedStringParser.html CEGUI::BasicRenderedStringParser] class reference for details).

It is important to note that these tags are like a 'state change', that means if you set a specific formatting option, it stays active until changed by another tag. You will see some examples later on.

== Escaping ==
Sometimes you want to just display [Something] and not regard that as a control sequence. In that case, you have to escape the '''opening bracket''' - [ - only. Example
\[Text text text]

This will display:
[Text text text]

If you want to escape the string from inside C++, you have to use \\[ but you probably know that if you know your way around C++.
In Python it's very similar to C++ but in Lua, the backslash is not an escape character, so just writing \[ should work fine (% is the escaping character in Lua).

== Available Tags ==
=== Font Colours ===
Changing the text colour in a string is quite easy, so let's start with that. In the following example, we will have some text shown in red, green and blue. Here's how the tags work:

"This is just some text that shows how nicely [colour='FFFF0000']CEGUI can format strings.[colour='FF00FF00']
and this is just colour [colour='FF0000FF'] formatting!"

In code, it looks like this:

<source lang="cpp">
CEGUI::Window* textComponent =
(CEGUI::Window*)CEGUI::WindowManager::getSingleton().getWindow("generat0r/AboutDialog/StaticText");
textComponent->setText("This is just some text that shows how nicely [colour='FFFF0000']CEGUI
can format strings.[colour='FF00FF00'] and this is just colour [colour='FF0000FF'] formatting!");
</source>

And that's how it looks in my app:

[[File:Cegui_formatting_tags_colours.png]]

A note:
* In case you have wondered why 4 sets of values are needed for each colour: Red, for example, is described by [colour='FFFF0000'] where the first 'FF' is the Alpha value (fully opaque in this case), the second is the value for the red component, the third for the green component and the fourth for the blue component, like in [AARRGGBB]

=== Font Formatting ===
Font formatting is a bit more involved as you need to have the actual fonts and the 'font' XML files defined for each style.

Let's assume you want to use the Arial font with the styles 'normal', '''italic''', ''''bold'''' and ''''''bold Italic''''''. This actually requires you to have four different Arial fonts. For Arial, the fonts are called as follows:

* Arial normal (arial.ttf)
* Arial bold (arialbd.ttf)
* Arial italic (ariali.ttf)
* Arial bold italic (arialbi.ttf)

If you want to tinker around with them you can find these and some more in the font manager app of your OS (Arial ships with Windows, so you can get them from the OS). Note that Arial is copyrighted, so you might want to use a free font for your app (check out [http://www.dafont.com/ DaFont] for example).

For each font, you will now have to create the according ".font" file that tells CEGUI how to use the font:

* Arial-10.font
<source lang="xml">
<?xml version="1.0" ?>

</source>

* Arial-Bold-10.font
<source lang="xml">
<?xml version="1.0" ?>

</source>

* Arial-Italic-10.font
<source lang="xml">
<?xml version="1.0" ?>

</source>

* Arial-BoldItalic-10.font
<source lang="xml">
<?xml version="1.0" ?>

</source>

Don't forget to add the font definitions into your scheme, like so:

<source lang="xml">
<?xml version="1.0" ?>
<GUIScheme Name="VanillaSkin">
<Imageset Filename="Vanilla.imageset" />





<LookNFeel Filename="Vanilla.looknfeel" />
..snip..
</source>

Here is the code:

<source lang="cpp">
textComponent->setText("You can also do [font='Arial-Bold-10']bold text, [font='Arial-Italic-10']italic
text, [font='Arial-BoldItalic-10']bold AND italic text.[font='Arial-10']!");
</source>

And here is how it looks in my app:

[[File:Cegui_formatting_tags_fonts.png]]

=== Embedding Images ===
Embedding an image into text is quite easy. The required tag follows the general syntax. Consider the following tag:

for CEGUI 0.7.x:
[image='set:<imageset> image:<image>']

or for CEGUI 0.8.x or later:
[image='<imageset>/<image>']

What you need to do here is specify the imageset where the image is specified and identify the image to be used. Let's assume you want to embed the MouseCursor of the TaharezLook imageset into the following text: "Nice, I can even embed images like this <mousepic here> into my text."

First you need to know the name of the imageset and the name of the image. Let's have a look at "TaharezLook.imageset" for that purpose:

<source lang="xml">
<?xml version="1.0" ?>
<Imageset Name="TaharezLook" Imagefile="TaharezLook.tga" NativeHorzRes="800" NativeVertRes="600"
AutoScaled="true">
...
<Image Name="MouseArrow" XPos="138" YPos="127" Width="31" Height="25" XOffset="0" YOffset="0" />
...
</Imageset>
</source>

So the imageset is named "TaharezLook" and the wanted image is called "MouseArrow". In code this would now look like follows:

<source lang="cpp">
textComponent->setText("Nice, I can even embed images like this [image='set:TaharezLook image:MouseArrow']
into my text. ");
</source>

And this is how it looks in my App:

[[File:Cegui_formatting_tags_image embed.png]]

Please note: The following tags have an effect on the way the image is drawn: 'padding', 'alignment' and 'colour'.

=== Image Size ===
The 'image-size' tag allows you to change the size of embedded image components. The sizes in the tag are given in pixels and the format is as follows:

w:<width value> h:<height value>

which specifies the width and height of a following image. So to set the size of a subsequent image to 32 pixels height and 64 pixels width, you would use:

[image-size='w:32 h:64']

Here is how it might look in code:

<source lang="cpp">
textComponent->setText("Nice, I can even embed images like this [image-size='w:32 h:64']
[image='set:TaharezLook image:MouseArrow'] into my text.");
</source>

And here is how it looks in my app:

[[File:Cegui_formatting_tags_image size.png]]

Please note: To set the image-size back to the real size of the image, just set the values to zero, like so: [image-size='w:0 h:0']

=== Vertical Alignment ===
The vertical alignment tag allows you align elements within a text that have different heights. The overall available space on a line is always taken as the height of the tallest element plus any vertical padding, elements are then positioned within this vertical space according to the specified option. Currently, you can align an element to 'top', 'bottom', 'centre' and 'stretch'. The option 'stretch' will stretch the tagged elements vertically to fill the available space. Please note that the stretching is vertical only, aspect ratios of images and text are not maintained! This will be accounted for in the future, though.

The following examples are valid tags for "vert-alignment":

[vert-alignment='top']
[vert-alignment='bottom']
[vert-alignment='centre']
[vert-alignment='stretch']

Here is the code:

<source lang="cpp">
textComponent->setText("Text can also be vertically aligned. It can be aligned to [vert-alignment='top']top,
[vert-alignment='bottom']bottom, [vert-alignment='centre']centre and [vert-alignment='stretch']'stretch'");
</source>

And here how it looks in my app:

[[File:Cegui_formatting_tags_vertalign.png]]

Please note: Embedded window elements cannot be stretched currently. This may also change in the future.

=== Padding ===
Padding is related to the vertical alignment tag in that it also allows you to specify the setting of elements in a text. You can set individual text elements or the whole text all together. The value you give the padding tag are a number of pixels to pad the surrounding elements with. The padding tag uses a "rect" property to specify padding values, like so: 'l:<value> t:<value> r:<value> b:<value>) where "l" stands for "left padding, "t" stands for "top padding", "r" stands for "right padding" and "b" stands for "bottom padding".

Consider the following sample text: ''"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. THIS IS PADDED. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."''

Our aim is to pad the text element "THIS IS PADDED" with 5 pixels of left and right padding and 10 pixels of top and bottom padding. The tag would look like this:

[padding='l:5 t:10 r:5 b:10']

Use padding, for example to provide extra spacing when embedding a picture or window in text.
Here is the code sample:

<source lang="cpp">
textComponent->setText("Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquip ex ea commodo consequat. [padding='l:5 t:10 r:5 b:10']THIS IS PADDED.[padding='l:0 t:0
r:0 b:0'] Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id
est laborum.");
</source>

And here is how it looks like in my app:

[[File:Cegui_formatting_tags_padding.png]]

Please note: Don't try to translate the latin here – its complete nonsense. The "Lorem Ipsum" text has been around since the 1500s, when an unknown printer defined it as a dummy text to make a type specimen book, and it's still in use today. Strange but true.

=== Window ===
The 'window' tag manipulates an existing child window of the window that you set the text on, such that the window is drawn in-line with the text, which means it moves with the text automatically. The 'window' tag takes the full name of the window just as you would use it with CEGUI::WindowManager. While the named window can be any window, it only makes sense to reference windows that are attached to the window where the text will be rendered.

So let us embed a button into our text!

First, we define the window in our layout:

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<GUILayout >
<Window Type="Vanilla/FrameWindow" Name="generat0r/AboutDialog" >
<Property Name="Text" Value="About generat0r" />
<Property Name="TitlebarFont" Value="Arial-14" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="CloseButtonEnabled" Value="False" />
<Property Name="SizingEnabled" Value="False" />
<Property Name="UnifiedAreaRect" Value="{{0.015,0},{0.015,0},{0.45,0},{0.40,0}}" />
<Property Name="UnifiedPosition" Value="{ {0.25, 0}, {0.25, 0} }" />

<Window Type="Vanilla/StaticText" Name="generat0r/AboutDialog/StaticText" >
<Property Name="Text" Value="Demonstrates static (non editable) text. Use the controls on your right for
formatting options." />
<Property Name="HorzExtent" Value="361" />
<Property Name="VertExtent" Value="59.5854" />
<Property Name="HorzFormatting" Value="WordWrapLeftAligned" />
<Property Name="VertFormatting" Value="TopAligned" />
<Property Name="UnifiedAreaRect" Value="{{0.03,0},{0.03,0},{0.97,0},{0.85,0}}" />

<Window Type="Vanilla/Button" Name="generat0r/AboutDialog/EmbeddedButton"
<Property Name="Text" Value="Embedded" />
<Property Name="UnifiedAreaRect" Value="{{0.42,0},{0.88,0},{0.60,0},{0.955,0}}" />
</Window>
</Window>
<Window Type="Vanilla/Button" Name="generat0r/AboutDialog/CloseButton" >
<Property Name="Text" Value="Close" />
<Property Name="UnifiedAreaRect" Value="{{0.42,0},{0.88,0},{0.60,0},{0.955,0}}" />
</Window>
</Window>
</GUILayout>
</source>

Pay special attention to the cut out segment in the above layout! Please also note that the window I want to embed is a child of the text window.

Our tag will look like this:

[window='generat0r/AboutDialog/EmbeddedButton']

Now, you just need to embed the defined window ("generat0r/AboutDialog/EmbeddedButton") into the string, like so:

<source lang="cpp">
textComponent->setText("Lorem ipsum dolor sit amet, consectetur adipisicing elit,sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
[window='generat0r/AboutDialog/EmbeddedButton']laboris nisi ut aliquip ex ea commodo consequat. THIS IS
PADDED. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est
laborum.");
</source>

And here is how it looks in my app:

[[File:Cegui_formatting_tags_window.png]]

The window tag works fine with formatting options for text. Please consider, though, that the embedded window is treated as a single entity. So if you embed a window that just draws text, the text of that window will not be split for wrapping purposes, but might have its own formatting! Padding and vertical alignments work here as well, with the exception of the 'stretch' option (which will default to 'centre' and raise a note in the CEGUI.log)

Note: If you have not created the window you call here, you will get an 'unknown object' exception!

== Demo Video ==
<youtube size="medium">eRC5R9aA_Zs</youtube>
Dont forget to check out the demo video: [[http://www.youtube.com/watch?v=eRC5R9aA_Zs&feature=player_embedded Tag Formatting Demo]]

== Feedback ==
Feedback is very welcome: please just PM me in the forum (my handle is 'mboeni') or leave a comment here in the wiki. :)

[[User:Mboeni]] 13:33, 24 September 2010 (UTC)

[[User:EsotericDude]] How do you display a left bracket since it initiates a tag?

[[Category:Manuals]]

Formatting Tags in CEGUI

2015-04-03T15:14:34Z

Bertram: /* Embedding Images */ Added info about how to do it in CEGUI 0.8.x

{{VersionBadge|0.7}}

== Some Basics ==
CEGUI has a nice feature that allows for formatted text in a widget, called "formatting tags". Basically, you insert tags like:

[tag-name='value']

into your strings and CEGUI does the necessary parsing (see [http://www.cegui.org.uk/docs/current/classCEGUI_1_1BasicRenderedStringParser.html CEGUI::BasicRenderedStringParser] class reference for details).

It is important to note that these tags are like a 'state change', that means if you set a specific formatting option, it stays active until changed by another tag. You will see some examples later on.

== Escaping ==
Sometimes you want to just display [Something] and not regard that as a control sequence. In that case, you have to escape the '''opening bracket''' - [ - only. Example
\[Text text text]

This will display:
[Text text text]

If you want to escape the string from inside C++, you have to use \\[ but you probably know that if you know your way around C++.
In Python it's very similar to C++ but in Lua, the backslash is not an escape character, so just writing \[ should work fine (% is the escaping character in Lua).

== Available Tags ==
=== Font Colours ===
Changing the text colour in a string is quite easy, so let's start with that. In the following example, we will have some text shown in red, green and blue. Here's how the tags work:

"This is just some text that shows how nicely [colour='FFFF0000']CEGUI can format strings.[colour='FF00FF00']
and this is just colour [colour='FF0000FF'] formatting!"

In code, it looks like this:

<source lang="cpp">
CEGUI::Window* textComponent =
(CEGUI::Window*)CEGUI::WindowManager::getSingleton().getWindow("generat0r/AboutDialog/StaticText");
textComponent->setText("This is just some text that shows how nicely [colour='FFFF0000']CEGUI
can format strings.[colour='FF00FF00'] and this is just colour [colour='FF0000FF'] formatting!");
</source>

And that's how it looks in my app:

[[File:Cegui_formatting_tags_colours.png]]

A note:
* In case you have wondered why 4 sets of values are needed for each colour: Red, for example, is described by [colour='FFFF0000'] where the first 'FF' is the Alpha value (fully opaque in this case), the second is the value for the red component, the third for the green component and the fourth for the blue component, like in [AARRGGBB]

=== Font Formatting ===
Font formatting is a bit more involved as you need to have the actual fonts and the 'font' XML files defined for each style.

Let's assume you want to use the Arial font with the styles 'normal', '''italic''', ''''bold'''' and ''''''bold Italic''''''. This actually requires you to have four different Arial fonts. For Arial, the fonts are called as follows:

* Arial normal (arial.ttf)
* Arial bold (arialbd.ttf)
* Arial italic (ariali.ttf)
* Arial bold italic (arialbi.ttf)

If you want to tinker around with them you can find these and some more in the font manager app of your OS (Arial ships with Windows, so you can get them from the OS). Note that Arial is copyrighted, so you might want to use a free font for your app (check out [http://www.dafont.com/ DaFont] for example).

For each font, you will now have to create the according ".font" file that tells CEGUI how to use the font:

* Arial-10.font
<source lang="xml">
<?xml version="1.0" ?>

</source>

* Arial-Bold-10.font
<source lang="xml">
<?xml version="1.0" ?>

</source>

* Arial-Italic-10.font
<source lang="xml">
<?xml version="1.0" ?>

</source>

* Arial-BoldItalic-10.font
<source lang="xml">
<?xml version="1.0" ?>

</source>

Don't forget to add the font definitions into your scheme, like so:

<source lang="xml">
<?xml version="1.0" ?>
<GUIScheme Name="VanillaSkin">
<Imageset Filename="Vanilla.imageset" />





<LookNFeel Filename="Vanilla.looknfeel" />
..snip..
</source>

Here is the code:

<source lang="cpp">
textComponent->setText("You can also do [font='Arial-Bold-10']bold text, [font='Arial-Italic-10']italic
text, [font='Arial-BoldItalic-10']bold AND italic text.[font='Arial-10']!");
</source>

And here is how it looks in my app:

[[File:Cegui_formatting_tags_fonts.png]]

=== Embedding Images ===
Embedding an image into text is quite easy. The required tag follows the general syntax. Consider the following tag:

[image='set:<imageset> image:<image>']

or for CEGUI 0.8.x or later:
[image='<imageset>/<image>']

What you need to do here is specify the imageset where the image is specified and identify the image to be used. Let's assume you want to embed the MouseCursor of the TaharezLook imageset into the following text: "Nice, I can even embed images like this <mousepic here> into my text."

First you need to know the name of the imageset and the name of the image. Let's have a look at "TaharezLook.imageset" for that purpose:

<source lang="xml">
<?xml version="1.0" ?>
<Imageset Name="TaharezLook" Imagefile="TaharezLook.tga" NativeHorzRes="800" NativeVertRes="600"
AutoScaled="true">
...
<Image Name="MouseArrow" XPos="138" YPos="127" Width="31" Height="25" XOffset="0" YOffset="0" />
...
</Imageset>
</source>

So the imageset is named "TaharezLook" and the wanted image is called "MouseArrow". In code this would now look like follows:

<source lang="cpp">
textComponent->setText("Nice, I can even embed images like this [image='set:TaharezLook image:MouseArrow']
into my text. ");
</source>

And this is how it looks in my App:

[[File:Cegui_formatting_tags_image embed.png]]

Please note: The following tags have an effect on the way the image is drawn: 'padding', 'alignment' and 'colour'.

=== Image Size ===
The 'image-size' tag allows you to change the size of embedded image components. The sizes in the tag are given in pixels and the format is as follows:

w:<width value> h:<height value>

which specifies the width and height of a following image. So to set the size of a subsequent image to 32 pixels height and 64 pixels width, you would use:

[image-size='w:32 h:64']

Here is how it might look in code:

<source lang="cpp">
textComponent->setText("Nice, I can even embed images like this [image-size='w:32 h:64']
[image='set:TaharezLook image:MouseArrow'] into my text.");
</source>

And here is how it looks in my app:

[[File:Cegui_formatting_tags_image size.png]]

Please note: To set the image-size back to the real size of the image, just set the values to zero, like so: [image-size='w:0 h:0']

=== Vertical Alignment ===
The vertical alignment tag allows you align elements within a text that have different heights. The overall available space on a line is always taken as the height of the tallest element plus any vertical padding, elements are then positioned within this vertical space according to the specified option. Currently, you can align an element to 'top', 'bottom', 'centre' and 'stretch'. The option 'stretch' will stretch the tagged elements vertically to fill the available space. Please note that the stretching is vertical only, aspect ratios of images and text are not maintained! This will be accounted for in the future, though.

The following examples are valid tags for "vert-alignment":

[vert-alignment='top']
[vert-alignment='bottom']
[vert-alignment='centre']
[vert-alignment='stretch']

Here is the code:

<source lang="cpp">
textComponent->setText("Text can also be vertically aligned. It can be aligned to [vert-alignment='top']top,
[vert-alignment='bottom']bottom, [vert-alignment='centre']centre and [vert-alignment='stretch']'stretch'");
</source>

And here how it looks in my app:

[[File:Cegui_formatting_tags_vertalign.png]]

Please note: Embedded window elements cannot be stretched currently. This may also change in the future.

=== Padding ===
Padding is related to the vertical alignment tag in that it also allows you to specify the setting of elements in a text. You can set individual text elements or the whole text all together. The value you give the padding tag are a number of pixels to pad the surrounding elements with. The padding tag uses a "rect" property to specify padding values, like so: 'l:<value> t:<value> r:<value> b:<value>) where "l" stands for "left padding, "t" stands for "top padding", "r" stands for "right padding" and "b" stands for "bottom padding".

Consider the following sample text: ''"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. THIS IS PADDED. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."''

Our aim is to pad the text element "THIS IS PADDED" with 5 pixels of left and right padding and 10 pixels of top and bottom padding. The tag would look like this:

[padding='l:5 t:10 r:5 b:10']

Use padding, for example to provide extra spacing when embedding a picture or window in text.
Here is the code sample:

<source lang="cpp">
textComponent->setText("Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquip ex ea commodo consequat. [padding='l:5 t:10 r:5 b:10']THIS IS PADDED.[padding='l:0 t:0
r:0 b:0'] Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id
est laborum.");
</source>

And here is how it looks like in my app:

[[File:Cegui_formatting_tags_padding.png]]

Please note: Don't try to translate the latin here – its complete nonsense. The "Lorem Ipsum" text has been around since the 1500s, when an unknown printer defined it as a dummy text to make a type specimen book, and it's still in use today. Strange but true.

=== Window ===
The 'window' tag manipulates an existing child window of the window that you set the text on, such that the window is drawn in-line with the text, which means it moves with the text automatically. The 'window' tag takes the full name of the window just as you would use it with CEGUI::WindowManager. While the named window can be any window, it only makes sense to reference windows that are attached to the window where the text will be rendered.

So let us embed a button into our text!

First, we define the window in our layout:

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<GUILayout >
<Window Type="Vanilla/FrameWindow" Name="generat0r/AboutDialog" >
<Property Name="Text" Value="About generat0r" />
<Property Name="TitlebarFont" Value="Arial-14" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="CloseButtonEnabled" Value="False" />
<Property Name="SizingEnabled" Value="False" />
<Property Name="UnifiedAreaRect" Value="{{0.015,0},{0.015,0},{0.45,0},{0.40,0}}" />
<Property Name="UnifiedPosition" Value="{ {0.25, 0}, {0.25, 0} }" />

<Window Type="Vanilla/StaticText" Name="generat0r/AboutDialog/StaticText" >
<Property Name="Text" Value="Demonstrates static (non editable) text. Use the controls on your right for
formatting options." />
<Property Name="HorzExtent" Value="361" />
<Property Name="VertExtent" Value="59.5854" />
<Property Name="HorzFormatting" Value="WordWrapLeftAligned" />
<Property Name="VertFormatting" Value="TopAligned" />
<Property Name="UnifiedAreaRect" Value="{{0.03,0},{0.03,0},{0.97,0},{0.85,0}}" />

<Window Type="Vanilla/Button" Name="generat0r/AboutDialog/EmbeddedButton"
<Property Name="Text" Value="Embedded" />
<Property Name="UnifiedAreaRect" Value="{{0.42,0},{0.88,0},{0.60,0},{0.955,0}}" />
</Window>
</Window>
<Window Type="Vanilla/Button" Name="generat0r/AboutDialog/CloseButton" >
<Property Name="Text" Value="Close" />
<Property Name="UnifiedAreaRect" Value="{{0.42,0},{0.88,0},{0.60,0},{0.955,0}}" />
</Window>
</Window>
</GUILayout>
</source>

Pay special attention to the cut out segment in the above layout! Please also note that the window I want to embed is a child of the text window.

Our tag will look like this:

[window='generat0r/AboutDialog/EmbeddedButton']

Now, you just need to embed the defined window ("generat0r/AboutDialog/EmbeddedButton") into the string, like so:

<source lang="cpp">
textComponent->setText("Lorem ipsum dolor sit amet, consectetur adipisicing elit,sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
[window='generat0r/AboutDialog/EmbeddedButton']laboris nisi ut aliquip ex ea commodo consequat. THIS IS
PADDED. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est
laborum.");
</source>

And here is how it looks in my app:

[[File:Cegui_formatting_tags_window.png]]

The window tag works fine with formatting options for text. Please consider, though, that the embedded window is treated as a single entity. So if you embed a window that just draws text, the text of that window will not be split for wrapping purposes, but might have its own formatting! Padding and vertical alignments work here as well, with the exception of the 'stretch' option (which will default to 'centre' and raise a note in the CEGUI.log)

Note: If you have not created the window you call here, you will get an 'unknown object' exception!

== Demo Video ==
<youtube size="medium">eRC5R9aA_Zs</youtube>
Dont forget to check out the demo video: [[http://www.youtube.com/watch?v=eRC5R9aA_Zs&feature=player_embedded Tag Formatting Demo]]

== Feedback ==
Feedback is very welcome: please just PM me in the forum (my handle is 'mboeni') or leave a comment here in the wiki. :)

[[User:Mboeni]] 13:33, 24 September 2010 (UTC)

[[User:EsotericDude]] How do you display a left bracket since it initiates a tag?

[[Category:Manuals]]

Tooltips

2014-11-24T13:28:27Z

Bertram: Added the right statement to create a tooltip on the 0.8 version and fixed the one used for 0.5-0.7 versions. Added a few comments about certain statement used on 0.8 only.

{{VersionBadge|0.5}} {{VersionBadge|0.6}}

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

<source lang="cpp">
// Create default ToolTip item
// On the 0.5, 0.6 and 0.7 versions only
CEGUI::System::getSingleton().setDefaultTooltip( (CEGUI::utf8*)"TaharezLook/Tooltip" );
// On the 0.8 version only
CEGUI::System::getSingleton().getDefaultGUIContext().setDefaultTooltipType( (CEGUI::utf8*)"TaharezLook/Tooltip" );
</source>

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:
<source lang="cpp">
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.");
</source>

'''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:
<source lang="xml">
<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>

</source>

'''Ensure that the Tooltip is registered in your .Scheme file'''
<source lang="xml">
<WindowSet Filename="CEGUITaharezLook">
....
<WindowFactory Name="TaharezLook/Tooltip" />
....
</WindowSet>
</source>

'''Ensure that imageset contains graphics for the Tooltip'''
<source lang="xml">
<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>
</source>

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

'''Inject Time Pulse'''

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. Both CEGUI::System and GUI Contextes must be injected. The best place to inject a time pulse into the CEGUI is in a main loop. Here are a couple of examples of how to implement this:

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

<source lang="cpp">
#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() )
{
clock_t now = clock();
CEGUI::System::getSingleton().injectTimePulse( ( now - mLastTimeInjection ) * 0.001f );
// From the 0.8 version (next to the line above)
CEGUI::System::getSingleton().getDefaultGUIContext().injectTimePulse( ( now - mLastTimeInjection ) * 0.001f );
mLastTimeInjection = clock();
} // CEGUI Time pulse
...
} // while
...
</source>

'''Inject Time Pulse: In C++11'''
<source lang="cpp">
#include <chrono>
...
typedef std::chrono::duration<float, std::chrono::seconds::period> fpTime;
std::chrono::high_resolution_clock::time_point last_time=std::chrono::high_resolution_clock::now();
...
// Your main loop
while ( true ){

{
CEGUI::System& system = CEGUI::System::getSingleton();
auto begin = std::chrono::high_resolution_clock::now();
float elapsed = fpTime(begin - last_time).count();

system.injectTimePulse( elapsed );
// From the 0.8 version (next to the line above)
system.getDefaultGUIContext().injectTimePulse( elapsed );

last_time = begin;

}

} // while
...
</source>

'''Inject Time Pulse: via an Ogre::FrameListenter'''
<source lang="cpp">

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)
// From the 0.8 version (next to the line above)
CEGUI::System::getSingleton().getDefaultGUIContext().injectTimePulse( evt.timeSinceLastFrame );
...
return true;
} //frameStarted

</source>

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.

== How to offset the ''Tooltip'' so it doesn't render under the mouse ==

'''Via LookNFeel animation'''

One way to do this is to edit your scheme's looknfeel and change the Tooltip's FadeIn animation to affect the Position property too.
If the tooltip doesn't have a FadeIn animation, just add one.

Example:
<source lang="xml">
<WidgetLook name="TaharezLook/Tooltip">
...
<AnimationDefinition name="FadeIn" duration="0.33" replayMode="once">
...
<Affector property="Position" interpolator="UVector2" applicationMethod="relative">
<KeyFrame position="0" value="{{0,12},{0,0}}" />
</Affector>
...
</AnimationDefinition>
...
</WidgetLook>
</source>
This will offset the tooltip's x by 12 pixels (in my case, that's how wide my system mouse cursor is -- modify to suit your needs).

== 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''.

[[Category:Tutorials]]
[[Category:Update requested]]