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

CEGUI In Practice - Auto Repeat Key

2014-03-30T08:30:46Z

Superpws:

{{VersionBadge|0.8}}
{{Series|CEGUI In Practice|8}}

== Auto Key==

== CEGUI In Practice 8 ==

This tutorial will build upon a previous tutorial we looked at, [[CEGUI_In_Practice_-_Managing_input | Managing Input]].

If you've done any thing involving a keyboard recently, you'll have noticed how much you rely on RepeatKeys. For example, when you hold down the backspace to delete something you typed, thats a RepeatKey. CEGUI does not handle this automatically, as it is a GUI Library, not an input library. And since CEGUI only takes single inputs, we need to do some work on our own. I recently stumbled across an example on another website (See references) that was a good example of this. So we'll implement it ourselves to see how to use it with CEGUI. Below is the code.

===The Header File===

<source lang="cpp">
#pragma once

#include <OIS.h>

class AutoRepeatKey {
private:

OIS::KeyCode m_nKey;
unsigned int m_nChar;

float m_fElapsed;
float m_fDelay;

float m_fRepeatDelay;
float m_fInitialDelay;

protected:

virtual void repeatKey(OIS::KeyCode a_nKey, unsigned int a_nChar) = 0;

public:

AutoRepeatKey(float a_fRepeatDelay = 0.035f, float a_fInitialDelay = 0.300f);

void begin(const OIS::KeyEvent &evt);

void end(const OIS::KeyEvent &evt);

void update(float a_fElapsed); // Elapsed time in seconds
};
</source>

===The CPP File===

<source lang="cpp">
#include "AutoRepeatKey.h"

AutoRepeatKey::AutoRepeatKey(float a_fRepeatDelay, float a_fInitialDelay):
m_nKey(OIS::KC_UNASSIGNED),
m_fRepeatDelay(a_fRepeatDelay),
m_fInitialDelay(a_fInitialDelay)
{}

void AutoRepeatKey::begin(const OIS::KeyEvent &evt) {
m_nKey = evt.key;
m_nChar = evt.text;

m_fElapsed = 0;
m_fDelay = m_fInitialDelay;
}

void AutoRepeatKey::end(const OIS::KeyEvent &evt) {
if (m_nKey != evt.key) return;

m_nKey = OIS::KC_UNASSIGNED;
}

void AutoRepeatKey::update(float a_fElapsed) {
if (m_nKey == OIS::KC_UNASSIGNED) return;

m_fElapsed += a_fElapsed;
if (m_fElapsed < m_fDelay) return;

m_fElapsed -= m_fDelay;
m_fDelay = m_fRepeatDelay;

do {
repeatKey(m_nKey, m_nChar);

m_fElapsed -= m_fRepeatDelay;
} while (m_fElapsed >= m_fRepeatDelay);

m_fElapsed = 0;
}
</source>

=== Understanding the Code ===

if you think about how an auto key works there is a sequence of events that take place. The key is pressed down and held for a certain period of time. After that threshold of time with the key down is hit, it begins to press that key every so often. Then once the key is released, it will stop injecting key inputs.

=== Applying our knowledge ===
Pretty straight forward. So lets do some implementation.

Previously we wrote a few lines of code that injected input to CEGUI. Because there is a virtual function located in AutoRepeatKey we have to create a definition of that. We'll have to create a custom class, and then inherit AutoRepatKey:

<source lang="cpp">
class MyInput : public AutoRepeatKey
public:
void InjectOISKey(bool bButtonDown, OIS::KeyEvent inKey)
{
if (bButtonDown)
{
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyDown(inKey.key);
CEGUI::System::getSingleton().getDefaultGUIContext().injectChar(inKey.text);
}
else
{
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyUp(inKey.key);
}
};

protected:
void repeatKey(OIS::KeyCode a_nKey, unsigned int a_nChar){};
</source>

This is what we're gonna start with. Its pretty simple. Right now the program will compile, but do nothing different than the previous time we visited the Input Tutorial.

Now, we decided that we need to acknowledge the KeyDown as the start of the autokey, and the keyup as the ending. InjectOISKey is where we actually deal with the key being up or down, so lets mark our start and stop of the autokey detection there. Change the InjectOISKey function to be as follows

<source lang="cpp">
void InjectOISKey(bool bButtonDown, OIS::KeyEvent inKey)
{
if (bButtonDown)
{
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyDown(inKey.key);
CEGUI::System::getSingleton().getDefaultGUIContext().injectChar(inKey.text);
begin(inKey); // <---- New line: Trigger beginning of AutoKeyRepeat
}
else
{
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyUp(inKey.key);
end(inKey); // <----- New Line: Trigger end of AutoKeyRepeat
}
};
</source>

Those will start and stop the internal timers for the autokeyrepeat.

Now we need to determine how exactly we will handle each of the key repeats. This will be pretty simple, as we just need to do the same stuff we normally do during a keypress. Inject the KeyDown to CEGUI, inject the Char, inject the KeyUp. Tho we don't want to just call the above function again or it would call begin/end and stuff could get strange and ugly.

Here is the definition of repeatKey we will use

<source lang="cpp">
void repeatKey(OIS::KeyCode a_nKey, unsigned int a_nChar)
{
// Now remember the key is still down, so we need to simulate the key being released, and then repressed immediatly
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyUp(a_nKey.key); // Key UP
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyDown(a_nKey.key); // Key Down
CEGUI::System::getSingleton().getDefaultGUIContext().injectChar(a_nChar); // What that key means
};
</source>

Now repeatKey will be called once the key has been depressed longer than our initial delay time, and will be called again for everytime the delay between keyrepeats has been met. But we need to tell this autokey about it. So somehwere in your code (probably around your Polling calls) you will want to call:
<source lang="cpp">
MyInput::update(float inTimeDelta);
</source>

You may want to add some functions to AutoRepeatKey to allow you to adjust m_fRepeatDelay and m_fInitialDelay. right now they are adjusted by the constructor of AutoRepeatKey which may not be optimal for your implementation.

==== Conclusion ====

Well there you have it, stolen and ripped code implemented into our input handler. But then again, you're using CEGUI so using foreign and alien code shouldn't be anything daunting!

Till next time!

== References ==

http://www.ogre3d.org/tikiwiki/Auto+Repeat+Key+Input

[[Category:Tutorials]]

CEGUI In Practice - User Data

2014-03-30T08:25:45Z

Superpws:

{{VersionBadge|0.8}}
{{Series|CEGUI In Practice|7}}

== CEGUI InPractice 7 ==

This tutorial will be a short tutorial, as i will show how to do a small addon to the previous tutorial [[CEGUI In Practice - A Game Console]] showing you how to associate the ConsoleRoot with our GameConsoleWindow class. While not terribly useful in this situation, it can demonstrate a useful feature that you likely will use in your own game.

==== UserData ====

User data in CEGUI is basically a void pointer. This allows you to assign a custom structure or variable to each cegui window. This is extremely useful as it allows you to greater incorporate CEGUI into your development. For the previous example we created a Class to encompass our Console window which was great as it allowed us to easily encapsulate all the CEGUI windows and their handlers into a neat and easy to use function. It was pretty easy to go from GameConsoleWindow to each of the classes (by accessing the m_ConsoleWindow in the class and getChild() method). However, its not so easy to from the CEGUI::Window back up to the class level without recompiling CEGUI and creating custom widgets, unless you use userData.

Its almost so easy to use that its a waste of wiki space to show this, but regardless I see alot of posts about it on the IRC channel. Here is a line we would add to our CreateCEGUIWindow(); function.

<source lang="cpp">
void GameConsoleWindow::CreateCEGUIWindow()
{

...

CEGUI::System::getSingleton().getDefaultGUIContext().getRootWindow()->addChild(m_ConsoleWindow);
(this)->RegisterHandlers();
m_ConsoleWindow->setUserData(this); // <------ Add this line
...
}
</source>

That adds a pointer to the class we're currently in, which is an instance of GameConsoleWindow. Note tho, it stores this as a void* so when we go back to this pointer later, it will not know what type of data this is, so you will need to cast it back:

<source lang="cpp">
GameConsoleWindow *ConsoleClass = NULL;

ConsoleClass = static_cast<GameConsoleWindow*>(m_ConsoleWindow->getUserData());
</source>

This will convert the void* we stored above, into the ConsoleClass pointer. You could probably use dynamic_cast but then you'd need to turn on RTT, which is not always required for performance reasons. Regardless you can see how easily this is done. We will use this in a later tutorial demonstrating how to implement an inventory system.

Until next time..

[[Category:Tutorials]]

Category:CEGUI In Practice series

2014-03-30T08:23:19Z

Superpws:

{{VersionBadge|0.8}}

Nice tutorial series by [User:Avengre] going over CEGUI concepts without delving too much into detail. Very good introductory material.

[[Category:Tutorials]]
[[Category:Series]]

CEGUI In Practice - Using .layout files

2014-03-30T08:22:23Z

Superpws:

{{VersionBadge|0.8}}
{{Series|CEGUI In Practice|5}}

== CEGUI InPractice 5 ==

In this tutorial we will introduce how to use the .layout file. This is likely what will be used for larger scale projects, where the art team isn't going to want to wait for you to recompile the source for every change they make.

==== Meet the Layout ====

The Layout file (.layout) is an xml file. There exists at least two editors for layouts. The first one is the [[Downloads|CEGUI LayoutEditor]] This is a fairly mature editor. Unfortunately it is deprecated and has not received any updates in sometime. There is a new Editor (CEGUI Layout Editor 2) which is available from the SVN. For the usage of this tutorial tho, we will not be using an editor and will be manipulating the .layout file with a plain old text editor.

First thing to note, is its an XML file. So proper XML formatting is required. Second, is that it is hierarchical just like CEGUI. We will work towards writing a Simple Console here. I have created a console layout, and that will be the goal of this tutorial, to make a console editor like you would find in the various MMORPG's. This is what we'll make today:

[[File:TutorialInPractice-Console.jpg]] 
Attached is the layout:
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<GUILayout >
<Window Type="TaharezLook/FrameWindow" Name="ConsoleRoot" >
<Property Name="Text" Value="Chat Window" />
<Property Name="TitlebarFont" Value="DejaVuSans-10" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.114991,0},{0.358182,0},{0.519469,0},{0.775455,0}}" />
<Window Type="TaharezLook/Editbox" Name="ConsoleRoot/EditBox" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedAreaRect" Value="{{0.0201637,0},{0.787097,0},{0.694549,0},{0.957693,0}}" />
<Property Name="TextParsingEnabled" Value="False" />
</Window>
<Window Type="TaharezLook/Button" Name="ConsoleRoot/SendButton" >
<Property Name="Text" Value="Send" />
<Property Name="UnifiedAreaRect" Value="{{0.732211,0},{0.812349,0},{0.928283,0},{0.946832,0}}" />
</Window>
<Window Type="TaharezLook/Listbox" Name="ConsoleRoot/ChatBox" >
<Property Name="UnifiedAreaRect" Value="{{0.00534809,0},{0.0131038,0},{0.949636,0},{0.762443,0}}" />
</Window>
</Window>
</GUILayout>
</source>

Okay, i'll admit. I cheated and used a LayoutEditor for this. But i'm allowed to, I know what I'm doing otherwise, so do don't back talk me and do your homework.

Erm. Anyway, lets look at the setup of the .layout file.

the first line <xml..> Is just the XML Declaration, and is not important for us.

the next line <GUILayout > begins the .layout file as far as CEGUI is concerned.

Next up is: <source lang="xml"><Window Type="TaharezLook/FrameWindow" Name="ConsoleRoot" ></source>
This is where the meat begins. As you can see we're creating a window of type "TaharezLook/FrameWindow" with the name "ConsoleRoot."

The next lines:
<source lang="xml"> <Property Name="Text" Value="Chat Window" />
<Property Name="TitlebarFont" Value="DejaVuSans-10" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.114991,0},{0.358182,0},{0.519469,0},{0.775455,0}}" />
</source>
change various PropertySets on that new framewindow. It sets the font, Titlebar and the area. These could also be done in code by calling:
<tabber>
C++=
<source lang="cpp">
CEGUI::Window::setProperty("TitlebarFont","DejaVuSans-10");
</source>
|-|
Python=
<source lang="python">
PyCEGUI.Window.setProperty("TitlebarFont","DejaVuSans-10")
</source>
</tabber>
So as you can see, the scripts can be very useful allowing us to change properties outside of the code, giving the artists a great deal of usability!

Anyway, the next line is <source lang="xml"> <Window Type="TaharezLook/Editbox" Name="ConsoleRoot/EditBox" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedAreaRect" Value="{{0.0201637,0},{0.787097,0},{0.694549,0},{0.957693,0}}" />
<Property Name="TextParsingEnabled" Value="False" />
</Window></source>

You'll notice this is before the </Window> of the ConsoleRoot, so it will be created as a child in of ConsoleRoot when the script is loaded in CEGUI. Can you tell what kind of window this will be? It will be an edit box. Thats the portion of the Console Window where the user will be able to type in what they want to say. I'm not going to go into detail about the rest of the windows, as they are pretty similar to the above examples. But "ConsoleRoot/SendButton" will be the send button, and "ConsoleRoot/ChatBox" will be where the chat messages will display to.

[Note: As you can see I adopted the Naming scheme of Parent/Child window names. This is NOT required, but I think it helps make things easier to read on code side while debugging. You wouldn't want to just name it EditBox as that would be a pretty Common name, and may conflict with other windows you create later on in the application.]

==== Applying our knowledge ====

Now that we have gotten an introduction to the .layout file, we should learn how to implement this knowledge. How to get the layout file to show up in CEGUI.

This code will load the layout into a new window:

<tabber>
C++=
<source lang="cpp">
CEGUI::Window *newWindow = CEGUI::WindowManager::getSingleton().loadLayoutFromFile("MyConsole.layout");
</source>
|-|
Python=
<source lang="python">
newWindow = PyCEGUI.WindowManager.getSingleton().loadLayoutFromFile("MyConsole.layout")
</source>
</tabber>

Pretty self explanatory. There is something to note tho, you can add a prefix to the names in this .layout file. This would be useful if you're going to add the same .layout multiple times, because after the first load you'd get name conflicts. It would find a previous "ConsoleRoot" for example. So by calling this

<tabber>
C++=
<source lang="cpp">
CEGUI::Window *newWindow = CEGUI::WindowManager::getSingleton().loadLayoutFromFile("MyConsole.layout","second_");
</source>
|-|
Python=
<source lang="python">
newWindow = PyCEGUI.WindowManager.getSingleton().loadLayoutFromFile("MyConsole.layout","second_")
</source>
</tabber>
It would append "second_" to the window names (ie. "second_ConsoleRoot"); This will prevent naming errors.

Now if we ran this right now would we be able to see the window?

Nope. We haven't attached it to the window hierarchy have we?

<tabber>
C++=
<source lang="cpp">
CEGUI::System::getSingleton().getDefaultGUIContext().getRootWindow()->addChild(newWindow);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.System.getSingleton().getDefaultGUIContext().getRootWindow().addChild(newWindow)
</source>
</tabber>
Note: This assumes that you have a GUISheet already set, otherwise this will result in a segfault!

==== Conclusion ====

Well we showed how to load a .layout file. So far now we know how to Start the system with Ogre, create a window and understand properties, add input, process events, and load layouts. In the next tutorial we will apply this knowledge to create a console which actually does something! Till next time.

This list of the Window properties may be helpful in creating your .layout files: [http://static.cegui.org.uk/docs/current/classCEGUI_1_1Window.html]

[[Category:Tutorials]]

CEGUI In Practice - Creating widgets

2014-03-30T08:16:57Z

Superpws:

{{VersionBadge|0.8}}
{{Series|CEGUI In Practice|2}}

== CEGUI In-Practice 2 ==

Welcome back. This is the second installment of CEGUI In-Practice tutorial series. In this we will build upon the previous tutorial, [[CEGUI In Practice - Introduction]]. We will show how to create Widgets and manage them.

=== The Widget ===

In the last example we showed how to bootstrap the system with Ogre, and gave a brief introduction to CEGUI's script files. Now we will work on understanding what a widget is and how to use them. Lets jump in and create a window which will display a box with an image in the middle of the screen:

<tabber>
C++=
<source lang="cpp">
CEGUI::Window *myImageWindow = CEGUI::WindowManager::getSingleton().createWindow("TaharezLook/StaticImage","PrettyWindow" );
</source>
|-|
Python=
<source lang="python">
myImageWindow = PyCEGUI.WindowManager.getSingleton().createWindow("TaharezLook/StaticImage","PrettyWindow" )
</source>
</tabber>

CEGUI uses numerous derived classes code-side to create windows. The base class CEGUI::Window is the generic window. the CEGUI::WindowManager calls a factory class when creating a window which returns the windows pointer. The first argument, "TaharezLook/StaticImage" tells the factory what kind of window to make. These windows are defined in .scheme, which are subsequently defined more depth in other .xml files. The second argument is the name which the window will have.

[Note: As a point to note, there is no strict requirement on naming of windows, except to avoid repeat names. Some users tend to prefer a naming convention using ParentName/ChildName. ie. "ConsoleWindow/SendButton" or "_MasterRoot/HealthBar"]

Once we have created the window, myImageWindow will be a pointer to a CEGUI::{{DoxygenClass|DefaultWindow|0.8}} which is derived from CEGUI::{{DoxygenClass|Window|0.8}}. If you look in the .scheme file you can see can see what a Widget is derived from via the TargetType= tag.

Next we need to set some properties for this window. There are two ways of doing this. The first is via the propertyset, or the second way by calling the function. The latter way can be more annoying at times, as you may have to cast the window to the correct type to get access to the member functions, but may be more intuitive depending on how you think.

=== The Unified Dimension System ===

We created our widget, now we need to position it and define its size. Lets do that via code shall we?

Before we jump in too far, we need to understand how CEGUI Handles positions. CEGUI Uses a Unified Dimension system.

<tabber>
C++=
<source lang="cpp">
CEGUI::UDim(scale,offset);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.UDim(scale,offset)
</source>
</tabber>

The first number is the relative point on the screen between (0,1). So if we were looking at the X axis (left to right on the screen) a UDim(0.5,0) would be Halfway across the screen with zero pixels offset. Udim(0.0,50) would be starting at the left side of the screen +50 pixels. You can combine them too Udim(0.75,10) would be 3/4 of the way across the screen, with an additional 10 pixels.

A point on the screen (or a UVector2) is made up of two UDims:

<tabber>
C++=
<source lang="cpp">
CEGUI::UVector2(CEGUI::UDim x, CEGUI::UDim y);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.UVector2(PyCEGUI.UDim x, PyCEGUI.UDim y)
</source>
</tabber>

As such, a CEGUI::Rect is as you would imagine, 4 UDims

<tabber>
C++=
<source lang="cpp">
CEGUI::URect(CEGUI::Udim left,CEGUI::Udim top,CEGUI::Udim right,CEGUI::Udim bottom);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.URect(PyCEGUI.Udim left, PyCEGUI.Udim top, PyCEGUI.Udim right, PyCEGUI.Udim bottom)
</source>
</tabber>

So now that we know how positions are done, lets move our created window to the middle of the screen:
==== The Widget in Practice ====

<tabber>
C++=
<source lang="cpp">
myImageWindow->setPosition(CEGUI::UVector2(CEGUI::UDim(0.5,0),CEGUI::UDim(0.5,0)));
</source>
|-|
Python=
<source lang="python">
myImageWindow.setPosition(PyCEGUI.UVector2(PyCEGUI.UDim(0.5,0), PyCEGUI.UDim(0.5,0)))
</source>
</tabber>

That may look a little ugly but break it down. setPosition takes a UVector2, and each UVector2 is made up of an X and Y Udim, which is made up of a Scale and Absolute float.

So, we have moved our window to the middle of the screen.. but CEGUI doesn't know how big to make it? So set its size to 150 pixels by 100 pixels [Note: I dropped the namespace for this to increase readability].

<tabber>
C++=
<source lang="cpp">
myImageWindow->setSize(USize(UDim(0,150),UDim(0,100)));
</source>
|-|
Python=
<source lang="python">
myImageWindow.setSize(USize(UDim(0,150),UDim(0,100)));
</source>
</tabber>

In this case we specified the Udim using 0 for scales, and the actual pixel size in the absolute argument. The Absolute argument is additive to the scale, and in this case we didn't want to have the size be affected by the scale argument. If we were creating a splash screen that took up the entire window, we would likely want the size to be USize(UDim(1,0),UDim(1,0) with the position being at USize(Udim(0,0), UDim(0,0).

[TODO: Add a proper description of USize which replaced UVector2 for setting size in CEGUI 0.8.3]

Now that we have created the window to the size we want. We need to tell it what image to display! That we will do by using the PropertySet as follows.

<tabber>
C++=
<source lang="cpp">
myImageWindow->setProperty("Image","set:TaharezLook image:full_image");
</source>
|-|
Python=
<source lang="python">
myImageWindow.setProperty("Image","set:TaharezLook image:full_image")
</source>
</tabber>

The first agument is what Property we want to set, and the second argument is what value to set. The second argument is a string broken into two pieces in this example. We need to know what ImageSet we are looking in, which is referenced following the 'set:' portion. And then the image via the 'image:' portion. In this case we want it to show the full_image.

A Listing of properties for TaharezLook is available here [http://cegui.org.uk/wiki/Property_reference_for_TaharezLook]

Now that we have created the window. We need to attach it to the current root window.

<tabber>
C++=
<source lang="cpp">
CEGUI::System::getSingleton().getDefaultGUIContext().getRootWindow()->addChild(myImageWindow);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.System.getSingleton().getDefaultGUIContext().getRootWindow().addChild(myImageWindow)
</source>
</tabber>

This will allow the Window to be displayed.

==== Conclusion ====

So with this quick tutorial we got a very short introduction to PropertySet usage (Important!) and a little bit about how the Unified Dimension System in CEGUI Works. While still not terribly useful, we're beginning to understand how to use some of CEGUI's faculties. Next up, we'll learn how to get some interactivity from this thing.

[[Category:Tutorials]]

CEGUI In Practice - Creating widgets

2014-03-30T08:15:01Z

Superpws:

{{VersionBadge|0.8}}
{{Series|CEGUI In Practice|2}}

== CEGUI In-Practice 2 ==

Welcome back. This is the second installment of CEGUI In-Practice tutorial series. In this we will build upon the previous tutorial, [[CEGUI In Practice - Introduction]]. We will show how to create Widgets and manage them.

=== The Widget ===

In the last example we showed how to bootstrap the system with Ogre, and gave a brief introduction to CEGUI's script files. Now we will work on understanding what a widget is and how to use them. Lets jump in and create a window which will display a box with an image in the middle of the screen:

<tabber>
C++=
<source lang="cpp">
CEGUI::Window *myImageWindow = CEGUI::WindowManager::getSingleton().createWindow("TaharezLook/StaticImage","PrettyWindow" );
</source>
|-|
Python=
<source lang="python">
myImageWindow = PyCEGUI.WindowManager.getSingleton().createWindow("TaharezLook/StaticImage","PrettyWindow" )
</source>
</tabber>

CEGUI uses numerous derived classes code-side to create windows. The base class CEGUI::Window is the generic window. the CEGUI::WindowManager calls a factory class when creating a window which returns the windows pointer. The first argument, "TaharezLook/StaticImage" tells the factory what kind of window to make. These windows are defined in .scheme, which are subsequently defined more depth in other .xml files. The second argument is the name which the window will have.

[Note: As a point to note, there is no strict requirement on naming of windows, except to avoid repeat names. Some users tend to prefer a naming convention using ParentName/ChildName. ie. "ConsoleWindow/SendButton" or "_MasterRoot/HealthBar"]

Once we have created the window, myImageWindow will be a pointer to a CEGUI::{{DoxygenClass|DefaultWindow|0.8}} which is derived from CEGUI::{{DoxygenClass|Window|0.8}}. If you look in the .scheme file you can see can see what a Widget is derived from via the TargetType= tag.

Next we need to set some properties for this window. There are two ways of doing this. The first is via the propertyset, or the second way by calling the function. The latter way can be more annoying at times, as you may have to cast the window to the correct type to get access to the member functions, but may be more intuitive depending on how you think.

=== The Unified Dimension System ===

We created our widget, now we need to position it and define its size. Lets do that via code shall we?

Before we jump in too far, we need to understand how CEGUI Handles positions. CEGUI Uses a Unified Dimension system.

<tabber>
C++=
<source lang="cpp">
CEGUI::UDim(scale,offset);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.UDim(scale,offset)
</source>
</tabber>

The first number is the relative point on the screen between (0,1). So if we were looking at the X axis (left to right on the screen) a UDim(0.5,0) would be Halfway across the screen with zero pixels offset. Udim(0.0,50) would be starting at the left side of the screen +50 pixels. You can combine them too Udim(0.75,10) would be 3/4 of the way across the screen, with an additional 10 pixels.

A point on the screen (or a UVector2) is made up of two UDims:

<tabber>
C++=
<source lang="cpp">
CEGUI::UVector2(CEGUI::UDim x, CEGUI::UDim y);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.UVector2(PyCEGUI.UDim x, PyCEGUI.UDim y)
</source>
</tabber>

As such, a CEGUI::Rect is as you would imagine, 4 UDims

<tabber>
C++=
<source lang="cpp">
CEGUI::URect(CEGUI::Udim left,CEGUI::Udim top,CEGUI::Udim right,CEGUI::Udim bottom);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.URect(PyCEGUI.Udim left, PyCEGUI.Udim top, PyCEGUI.Udim right, PyCEGUI.Udim bottom)
</source>
</tabber>

So now that we know how positions are done, lets move our created window to the middle of the screen:
==== The Widget in Practice ====

<tabber>
C++=
<source lang="cpp">
myImageWindow->setPosition(CEGUI::UVector2(CEGUI::UDim(0.5,0),CEGUI::UDim(0.5,0)));
</source>
|-|
Python=
<source lang="python">
myImageWindow.setPosition(PyCEGUI.UVector2(PyCEGUI.UDim(0.5,0), PyCEGUI.UDim(0.5,0)))
</source>
</tabber>

That may look a little ugly but break it down. setPosition takes a UVector2, and each UVector2 is made up of an X and Y Udim, which is made up of a Scale and Absolute float.

So, we have moved our window to the middle of the screen.. but CEGUI doesn't know how big to make it? So set its size to 150 pixels by 100 pixels [Note: I dropped the namespace for this to increase readability].

<tabber>
C++=
<source lang="cpp">
myImageWindow->setSize(USize(UDim(0,150),UDim(0,100)));
</source>
|-|
Python=
<source lang="python">
myImageWindow.setSize(USize(UDim(0,150),UDim(0,100)));
</source>
</tabber>

In this case we specified the Udim using 0 for scales, and the actual pixel size in the absolute argument. The Absolute argument is additive to the scale, and in this case we didn't want to have the size be affected by the scale argument. If we were creating a splash screen that took up the entire window, we would likely want the size to be USize(UDim(1,0),UDim(1,0) with the position being at USize(Udim(0,0), UDim(0,0).

Now that we have created the window to the size we want. We need to tell it what image to display! That we will do by using the PropertySet as follows.

<tabber>
C++=
<source lang="cpp">
myImageWindow->setProperty("Image","set:TaharezLook image:full_image");
</source>
|-|
Python=
<source lang="python">
myImageWindow.setProperty("Image","set:TaharezLook image:full_image")
</source>
</tabber>

The first agument is what Property we want to set, and the second argument is what value to set. The second argument is a string broken into two pieces in this example. We need to know what ImageSet we are looking in, which is referenced following the 'set:' portion. And then the image via the 'image:' portion. In this case we want it to show the full_image.

A Listing of properties for TaharezLook is available here [http://cegui.org.uk/wiki/Property_reference_for_TaharezLook]

Now that we have created the window. We need to attach it to the current root window.

<tabber>
C++=
<source lang="cpp">
CEGUI::System::getSingleton().getDefaultGUIContext().getRootWindow()->addChild(myImageWindow);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.System.getSingleton().getDefaultGUIContext().getRootWindow().addChild(myImageWindow)
</source>
</tabber>

This will allow the Window to be displayed.

==== Conclusion ====

So with this quick tutorial we got a very short introduction to PropertySet usage (Important!) and a little bit about how the Unified Dimension System in CEGUI Works. While still not terribly useful, we're beginning to understand how to use some of CEGUI's faculties. Next up, we'll learn how to get some interactivity from this thing.

[[Category:Tutorials]]

CEGUI In Practice - A push button

2014-03-30T08:08:49Z

Superpws:

{{VersionBadge|0.8}}
{{Series|CEGUI In Practice|4}}

== CEGUI In-Practice 4 ==

Hello hello, you're making good headway through these tutorials! Alright, last lesson we got a glimpse of how to send input to CEGUI. This is useful, because today we're going to make a button. And not just any button, but a button which makes something happen! I know, exciting.

==== Some groundwork ====

First we need to look into how CEGUI handles event control.

CEGUI is based around the Event/Subscriber method. Meaning, something (A button, an edit box, a list box) fires off an event (MouseClick,Text Accepted, or Selection), and something else (The Application Class, another CEGUI Widget, anything!) is informed about it. It does this via the

<source lang="cpp">CEGUI::Window::subscribeEvent(const String& name,Event::Subscriber subscriber) </source>

The first argument is the Event that you wish to keep track of. Events are static const strings. You will find these in the respective header files for CEGUI Widget types. (Example CEGUIPushButton contains CEGUI::PushButton::EventClicked)

The second argument is the subscriber which will be called whenever this event occurs.

Let's give an example of how to register our character to jump whenever a button is pressed. First, let's create our Button, which will make our character jump. Although this is bad coding style, we will create the button in global scope for ease of this example.
<source lang="cpp">
CEGUI::Window *gJumpBtnWindow = NULL;

void CreateJumpButton()
{
gJumpBtnWindow = CEGUI::WindowManager::getSingleton().createWindow("TaharezLook/Button","JumpPushButton"); // Create Window
gJumpBtnWindow->setPosition(CEGUI::UVector2(CEGUI::UDim(0.75,0),CEGUI::UDim(0.50,0)));
gJumpBtnWindow->setSize(CEGUI::USize(CEGUI::UDim(0,50),CEGUI::UDim(0,50)));
gJumpBtnWindow->setText("Jump!");
CEGUI::System::getSingleton().getDefaultGUIContext().getRootWindow()->addChild(gJumpBtnWindow);
}
</source>

The above code Creates the button of type "TaharezLook/Button", as exists in the .scheme file. Then it gives it the name of "JumpPushButton" and sets its size and position, followed by attaching it to the root GUI Window. This is review from two tutorials ago. However, the setText one is new. It's pretty Self explanatory I would assume, but it Sets the text for windows. PushButtons, EditBoxes, FrameWindows, etc. all have a spot to display text and this function will do it.

Now that we have created our button, let's create a class that will receive this JumpPushButton's events. Please remember this is an example. In your application, it likely won't be this simple!

<source lang="cpp">
class OurPlayer
{
public:
OurPlayer()
{
RegisterForEvents(); // Call our Register function
};
bool Jump(const CEGUI::EventArgs& /*e*/){}; // Jump for joy
private:
RegisterForEvents()
{
gJumpBtnWindow->subscribeEvent(CEGUI::PushButton::EventClicked,CEGUI::Event::Subscriber(&OurPlayer::Jump,this));
};
}
</source>

Alright, that's a neat little class right? I don't know how you're going to make your character jump, so you get to fill in that information. I'm just gonna show you how to interact with the GUI!

Alright, the really interesting line here is the RegisterForEvents() function. You may or may not have dealt with EventSubscribers before in other applications, so I will give a very brief intro to them.

Basically, they work by creating a structure which is supplied to CEGUI stating what function to call, and where to get an instance of a member that has that function. the first argument, &OurPlayer::Jump states that we want to use the function Jump which is a member of OurPlayer. The problem is it doesn't know WHICH OurPlayer we want to use. What if we are playing split screen and we have two OurPlayer classes? One for the Left player and one for the Right player? Now we need to specify which player. There is the second argument. In C++, '''this''' returns a pointer to the class execution is currently in. So since we're registering this event within a class, we tell it to use this, which will reference the class that called RegisterForEvents();

If we had created as follows:
<source lang="cpp">
OurPlayer *leftPlayer;
OurPlayer *rightPlayer;
</source>

then we would call the function like this

<source lang="cpp">
gJumpBtnWindow->subscribeEvent(CEGUI::PushButton::EventClicked,CEGUI::Event::Subscriber(&OurPlayer::Jump,leftPlayer));
</source>

So as you can see this allows for a lot of possibilities. There are also events for:

* MouseClicked,
* MouseEnters,
* MouseLeaves,
* EventActivated,
* EventTextChanged,
* EventAlphaChanged,
* EventSized

Just to name a few. There is a Huge listing of events which all windows inherit in CEGUIWindow.h

==== Conclusion ====

Hopefully this tutorial showed you how to implement events in cegui. They really are the mechanism which all things happen. Once you master how to use events, the rest of the GUI becomes so easy to use, as most user interactions are event driven. While you may not use them all, there are even events for Rotating windows and dropping windows on other windows! Just think of the possibilities. Until next time Happy Clicking!

[[Category:Tutorials]]

CEGUI In Practice - Managing input

2014-03-30T08:03:15Z

Superpws:

{{VersionBadge|0.8}}
{{Series|CEGUI In Practice|3}}

== CEGUI In-Practice ==

Once again Welcome back! In this tutorial we will learn how to interact with the CEGUI System at runtime, a VERY useful feature to have for a Graphical User '''Interface'''!

CEGUI Has been designed to work on many systems, using many different renderers. As such it is tied to no particular input system. Unfortunately for us to demonstrate how to interact with CEGUI, we need to pick one and USE it don't we? So I have decided to use OIS [http://sourceforge.net/projects/wgois/]. Although I will attempt to keep OIS Specific functions and structures seperate, if they slip in, there is the reference to the system I'm using.

==== Input Injection ====

The first thing to note, is that not surprisingly CEGUI has made it easy to deal with inputing user actions into CEGUI. Whenever an action happens (User typing, hitting Escape, clicking a button) CEGUI will need to be informed about it.

<source lang="cpp">
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyDown(uint key_code); // Tells CEGUI Key has been Pressed
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyUp(uint key_code); // Tells CEGUI Key has been Released

CEGUI::System::getSingleton().getDefaultGUIContext().injectChar(utf32 code_point);
</source>

The Inject keydown/up are good for sending Shift, controls, enters, etc. While the injectChar is pretty self explanatory for what it means, it injects a 'letter'.

Handling the mouse works in a similiar method as above. The following code shows how you would inform CEGUI about a Left Mouse Button Keypress.
<source lang="cpp">CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonDown(CEGUI::MouseButton::LeftButton);</source>

As you can imagine, there is a injectMouseButtonUp() as well for letting CEGUI know when the mouse is released.

And what about when the mouse itself moves? Of course thats covered

<source lang="cpp">CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseMove(float delta_x, float delta_y);</source>

The delta is in Screen pixels that the mouse moved since the last CEGUI Update.

Up until know, we haven't actually given CEGUI any processor time. If we're going to be moving a mouse, or clicking buttons, we're going to want CEGUI to display these actions. So we need to let CEGUI know how much time has passed since its last render.

<source lang="cpp">CEGUI::System::getSingleton().injectTimePulse(float timeElapsed);</source>

This allows you to inject a time pulse, based on the number of Seconds that have passed. However often you update CEGUI is up to you, but most games will want to update the GUI by injectingTime pulses during every update cycle. If you're building more of a Tool Application you might not need constant updates.

==== On ward! ====

I'm going to assume that you are using OIS and are knowledgable about its uses. Here are two functions which will allow you to interact with CEGUI

The following will input keypresses when typing. It injects the key down and up actions (By key code) and the characters that associate with those keypresses.

<source lang="cpp">
void InjectOISKey(bool bButtonDown, OIS::KeyEvent inKey)
{
if (bButtonDown)
{
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyDown(inKey.key);
CEGUI::System::getSingleton().getDefaultGUIContext().injectChar(inKey.text);
}
else
{
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyUp(inKey.key);
}
}
</source>

The following function will handle injection of OIS Mouse Button presses and releases
<source lang="cpp">
void InjectOISMouseButton(bool bButtonDown, OIS::MouseButtonID inButton)
{
if (bButtonDown == true)
{
switch (inButton)
{
case OIS::MB_Left:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonDown(CEGUI::LeftButton);
break;
case OIS::MB_Middle:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case OIS::MB_Right:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonDown(CEGUI::RightButton);
break;
case OIS::MB_Button3:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonDown(CEGUI::X1Button);
break;
case OIS::MB_Button4:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonDown(CEGUI::X2Button);
break;
default:
break;

}
}
else // bButtonDown = false
{
switch (inButton)
{
case OIS::MB_Left:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonUp(CEGUI::LeftButton);
break;
case OIS::MB_Middle:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case OIS::MB_Right:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonUp(CEGUI::RightButton);
break;
case OIS::MB_Button3:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonUp(CEGUI::X1Button);
break;
case OIS::MB_Button4:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonUp(CEGUI::X2Button);
break;
default:
break;
}
}

}
</source>

This above function will Convert a OIS Input for the mouse and change it to CEGUI. Right now the codes match, but if they ever change it will provide an example of how to use OIS with CEGUI.

==== Conclusion ====

Understandably this section is a little quicker. But it gives you information about how to start interacting with CEGUI. The next tutorial will teach us how to actually deal with keypresses and make interesting things happen. Until then!

[[Category:Tutorials]]

CEGUI In Practice - Creating widgets

2014-03-30T07:40:24Z

Superpws:

{{VersionBadge|0.8}}
{{Series|CEGUI In Practice|2}}

== CEGUI In-Practice 2 ==

Welcome back. This is the second installment of CEGUI In-Practice tutorial series. In this we will build upon the previous tutorial, [[CEGUI In Practice - Introduction]]. We will show how to create Widgets and manage them.

=== The Widget ===

In the last example we showed how to bootstrap the system with Ogre, and gave a brief introduction to CEGUI's script files. Now we will work on understanding what a widget is and how to use them. Lets jump in and create a window which will display a box with an image in the middle of the screen:

<tabber>
C++=
<source lang="cpp">
CEGUI::Window *myImageWindow = CEGUI::WindowManager::getSingleton().createWindow("TaharezLook/StaticImage","PrettyWindow" );
</source>
|-|
Python=
<source lang="python">
myImageWindow = PyCEGUI.WindowManager.getSingleton().createWindow("TaharezLook/StaticImage","PrettyWindow" )
</source>
</tabber>

CEGUI uses numerous derived classes code-side to create windows. The base class CEGUI::Window is the generic window. the CEGUI::WindowManager calls a factory class when creating a window which returns the windows pointer. The first argument, "TaharezLook/StaticImage" tells the factory what kind of window to make. These windows are defined in .scheme, which are subsequently defined more depth in other .xml files. The second argument is the name which the window will have.

[Note: As a point to note, there is no strict requirement on naming of windows, except to avoid repeat names. Some users tend to prefer a naming convention using ParentName/ChildName. ie. "ConsoleWindow/SendButton" or "_MasterRoot/HealthBar"]

Once we have created the window, myImageWindow will be a pointer to a CEGUI::{{DoxygenClass|DefaultWindow|0.8}} which is derived from CEGUI::{{DoxygenClass|Window|0.8}}. If you look in the .scheme file you can see can see what a Widget is derived from via the TargetType= tag.

Next we need to set some properties for this window. There are two ways of doing this. The first is via the propertyset, or the second way by calling the function. The latter way can be more annoying at times, as you may have to cast the window to the correct type to get access to the member functions, but may be more intuitive depending on how you think.

=== The Unified Dimension System ===

We created our widget, now we need to position it and define its size. Lets do that via code shall we?

Before we jump in too far, we need to understand how CEGUI Handles positions. CEGUI Uses a Unified Dimension system.

<tabber>
C++=
<source lang="cpp">
CEGUI::UDim(scale,offset);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.UDim(scale,offset)
</source>
</tabber>

The first number is the relative point on the screen between (0,1). So if we were looking at the X axis (left to right on the screen) a UDim(0.5,0) would be Halfway across the screen with zero pixels offset. Udim(0.0,50) would be starting at the left side of the screen +50 pixels. You can combine them too Udim(0.75,10) would be 3/4 of the way across the screen, with an additional 10 pixels.

A point on the screen (or a UVector2) is made up of two UDims:

<tabber>
C++=
<source lang="cpp">
CEGUI::UVector2(UDim x,UDim y);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.UVector2(UDim x, UDim y)
</source>
</tabber>

As such, a CEGUI::Rect is as you would imagine, 4 UDims

<tabber>
C++=
<source lang="cpp">
CEGUI::URect(CEGUI::Udim left,CEGUI::Udim top,CEGUI::Udim right,CEGUI::Udim bottom);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.URect(PyCEGUI.Udim left, PyCEGUI.Udim top, PyCEGUI.Udim right, PyCEGUI.Udim bottom)
</source>
</tabber>

So now that we know how positions are done, lets move our created window to the middle of the screen:
==== The Widget in Practice ====

<tabber>
C++=
<source lang="cpp">
myImageWindow->setPosition(CEGUI::UVector2(CEGUI::UDim(0.5,0),CEGUI::UDim(0.5,0)));
</source>
|-|
Python=
<source lang="python">
myImageWindow.setPosition(PyCEGUI.UVector2(PyCEGUI.UDim(0.5,0), PyCEGUI.UDim(0.5,0)))
</source>
</tabber>

That may look a little ugly but break it down. setPosition takes a UVector2, and each UVector2 is made up of an X and Y Udim, which is made up of a Scale and Absolute float.

So, we have moved our window to the middle of the screen.. but CEGUI doesn't know how big to make it? So set its size to 150 pixels by 100 pixels [Note: I dropped the namespace for this to increase readability].

<tabber>
C++=
<source lang="cpp">
myImageWindow->setSize(UVector2(UDim(0,150),UDim(0,100)));
</source>
|-|
Python=
<source lang="python">
myImageWindow.setSize(UVector2(UDim(0,150),UDim(0,100)));
</source>
</tabber>

In this case we specified the Udim using 0 for scales, and the actual pixel size in the absolute argument. The Absolute argument is additive to the scale, and in this case we didn't want to have the size be affected by the scale argument. If we were creating a splash screen that took up the entire window, we would likely want the size to be UVector2(UDim(1,0),UDim(1,0) with the position being at UVector2(Udim(0,0), UDim(0,0).

Now that we have created the window to the size we want. We need to tell it what image to display! That we will do by using the PropertySet as follows.

<tabber>
C++=
<source lang="cpp">
myImageWindow->setProperty("Image","set:TaharezLook image:full_image");
</source>
|-|
Python=
<source lang="python">
myImageWindow.setProperty("Image","set:TaharezLook image:full_image")
</source>
</tabber>

The first agument is what Property we want to set, and the second argument is what value to set. The second argument is a string broken into two pieces in this example. We need to know what ImageSet we are looking in, which is referenced following the 'set:' portion. And then the image via the 'image:' portion. In this case we want it to show the full_image.

A Listing of properties for TaharezLook is available here [http://cegui.org.uk/wiki/Property_reference_for_TaharezLook]

Now that we have created the window. We need to attach it to the current root window.

<tabber>
C++=
<source lang="cpp">
CEGUI::System::getSingleton().getDefaultGUIContext().getRootWindow()->addChild(myImageWindow);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.System.getSingleton().getDefaultGUIContext().getRootWindow().addChild(myImageWindow)
</source>
</tabber>

This will allow the Window to be displayed.

==== Conclusion ====

So with this quick tutorial we got a very short introduction to PropertySet usage (Important!) and a little bit about how the Unified Dimension System in CEGUI Works. While still not terribly useful, we're beginning to understand how to use some of CEGUI's faculties. Next up, we'll learn how to get some interactivity from this thing.

[[Category:Tutorials]]

CEGUI In Practice - Introduction

2014-03-30T07:22:27Z

Superpws:

{{VersionBadge|0.8}}
{{Series|CEGUI In Practice|1}}

== CEGUI In-Practice ==

Welcome to the first in a series of tutorials based on how to use CEGUI. The majority of the tutorials will be done in code. I may attempt to sprinkle in uses of .layouts throughout the tutorial. But once you understand how to use many of the Widgets in code it becomes easy to use them via script.

[Please note, I am an Ogre3d user, so the initial setup will be how to bootstrap and start with ogre3d.]

=== Introducing CEGUI ===
First notes, CEGUI uses a number of Singleton classes. These, if not experienced with singletons, allow global access to a Class globally in the code, while ensuring only a 'single'ton instance is ever created. The following are the Singletons we will be using
in this example.

'''CEGUI::{{DoxygenClass|System|0.8}}''' - The big Kahuna. This contains many of the functions for setting and getting defaults. 
'''CEGUI::{{DoxygenClass|WindowManager|0.8}}''' - Manages the windows of CEGUI. If a new window is going to be created or Deleted WindowManager is gonna be your class. 

'''CEGUI::{{DoxygenClass|SchemeManager|0.8}}''' - Manages Schemes. 
'''CEGUI::{{DoxygenClass|FontManager|0.8}}''' - Manages the different fonts you will use in your application. 

==== Getting Started ====

Let's jump in and get some stuff setup. The first thing we need to do is get the system up and running. Since I am an Ogre user, I will show the code to get the system up and running with ogre. There are methods of getting it started for numerous other Rendering systems. Shown here [[The Beginner Guide to Getting CEGUI Rendering]]. 

The Ogre3d Method is shown here:

===== Including necessary headers =====
<tabber>
C++=
<source lang="cpp">
#include <CEGUI.h>
#include <RendererModules/Ogre/Renderer.h>
</source>
|-|
Python=
<source lang="python">
import PyCEGUI
import PyCEGUIOgreRenderer
</source>
</tabber>

===== Bootstrapping CEGUI =====

<tabber>
C++=
<source lang="cpp">
CEGUI::OgreRenderer* renderer = &CEGUI::OgreRenderer::bootstrapSystem();
</source>
|-|
Python=
<source lang="python">
renderer = PyCEGUIOgreRenderer.OgreRenderer.bootstrapSystem()
</source>
</tabber>

[Note: This is a newer method using the bootstrapSystem, this was introduced in CEGUI 0.7.1. There are examples on this wiki using older versions of CEGUI. Please make note of which version you are using] 

The above code creates an instance of the Ogre3d Render interface between Ogre3d and CEGUI. You will not need to deal with this much after the above code has been run. This creates the link which Ogre will use to render CEGUI. Please note, you will want to call this if Ogre is auto-creating the render window ( pretty common ). If you are manually creating the Ogre3d window, you will need to use the ''CEGUI::OgreRenderer::bootstrapSystem(Ogre::RenderWindow *)'' overload.

An additional point to mention is that the bootstrapSystem() will create an instance of CEGUI::System. This is important, as if you already have created CEGUI::System, an exception will be thrown.

==== Oh there will be scripts ====

Now that we've called the very meager function above. We need to cover some very basic information about CEGUI before we proceed.

CEGUI is a VERY heavily scripted library. Much of what defines the artistic content of CEGUI is defined in various .xml files. The beginning script we will mention is the '''Scheme''' (*.scheme). Every widget you will use in your GUI will be defined in the .scheme file. It will also contain information for about subscripts which will be used, described below. Later tutorials will describe this file in greater detail. Below is an example if you run across one:

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

<LookNFeel Filename="TaharezLook.looknfeel" />
<WindowRendererSet Filename="CEGUIFalagardWRBase" />
<FalagardMapping WindowType="TaharezLook/Button" TargetType="CEGUI/PushButton" Renderer="Falagard/Button" LookNFeel="TaharezLook/Button" />
<FalagardMapping WindowType="TaharezLook/Checkbox" TargetType="CEGUI/Checkbox" Renderer="Falagard/ToggleButton" LookNFeel="TaharezLook/Checkbox" />
</GUIScheme></source> 

The next script we will mention is the '''Layouts''' (*.layout). This is also an xml file, which defines the layout (obviously!) of the window we want to display on the screen. For example, if we wanted a to create a Chat window, we would probably have a ChatWindow.layout file somewhere. This would describe how the window looks (How big, where on the screen its displayed, etc), where the typing box would be located within this window, and where the button to 'send' the chat message would be. Below is a quick example of what a .layout file looks like:

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<GUILayout >
<Window Type="TaharezLook/FrameWindow" Name="ConsoleRoot" >
<Property Name="Text" Value="Chat Window" />
<Property Name="TitlebarFont" Value="DejaVuSans-10" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.114991,0},{0.358182,0},{0.519469,0},{0.775455,0}}" />
<Window Type="TaharezLook/Editbox" Name="ConsoleRoot/EditBox" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedAreaRect" Value="{{0.0201637,0},{0.787097,0},{0.694549,0},{0.957693,0}}" />
<Property Name="TextParsingEnabled" Value="False" />
</Window>
</GUILayout>
</source>

Another script which is useful to mention is a '''Font''' (*.font). This describes fonts which will be used in cegui. Below is an example:

<source lang="xml"><?xml version="1.0" ?>

</source>

Another important script is the '''Imageset''' (*.imageset). This is the file which determines the visuals of each widget. In CEGUI the visual part of a widget which the user see's is a small X/Y coordinate on a larger texture file. For example, a basic Button will have the graphics defined in a .imageset to be a certain position on a texture image (*.png, *.bmp, *.jpg, etc) with a certain height and width. It may be located at Pixel 100x320 and be 50x50 in size. This will be defined in the imageset. Below is an example.

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

Lastly, '''LookNFeel''' (*.looknfeel). This is a fairly evil looking file, and to save everyone from nightmarish horrors, I will not post an example (and to save space). This is the file which determines how every widget (CEGUI speak for window/object/item) looks and acts. For example, what it looks like when you mouse over a button, or how to build the border and background of a Window. Each scheme will generally have its own LookNFeel to allow more customization of the basic construction of CEGUI Widgets.

==== Back to Getting Started ====

Now that we have a minimal idea about what scripts CEGUI uses (and don't worry, they make more sense and are less intimidating as you proceede. You will likely use .layout the most in the beginning) lets start doing something useful!

Where we left off, CEGUI was just started. But in and of itself, it doesn't know what you want to do. First thing we should do is tell it what Scheme we want to use. As mentioned above, a .Scheme contains a listing of Widget and Other scripts to include, a Scheme can include an Imageset, lookNFeel, and font to use.

<tabber>
C++=
<source lang="cpp">
// Load the scheme
CEGUI::SchemeManager::getSingleton().createFromFile( "TaharezLook.scheme" );
</source>
|-|
Python=
<source lang="python">
# Load the scheme
PyCEGUI.SchemeManager.getSingleton().createFromFile( "TaharezLook.scheme" )
</source>
</tabber>

If you wanted to use an imageset or Font which is not designated in the .Scheme file its easy to do. Simply use the associated manager to load them. Since i'm trying my best to keep this as an introductory tutorial, I'll keep to the mission and explain these managers in a later tutorial.

Next up, lets define a few defaults:

<tabber>
C++=
<source lang="cpp">
// Set the defaults
CEGUI::System::getSingleton().getDefaultGUIContext().setDefaultFont("DejaVuSans-10");
CEGUI::System::getSingleton().getDefaultGUIContext().getMouseCursor().setDefaultImage("TaharezLook/MouseArrow");
</source>
|-|
Python=
<source lang="python">
# Set the defaults
PyCEGUI.System.getSingleton().getDefaultGUIContext().setDefaultFont( "DejaVuSans-10" )
PyCEGUI.System.getSingleton().getDefaultGUIContext().getMouseCursor().setDefaultImage("TaharezLook/MouseArrow")
</source>
</tabber>

These calls will summon the CEGUI::System from global scope and set the DefaultFont, and the default Mouse Cursor. If you reference TaharezLook.scheme (located in the cegui/datafiles/schemes folder). You will see that it loaded a font named DejaVuSans-10.font with the tag in the .scheme. The MouseArrow is found inside the imageset called "TharezLook" under the tag of "MouseArrow". Pretty self explanetory I'd hope.

Alright, now CEGUI knows about some basic defaults we want to use. Lets create a window which will be the Root window we will put everything on from here on out.

CEGUI uses a Parent/Child system for organizing the windows. So the first useful thing to do is create a parent which all other windows will be the child

<tabber>
C++=
<source lang="cpp">
CEGUI::Window* myRoot = CEGUI::WindowManager::getSingleton().createWindow( "DefaultWindow", "_MasterRoot" );
</source>
|-|
Python=
<source lang="python">
myRoot = PyCEGUI.WindowManager.getSingleton().createWindow( "DefaultWindow", "_MasterRoot" )
</source>
</tabber>

The above function calls upon the WindowManager singleton, and creates a window of type "DefaultWindow" named "_MasterRoot". The default window is just that. a default window, which is blank (or transparent). You can give the root window any name you like, however, i like using _MasterRoot as its unlikely any other window I ever use will have the name.

Now that we have created the window, we need to set it as the root window.

<tabber>
C++=
<source lang="cpp">
CEGUI::System::getSingleton().getDefaultGUIContext().setRootWindow( myRoot );
</source>
|-|
Python=
<source lang="python">
PyCEGUI.System.getSingleton().getDefaultGUIContext().setRootWindow( myRoot )
</source>
</tabber>

This calls upon the system, and assigns myRoot as the default window. Recall myRoot was created above with the name "_MasterRoot".

==== Conclusion ====

While not a super exciting tutorial. At this point CEGUI is now setup, and we could begin adding windows and doing such GUI shenanigans as making windows, buttons, clicking, and fun. Later tutorials will demonstrate how to have CEGUI Recognize clicking, dragging of windows, typing, and more! Thanks for reading!

[[Category:Tutorials]]

CEGUI In Practice - Using .layout files

2014-03-29T19:15:33Z

Superpws: /* Applying our knowledge */

{{VersionBadge|0.7}}
{{Series|CEGUI In Practice|5}}

== CEGUI InPractice 5 ==

In this tutorial we will introduce how to use the .layout file. This is likely what will be used for larger scale projects, where the art team isn't going to want to wait for you to recompile the source for every change they make.

==== Meet the Layout ====

The Layout file (.layout) is an xml file. There exists at least two editors for layouts. The first one is the [[Downloads|CEGUI LayoutEditor]] This is a fairly mature editor. Unfortunately it is deprecated and has not received any updates in sometime. There is a new Editor (CEGUI Layout Editor 2) which is available from the SVN. For the usage of this tutorial tho, we will not be using an editor and will be manipulating the .layout file with a plain old text editor.

First thing to note, is its an XML file. So proper XML formatting is required. Second, is that it is hierarchical just like CEGUI. We will work towards writing a Simple Console here. I have created a console layout, and that will be the goal of this tutorial, to make a console editor like you would find in the various MMORPG's. This is what we'll make today:

[[File:TutorialInPractice-Console.jpg]] 
Attached is the layout:
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<GUILayout >
<Window Type="TaharezLook/FrameWindow" Name="ConsoleRoot" >
<Property Name="Text" Value="Chat Window" />
<Property Name="TitlebarFont" Value="DejaVuSans-10" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.114991,0},{0.358182,0},{0.519469,0},{0.775455,0}}" />
<Window Type="TaharezLook/Editbox" Name="ConsoleRoot/EditBox" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedAreaRect" Value="{{0.0201637,0},{0.787097,0},{0.694549,0},{0.957693,0}}" />
<Property Name="TextParsingEnabled" Value="False" />
</Window>
<Window Type="TaharezLook/Button" Name="ConsoleRoot/SendButton" >
<Property Name="Text" Value="Send" />
<Property Name="UnifiedAreaRect" Value="{{0.732211,0},{0.812349,0},{0.928283,0},{0.946832,0}}" />
</Window>
<Window Type="TaharezLook/Listbox" Name="ConsoleRoot/ChatBox" >
<Property Name="UnifiedAreaRect" Value="{{0.00534809,0},{0.0131038,0},{0.949636,0},{0.762443,0}}" />
</Window>
</Window>
</GUILayout>
</source>

Okay, i'll admit. I cheated and used a LayoutEditor for this. But i'm allowed to, I know what I'm doing otherwise, so do don't back talk me and do your homework.

Erm. Anyway, lets look at the setup of the .layout file.

the first line <xml..> Is just the XML Declaration, and is not important for us.

the next line <GUILayout > begins the .layout file as far as CEGUI is concerned.

Next up is: <source lang="xml"><Window Type="TaharezLook/FrameWindow" Name="ConsoleRoot" ></source>
This is where the meat begins. As you can see we're creating a window of type "TaharezLook/FrameWindow" with the name "ConsoleRoot."

The next lines:
<source lang="xml"> <Property Name="Text" Value="Chat Window" />
<Property Name="TitlebarFont" Value="DejaVuSans-10" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.114991,0},{0.358182,0},{0.519469,0},{0.775455,0}}" />
</source>
change various PropertySets on that new framewindow. It sets the font, Titlebar and the area. These could also be done in code by calling:
<tabber>
C++=
<source lang="cpp">
CEGUI::Window::setProperty("TitlebarFont","DejaVuSans-10");
</source>
|-|
Python=
<source lang="python">
PyCEGUI.Window.setProperty("TitlebarFont","DejaVuSans-10")
</source>
</tabber>
So as you can see, the scripts can be very useful allowing us to change properties outside of the code, giving the artists a great deal of usability!

Anyway, the next line is <source lang="xml"> <Window Type="TaharezLook/Editbox" Name="ConsoleRoot/EditBox" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedAreaRect" Value="{{0.0201637,0},{0.787097,0},{0.694549,0},{0.957693,0}}" />
<Property Name="TextParsingEnabled" Value="False" />
</Window></source>

You'll notice this is before the </Window> of the ConsoleRoot, so it will be created as a child in of ConsoleRoot when the script is loaded in CEGUI. Can you tell what kind of window this will be? It will be an edit box. Thats the portion of the Console Window where the user will be able to type in what they want to say. I'm not going to go into detail about the rest of the windows, as they are pretty similar to the above examples. But "ConsoleRoot/SendButton" will be the send button, and "ConsoleRoot/ChatBox" will be where the chat messages will display to.

[Note: As you can see I adopted the Naming scheme of Parent/Child window names. This is NOT required, but I think it helps make things easier to read on code side while debugging. You wouldn't want to just name it EditBox as that would be a pretty Common name, and may conflict with other windows you create later on in the application.]

==== Applying our knowledge ====

Now that we have gotten an introduction to the .layout file, we should learn how to implement this knowledge. How to get the layout file to show up in CEGUI.

This code will load the layout into a new window:

<tabber>
C++=
<source lang="cpp">
CEGUI::Window *newWindow = CEGUI::WindowManager::getSingleton().loadWindowLayout("MyConsole.layout");
</source>
|-|
Python=
<source lang="python">
newWindow = PyCEGUI.WindowManager.getSingleton().loadWindowLayout("MyConsole.layout")
</source>
</tabber>

Pretty self explanatory. There is something to note tho, you can add a prefix to the names in this .layout file. This would be useful if you're going to add the same .layout multiple times, because after the first load you'd get name conflicts. It would find a previous "ConsoleRoot" for example. So by calling this

<tabber>
C++=
<source lang="cpp">
CEGUI::Window *newWindow = CEGUI::WindowManager::getSingleton().loadWindowLayout("MyConsole.layout","second_");
</source>
|-|
Python=
<source lang="python">
newWindow = PyCEGUI.WindowManager.getSingleton().loadWindowLayout("MyConsole.layout","second_")
</source>
</tabber>
It would append "second_" to the window names (ie. "second_ConsoleRoot"); This will prevent naming errors.

Now if we ran this right now would we be able to see the window?

Nope. We haven't attached it to the window hierarchy have we?

<tabber>
C++=
<source lang="cpp">
CEGUI::System::getSingleton().getGUISheet()->addChildWindow(newWindow);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.System.getSingleton().getGuiSheet().addChildWindow(newWindow)
</source>
</tabber>
Note: This assumes that you have a GUISheet already set, otherwise this will result in a segfault!

==== Conclusion ====

Well we showed how to load a .layout file. So far now we know how to Start the system with Ogre, create a window and understand properties, add input, process events, and load layouts. In the next tutorial we will apply this knowledge to create a console which actually does something! Till next time.

This list of the Window properties may be helpful in creating your .layout files: [http://www.cegui.org.uk/docs/current/namespaceCEGUI_1_1WindowProperties.html Properties]

[[Category:Tutorials]]

CEGUI In Practice - Using .layout files

2014-03-29T19:13:05Z

Superpws: /* Meet the Layout */

{{VersionBadge|0.7}}
{{Series|CEGUI In Practice|5}}

== CEGUI InPractice 5 ==

In this tutorial we will introduce how to use the .layout file. This is likely what will be used for larger scale projects, where the art team isn't going to want to wait for you to recompile the source for every change they make.

==== Meet the Layout ====

The Layout file (.layout) is an xml file. There exists at least two editors for layouts. The first one is the [[Downloads|CEGUI LayoutEditor]] This is a fairly mature editor. Unfortunately it is deprecated and has not received any updates in sometime. There is a new Editor (CEGUI Layout Editor 2) which is available from the SVN. For the usage of this tutorial tho, we will not be using an editor and will be manipulating the .layout file with a plain old text editor.

First thing to note, is its an XML file. So proper XML formatting is required. Second, is that it is hierarchical just like CEGUI. We will work towards writing a Simple Console here. I have created a console layout, and that will be the goal of this tutorial, to make a console editor like you would find in the various MMORPG's. This is what we'll make today:

[[File:TutorialInPractice-Console.jpg]] 
Attached is the layout:
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<GUILayout >
<Window Type="TaharezLook/FrameWindow" Name="ConsoleRoot" >
<Property Name="Text" Value="Chat Window" />
<Property Name="TitlebarFont" Value="DejaVuSans-10" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.114991,0},{0.358182,0},{0.519469,0},{0.775455,0}}" />
<Window Type="TaharezLook/Editbox" Name="ConsoleRoot/EditBox" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedAreaRect" Value="{{0.0201637,0},{0.787097,0},{0.694549,0},{0.957693,0}}" />
<Property Name="TextParsingEnabled" Value="False" />
</Window>
<Window Type="TaharezLook/Button" Name="ConsoleRoot/SendButton" >
<Property Name="Text" Value="Send" />
<Property Name="UnifiedAreaRect" Value="{{0.732211,0},{0.812349,0},{0.928283,0},{0.946832,0}}" />
</Window>
<Window Type="TaharezLook/Listbox" Name="ConsoleRoot/ChatBox" >
<Property Name="UnifiedAreaRect" Value="{{0.00534809,0},{0.0131038,0},{0.949636,0},{0.762443,0}}" />
</Window>
</Window>
</GUILayout>
</source>

Okay, i'll admit. I cheated and used a LayoutEditor for this. But i'm allowed to, I know what I'm doing otherwise, so do don't back talk me and do your homework.

Erm. Anyway, lets look at the setup of the .layout file.

the first line <xml..> Is just the XML Declaration, and is not important for us.

the next line <GUILayout > begins the .layout file as far as CEGUI is concerned.

Next up is: <source lang="xml"><Window Type="TaharezLook/FrameWindow" Name="ConsoleRoot" ></source>
This is where the meat begins. As you can see we're creating a window of type "TaharezLook/FrameWindow" with the name "ConsoleRoot."

The next lines:
<source lang="xml"> <Property Name="Text" Value="Chat Window" />
<Property Name="TitlebarFont" Value="DejaVuSans-10" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.114991,0},{0.358182,0},{0.519469,0},{0.775455,0}}" />
</source>
change various PropertySets on that new framewindow. It sets the font, Titlebar and the area. These could also be done in code by calling:
<tabber>
C++=
<source lang="cpp">
CEGUI::Window::setProperty("TitlebarFont","DejaVuSans-10");
</source>
|-|
Python=
<source lang="python">
PyCEGUI.Window.setProperty("TitlebarFont","DejaVuSans-10")
</source>
</tabber>
So as you can see, the scripts can be very useful allowing us to change properties outside of the code, giving the artists a great deal of usability!

Anyway, the next line is <source lang="xml"> <Window Type="TaharezLook/Editbox" Name="ConsoleRoot/EditBox" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedAreaRect" Value="{{0.0201637,0},{0.787097,0},{0.694549,0},{0.957693,0}}" />
<Property Name="TextParsingEnabled" Value="False" />
</Window></source>

You'll notice this is before the </Window> of the ConsoleRoot, so it will be created as a child in of ConsoleRoot when the script is loaded in CEGUI. Can you tell what kind of window this will be? It will be an edit box. Thats the portion of the Console Window where the user will be able to type in what they want to say. I'm not going to go into detail about the rest of the windows, as they are pretty similar to the above examples. But "ConsoleRoot/SendButton" will be the send button, and "ConsoleRoot/ChatBox" will be where the chat messages will display to.

[Note: As you can see I adopted the Naming scheme of Parent/Child window names. This is NOT required, but I think it helps make things easier to read on code side while debugging. You wouldn't want to just name it EditBox as that would be a pretty Common name, and may conflict with other windows you create later on in the application.]

==== Applying our knowledge ====

Now that we have gotten an introduction to the .layout file, we should learn how to implement this knowledge. How to get the layout file to show up in CEGUI.

This code will load the layout into a new window:

<tabs>
<tab title="C++">
<source lang="cpp">
CEGUI::Window *newWindow = CEGUI::WindowManager::getSingleton().loadWindowLayout("MyConsole.layout");
</source>
</tab>
<tab title="Python">
<source lang="python">
newWindow = PyCEGUI.WindowManager.getSingleton().loadWindowLayout("MyConsole.layout")
</source>
</tab>
</tabs>

Pretty self explanatory. There is something to note tho, you can add a prefix to the names in this .layout file. This would be useful if you're going to add the same .layout multiple times, because after the first load you'd get name conflicts. It would find a previous "ConsoleRoot" for example. So by calling this

<tabs>
<tab title="C++">
<source lang="cpp">
CEGUI::Window *newWindow = CEGUI::WindowManager::getSingleton().loadWindowLayout("MyConsole.layout","second_");
</source>
</tab>
<tab title="Python">
<source lang="python">
newWindow = PyCEGUI.WindowManager.getSingleton().loadWindowLayout("MyConsole.layout","second_")
</source>
</tab>
</tabs>
It would append "second_" to the window names (ie. "second_ConsoleRoot"); This will prevent naming errors.

Now if we ran this right now would we be able to see the window?

Nope. We haven't attached it to the window hierarchy have we?

<tabs>
<tab title="C++">
<source lang="cpp">
CEGUI::System::getSingleton().getGUISheet()->addChildWindow(newWindow);
</source>
</tab>
<tab title="Python">
<source lang="python">
PyCEGUI.System.getSingleton().getGuiSheet().addChildWindow(newWindow)
</source>
</tab>
</tabs>
Note: This assumes that you have a GUISheet already set, otherwise this will result in a segfault!

==== Conclusion ====

Well we showed how to load a .layout file. So far now we know how to Start the system with Ogre, create a window and understand properties, add input, process events, and load layouts. In the next tutorial we will apply this knowledge to create a console which actually does something! Till next time.

This list of the Window properties may be helpful in creating your .layout files: [http://www.cegui.org.uk/docs/current/namespaceCEGUI_1_1WindowProperties.html Properties]

[[Category:Tutorials]]

CEGUI In Practice - Introduction

2014-03-29T14:37:09Z

Superpws: /* Back to Getting Started */

{{VersionBadge|0.7}}
{{Series|CEGUI In Practice|1}}

== CEGUI In-Practice ==

Welcome to the first in a series of tutorials based on how to use CEGUI. The majority of the tutorials will be done in code. I may attempt to sprinkle in uses of .layouts throughout the tutorial. But once you understand how to use many of the Widgets in code it becomes easy to use them via script.

[Please note, I am an Ogre3d user, so the initial setup will be how to bootstrap and start with ogre3d.]

=== Introducing CEGUI ===
First notes, CEGUI uses a number of Singleton classes. These, if not experienced with singletons, allow global access to a Class globally in the code, while ensuring only a 'single'ton instance is ever created. The following are the Singletons we will be using
in this example.

'''CEGUI::{{DoxygenClass|System|0.7}}''' - The big Kahuna. This contains many of the functions for setting and getting defaults. 
'''CEGUI::{{DoxygenClass|WindowManager|0.7}}''' - Manages the windows of CEGUI. If a new window is going to be created or Deleted WindowManager is gonna be your class. 

'''CEGUI::{{DoxygenClass|SchemeManager|0.7}}''' - Manages Schemes. 
'''CEGUI::{{DoxygenClass|FontManager|0.7}}''' - Manages the different fonts you will use in your application. 

==== Getting Started ====

Let's jump in and get some stuff setup. The first thing we need to do is get the system up and running. Since I am an Ogre user, I will show the code to get the system up and running with ogre. There are methods of getting it started for numerous other Rendering systems. Shown here [[The Beginner Guide to Getting CEGUI Rendering]]. 

The Ogre3d Method is shown here:

===== Including necessary headers =====
<tabber>
C++=
<source lang="cpp">
#include "CEGUI.h"
#include "RendererModules/Ogre/CEGUIOgreRenderer.h"
</source>
|-|
Python=
<source lang="python">
import PyCEGUI
import PyCEGUIOgreRenderer
</source>
</tabber>

===== Bootstrapping CEGUI =====

<tabber>
C++=
<source lang="cpp">
CEGUI::OgreRenderer* renderer = &CEGUI::OgreRenderer::bootstrapSystem();
</source>
|-|
Python=
<source lang="python">
renderer = PyCEGUIOgreRenderer.OgreRenderer.bootstrapSystem()
</source>
</tabber>

[Note: This is a newer method using the bootstrapSystem, this was introduced in CEGUI 0.7.1. There are examples on this wiki using older versions of CEGUI. Please make note of which version you are using] 

The above code creates an instance of the Ogre3d Render interface between Ogre3d and CEGUI. You will not need to deal with this much after the above code has been run. This creates the link which Ogre will use to render CEGUI. Please note, you will want to call this if Ogre is auto-creating the render window ( pretty common ). If you are manually creating the Ogre3d window, you will need to use the ''CEGUI::OgreRenderer::bootstrapSystem(Ogre::RenderWindow *)'' overload.

An additional point to mention is that the bootstrapSystem() will create an instance of CEGUI::System. This is important, as if you already have created CEGUI::System, an exception will be thrown.

==== Oh there will be scripts ====

Now that we've called the very meager function above. We need to cover some very basic information about CEGUI before we proceed.

CEGUI is a VERY heavily scripted library. Much of what defines the artistic content of CEGUI is defined in various .xml files. The beginning script we will mention is the '''Scheme''' (*.scheme). Every widget you will use in your GUI will be defined in the .scheme file. It will also contain information for about subscripts which will be used, described below. Later tutorials will describe this file in greater detail. Below is an example if you run across one:

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

<LookNFeel Filename="TaharezLook.looknfeel" />
<WindowRendererSet Filename="CEGUIFalagardWRBase" />
<FalagardMapping WindowType="TaharezLook/Button" TargetType="CEGUI/PushButton" Renderer="Falagard/Button" LookNFeel="TaharezLook/Button" />
<FalagardMapping WindowType="TaharezLook/Checkbox" TargetType="CEGUI/Checkbox" Renderer="Falagard/ToggleButton" LookNFeel="TaharezLook/Checkbox" />
</GUIScheme></source> 

The next script we will mention is the '''Layouts''' (*.layout). This is also an xml file, which defines the layout (obviously!) of the window we want to display on the screen. For example, if we wanted a to create a Chat window, we would probably have a ChatWindow.layout file somewhere. This would describe how the window looks (How big, where on the screen its displayed, etc), where the typing box would be located within this window, and where the button to 'send' the chat message would be. Below is a quick example of what a .layout file looks like:

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<GUILayout >
<Window Type="TaharezLook/FrameWindow" Name="ConsoleRoot" >
<Property Name="Text" Value="Chat Window" />
<Property Name="TitlebarFont" Value="DejaVuSans-10" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.114991,0},{0.358182,0},{0.519469,0},{0.775455,0}}" />
<Window Type="TaharezLook/Editbox" Name="ConsoleRoot/EditBox" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedAreaRect" Value="{{0.0201637,0},{0.787097,0},{0.694549,0},{0.957693,0}}" />
<Property Name="TextParsingEnabled" Value="False" />
</Window>
</GUILayout>
</source>

Another script which is useful to mention is a '''Font''' (*.font). This describes fonts which will be used in cegui. Below is an example:

<source lang="xml"><?xml version="1.0" ?>

</source>

Another important script is the '''Imageset''' (*.imageset). This is the file which determines the visuals of each widget. In CEGUI the visual part of a widget which the user see's is a small X/Y coordinate on a larger texture file. For example, a basic Button will have the graphics defined in a .imageset to be a certain position on a texture image (*.png, *.bmp, *.jpg, etc) with a certain height and width. It may be located at Pixel 100x320 and be 50x50 in size. This will be defined in the imageset. Below is an example.

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

Lastly, '''LookNFeel''' (*.looknfeel). This is a fairly evil looking file, and to save everyone from nightmarish horrors, I will not post an example (and to save space). This is the file which determines how every widget (CEGUI speak for window/object/item) looks and acts. For example, what it looks like when you mouse over a button, or how to build the border and background of a Window. Each scheme will generally have its own LookNFeel to allow more customization of the basic construction of CEGUI Widgets.

==== Back to Getting Started ====

Now that we have a minimal idea about what scripts CEGUI uses (and don't worry, they make more sense and are less intimidating as you proceede. You will likely use .layout the most in the beginning) lets start doing something useful!

Where we left off, CEGUI was just started. But in and of itself, it doesn't know what you want to do. First thing we should do is tell it what Scheme we want to use. As mentioned above, a .Scheme contains a listing of Widget and Other scripts to include, a Scheme can include an Imageset, lookNFeel, and font to use.

<tabber>
C++=
<source lang="cpp">
// Load the scheme
CEGUI::SchemeManager::getSingleton().create( "TaharezLook.scheme" );
</source>
|-|
Python=
<source lang="python">
# Load the scheme
PyCEGUI.SchemeManager.getSingleton().create( "TaharezLook.scheme" )
</source>
</tabber>

If you wanted to use an imageset or Font which is not designated in the .Scheme file its easy to do. Simply use the associated manager to load them. Since i'm trying my best to keep this as an introductory tutorial, I'll keep to the mission and explain these managers in a later tutorial.

Next up, lets define a few defaults:

<tabber>
C++=
<source lang="cpp">
// Set the defaults
CEGUI::System::getSingleton().setDefaultFont( "DejaVuSans-10" );
CEGUI::System::getSingleton().setDefaultMouseCursor( "TaharezLook", "MouseArrow" );
</source>
|-|
Python=
<source lang="python">
# Set the defaults
PyCEGUI.System.getSingleton().setDefaultFont( "DejaVuSans-10" )
PyCEGUI.System.getSingleton().setDefaultMouseCursor( "TaharezLook", "MouseArrow" )
</source>
</tabber>

These calls will summon the CEGUI::System from global scope and set the DefaultFont, and the default Mouse Cursor. If you reference TaharezLook.scheme (located in the cegui/datafiles/schemes folder). You will see that it loaded a font named DejaVuSans-10.font with the tag in the .scheme. The MouseArrow is found inside the imageset called "TharezLook" under the tag of "MouseArrow". Pretty self explanetory I'd hope.

Alright, now CEGUI knows about some basic defaults we want to use. Lets create a window which will be the Root window we will put everything on from here on out.

CEGUI uses a Parent/Child system for organizing the windows. So the first useful thing to do is create a parent which all other windows will be the child

<tabber>
C++=
<source lang="cpp">
CEGUI::Window* myRoot = CEGUI::WindowManager::getSingleton().createWindow( "DefaultWindow", "_MasterRoot" );
</source>
|-|
Python=
<source lang="python">
myRoot = PyCEGUI.WindowManager.getSingleton().createWindow( "DefaultWindow", "_MasterRoot" )
</source>
</tabber>

The above function calls upon the WindowManager singleton, and creates a window of type "DefaultWindow" named "_MasterRoot". The default window is just that. a default window, which is blank (or transparent). You can give the root window any name you like, however, i like using _MasterRoot as its unlikely any other window I ever use will have the name.

Now that we have created the window, we need to set it as the root window.

<tabber>
C++=
<source lang="cpp">
CEGUI::System::getSingleton().setGUISheet( myRoot );
</source>
|-|
Python=
<source lang="python">
PyCEGUI.System.getSingleton().setGUISheet( myRoot )
</source>
</tabber>

This calls upon the system, and assigns myRoot as the default window. Recall myRoot was created above with the name "_MasterRoot".

==== Conclusion ====

While not a super exciting tutorial. At this point CEGUI is now setup, and we could begin adding windows and doing such GUI shenanigans as making windows, buttons, clicking, and fun. Later tutorials will demonstrate how to have CEGUI Recognize clicking, dragging of windows, typing, and more! Thanks for reading!

[[Category:Tutorials]]

CEGUI In Practice - Introduction

2014-03-29T14:32:29Z

Superpws: /* Bootstrapping CEGUI */

{{VersionBadge|0.7}}
{{Series|CEGUI In Practice|1}}

== CEGUI In-Practice ==

Welcome to the first in a series of tutorials based on how to use CEGUI. The majority of the tutorials will be done in code. I may attempt to sprinkle in uses of .layouts throughout the tutorial. But once you understand how to use many of the Widgets in code it becomes easy to use them via script.

[Please note, I am an Ogre3d user, so the initial setup will be how to bootstrap and start with ogre3d.]

=== Introducing CEGUI ===
First notes, CEGUI uses a number of Singleton classes. These, if not experienced with singletons, allow global access to a Class globally in the code, while ensuring only a 'single'ton instance is ever created. The following are the Singletons we will be using
in this example.

'''CEGUI::{{DoxygenClass|System|0.7}}''' - The big Kahuna. This contains many of the functions for setting and getting defaults. 
'''CEGUI::{{DoxygenClass|WindowManager|0.7}}''' - Manages the windows of CEGUI. If a new window is going to be created or Deleted WindowManager is gonna be your class. 

'''CEGUI::{{DoxygenClass|SchemeManager|0.7}}''' - Manages Schemes. 
'''CEGUI::{{DoxygenClass|FontManager|0.7}}''' - Manages the different fonts you will use in your application. 

==== Getting Started ====

Let's jump in and get some stuff setup. The first thing we need to do is get the system up and running. Since I am an Ogre user, I will show the code to get the system up and running with ogre. There are methods of getting it started for numerous other Rendering systems. Shown here [[The Beginner Guide to Getting CEGUI Rendering]]. 

The Ogre3d Method is shown here:

===== Including necessary headers =====
<tabber>
C++=
<source lang="cpp">
#include "CEGUI.h"
#include "RendererModules/Ogre/CEGUIOgreRenderer.h"
</source>
|-|
Python=
<source lang="python">
import PyCEGUI
import PyCEGUIOgreRenderer
</source>
</tabber>

===== Bootstrapping CEGUI =====

<tabber>
C++=
<source lang="cpp">
CEGUI::OgreRenderer* renderer = &CEGUI::OgreRenderer::bootstrapSystem();
</source>
|-|
Python=
<source lang="python">
renderer = PyCEGUIOgreRenderer.OgreRenderer.bootstrapSystem()
</source>
</tabber>

[Note: This is a newer method using the bootstrapSystem, this was introduced in CEGUI 0.7.1. There are examples on this wiki using older versions of CEGUI. Please make note of which version you are using] 

The above code creates an instance of the Ogre3d Render interface between Ogre3d and CEGUI. You will not need to deal with this much after the above code has been run. This creates the link which Ogre will use to render CEGUI. Please note, you will want to call this if Ogre is auto-creating the render window ( pretty common ). If you are manually creating the Ogre3d window, you will need to use the ''CEGUI::OgreRenderer::bootstrapSystem(Ogre::RenderWindow *)'' overload.

An additional point to mention is that the bootstrapSystem() will create an instance of CEGUI::System. This is important, as if you already have created CEGUI::System, an exception will be thrown.

==== Oh there will be scripts ====

Now that we've called the very meager function above. We need to cover some very basic information about CEGUI before we proceed.

CEGUI is a VERY heavily scripted library. Much of what defines the artistic content of CEGUI is defined in various .xml files. The beginning script we will mention is the '''Scheme''' (*.scheme). Every widget you will use in your GUI will be defined in the .scheme file. It will also contain information for about subscripts which will be used, described below. Later tutorials will describe this file in greater detail. Below is an example if you run across one:

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

<LookNFeel Filename="TaharezLook.looknfeel" />
<WindowRendererSet Filename="CEGUIFalagardWRBase" />
<FalagardMapping WindowType="TaharezLook/Button" TargetType="CEGUI/PushButton" Renderer="Falagard/Button" LookNFeel="TaharezLook/Button" />
<FalagardMapping WindowType="TaharezLook/Checkbox" TargetType="CEGUI/Checkbox" Renderer="Falagard/ToggleButton" LookNFeel="TaharezLook/Checkbox" />
</GUIScheme></source> 

The next script we will mention is the '''Layouts''' (*.layout). This is also an xml file, which defines the layout (obviously!) of the window we want to display on the screen. For example, if we wanted a to create a Chat window, we would probably have a ChatWindow.layout file somewhere. This would describe how the window looks (How big, where on the screen its displayed, etc), where the typing box would be located within this window, and where the button to 'send' the chat message would be. Below is a quick example of what a .layout file looks like:

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<GUILayout >
<Window Type="TaharezLook/FrameWindow" Name="ConsoleRoot" >
<Property Name="Text" Value="Chat Window" />
<Property Name="TitlebarFont" Value="DejaVuSans-10" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.114991,0},{0.358182,0},{0.519469,0},{0.775455,0}}" />
<Window Type="TaharezLook/Editbox" Name="ConsoleRoot/EditBox" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedAreaRect" Value="{{0.0201637,0},{0.787097,0},{0.694549,0},{0.957693,0}}" />
<Property Name="TextParsingEnabled" Value="False" />
</Window>
</GUILayout>
</source>

Another script which is useful to mention is a '''Font''' (*.font). This describes fonts which will be used in cegui. Below is an example:

<source lang="xml"><?xml version="1.0" ?>

</source>

Another important script is the '''Imageset''' (*.imageset). This is the file which determines the visuals of each widget. In CEGUI the visual part of a widget which the user see's is a small X/Y coordinate on a larger texture file. For example, a basic Button will have the graphics defined in a .imageset to be a certain position on a texture image (*.png, *.bmp, *.jpg, etc) with a certain height and width. It may be located at Pixel 100x320 and be 50x50 in size. This will be defined in the imageset. Below is an example.

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

Lastly, '''LookNFeel''' (*.looknfeel). This is a fairly evil looking file, and to save everyone from nightmarish horrors, I will not post an example (and to save space). This is the file which determines how every widget (CEGUI speak for window/object/item) looks and acts. For example, what it looks like when you mouse over a button, or how to build the border and background of a Window. Each scheme will generally have its own LookNFeel to allow more customization of the basic construction of CEGUI Widgets.

==== Back to Getting Started ====

Now that we have a minimal idea about what scripts CEGUI uses (and don't worry, they make more sense and are less intimidating as you proceede. You will likely use .layout the most in the beginning) lets start doing something useful!

Where we left off, CEGUI was just started. But in and of itself, it doesn't know what you want to do. First thing we should do is tell it what Scheme we want to use. As mentioned above, a .Scheme contains a listing of Widget and Other scripts to include, a Scheme can include an Imageset, lookNFeel, and font to use.

<tabs>
<tab title="C++">
<source lang="cpp">
// Load the scheme
CEGUI::SchemeManager::getSingleton().create( "TaharezLook.scheme" );
</source>
</tab>
<tab title="Python">
<source lang="python">
# Load the scheme
PyCEGUI.SchemeManager.getSingleton().create( "TaharezLook.scheme" )
</source>
</tab>
</tabs>

If you wanted to use an imageset or Font which is not designated in the .Scheme file its easy to do. Simply use the associated manager to load them. Since i'm trying my best to keep this as an introductory tutorial, I'll keep to the mission and explain these managers in a later tutorial.

Next up, lets define a few defaults:

<tabs>
<tab title="C++">
<source lang="cpp">
// Set the defaults
CEGUI::System::getSingleton().setDefaultFont( "DejaVuSans-10" );
CEGUI::System::getSingleton().setDefaultMouseCursor( "TaharezLook", "MouseArrow" );
</source>
</tab>
<tab title="Python">
<source lang="python">
# Set the defaults
PyCEGUI.System.getSingleton().setDefaultFont( "DejaVuSans-10" )
PyCEGUI.System.getSingleton().setDefaultMouseCursor( "TaharezLook", "MouseArrow" )
</source>
</tab>
</tabs>

These calls will summon the CEGUI::System from global scope and set the DefaultFont, and the default Mouse Cursor. If you reference TaharezLook.scheme (located in the cegui/datafiles/schemes folder). You will see that it loaded a font named DejaVuSans-10.font with the tag in the .scheme. The MouseArrow is found inside the imageset called "TharezLook" under the tag of "MouseArrow". Pretty self explanetory I'd hope.

Alright, now CEGUI knows about some basic defaults we want to use. Lets create a window which will be the Root window we will put everything on from here on out.

CEGUI uses a Parent/Child system for organizing the windows. So the first useful thing to do is create a parent which all other windows will be the child

<tabs>
<tab title="C++">
<source lang="cpp">
CEGUI::Window* myRoot = CEGUI::WindowManager::getSingleton().createWindow( "DefaultWindow", "_MasterRoot" );
</source>
</tab>
<tab title="Python">
<source lang="python">
myRoot = PyCEGUI.WindowManager.getSingleton().createWindow( "DefaultWindow", "_MasterRoot" )
</source>
</tab>
</tabs>

The above function calls upon the WindowManager singleton, and creates a window of type "DefaultWindow" named "_MasterRoot". The default window is just that. a default window, which is blank (or transparent). You can give the root window any name you like, however, i like using _MasterRoot as its unlikely any other window I ever use will have the name.

Now that we have created the window, we need to set it as the root window.

<tabs>
<tab title="C++">
<source lang="cpp">
CEGUI::System::getSingleton().setGUISheet( myRoot );
</source>
</tab>
<tab title="Python">
<source lang="python">
PyCEGUI.System.getSingleton().setGUISheet( myRoot )
</source>
</tab>
</tabs>

This calls upon the system, and assigns myRoot as the default window. Recall myRoot was created above with the name "_MasterRoot".

==== Conclusion ====

While not a super exciting tutorial. At this point CEGUI is now setup, and we could begin adding windows and doing such GUI shenanigans as making windows, buttons, clicking, and fun. Later tutorials will demonstrate how to have CEGUI Recognize clicking, dragging of windows, typing, and more! Thanks for reading!

[[Category:Tutorials]]

CEGUI In Practice - Introduction

2014-03-29T14:29:42Z

Superpws: /* Including necessary headers */

{{VersionBadge|0.7}}
{{Series|CEGUI In Practice|1}}

== CEGUI In-Practice ==

Welcome to the first in a series of tutorials based on how to use CEGUI. The majority of the tutorials will be done in code. I may attempt to sprinkle in uses of .layouts throughout the tutorial. But once you understand how to use many of the Widgets in code it becomes easy to use them via script.

[Please note, I am an Ogre3d user, so the initial setup will be how to bootstrap and start with ogre3d.]

=== Introducing CEGUI ===
First notes, CEGUI uses a number of Singleton classes. These, if not experienced with singletons, allow global access to a Class globally in the code, while ensuring only a 'single'ton instance is ever created. The following are the Singletons we will be using
in this example.

'''CEGUI::{{DoxygenClass|System|0.7}}''' - The big Kahuna. This contains many of the functions for setting and getting defaults. 
'''CEGUI::{{DoxygenClass|WindowManager|0.7}}''' - Manages the windows of CEGUI. If a new window is going to be created or Deleted WindowManager is gonna be your class. 

'''CEGUI::{{DoxygenClass|SchemeManager|0.7}}''' - Manages Schemes. 
'''CEGUI::{{DoxygenClass|FontManager|0.7}}''' - Manages the different fonts you will use in your application. 

==== Getting Started ====

Let's jump in and get some stuff setup. The first thing we need to do is get the system up and running. Since I am an Ogre user, I will show the code to get the system up and running with ogre. There are methods of getting it started for numerous other Rendering systems. Shown here [[The Beginner Guide to Getting CEGUI Rendering]]. 

The Ogre3d Method is shown here:

===== Including necessary headers =====
<tabber>
C++=
<source lang="cpp">
#include "CEGUI.h"
#include "RendererModules/Ogre/CEGUIOgreRenderer.h"
</source>
|-|
Python=
<source lang="python">
import PyCEGUI
import PyCEGUIOgreRenderer
</source>
</tabber>

===== Bootstrapping CEGUI =====

<tabs>
<tab title="C++">
<source lang="cpp">CEGUI::OgreRenderer* renderer = &CEGUI::OgreRenderer::bootstrapSystem();</source>
</tab>
<tab title="Python">
<source lang="python">renderer = PyCEGUIOgreRenderer.OgreRenderer.bootstrapSystem()</source>
</tab>
</tabs>

[Note: This is a newer method using the bootstrapSystem, this was introduced in CEGUI 0.7.1. There are examples on this wiki using older versions of CEGUI. Please make note of which version you are using] 

The above code creates an instance of the Ogre3d Render interface between Ogre3d and CEGUI. You will not need to deal with this much after the above code has been run. This creates the link which Ogre will use to render CEGUI. Please note, you will want to call this if Ogre is auto-creating the render window ( pretty common ). If you are manually creating the Ogre3d window, you will need to use the ''CEGUI::OgreRenderer::bootstrapSystem(Ogre::RenderWindow *)'' overload.

An additional point to mention is that the bootstrapSystem() will create an instance of CEGUI::System. This is important, as if you already have created CEGUI::System, an exception will be thrown.

==== Oh there will be scripts ====

Now that we've called the very meager function above. We need to cover some very basic information about CEGUI before we proceed.

CEGUI is a VERY heavily scripted library. Much of what defines the artistic content of CEGUI is defined in various .xml files. The beginning script we will mention is the '''Scheme''' (*.scheme). Every widget you will use in your GUI will be defined in the .scheme file. It will also contain information for about subscripts which will be used, described below. Later tutorials will describe this file in greater detail. Below is an example if you run across one:

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

<LookNFeel Filename="TaharezLook.looknfeel" />
<WindowRendererSet Filename="CEGUIFalagardWRBase" />
<FalagardMapping WindowType="TaharezLook/Button" TargetType="CEGUI/PushButton" Renderer="Falagard/Button" LookNFeel="TaharezLook/Button" />
<FalagardMapping WindowType="TaharezLook/Checkbox" TargetType="CEGUI/Checkbox" Renderer="Falagard/ToggleButton" LookNFeel="TaharezLook/Checkbox" />
</GUIScheme></source> 

The next script we will mention is the '''Layouts''' (*.layout). This is also an xml file, which defines the layout (obviously!) of the window we want to display on the screen. For example, if we wanted a to create a Chat window, we would probably have a ChatWindow.layout file somewhere. This would describe how the window looks (How big, where on the screen its displayed, etc), where the typing box would be located within this window, and where the button to 'send' the chat message would be. Below is a quick example of what a .layout file looks like:

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<GUILayout >
<Window Type="TaharezLook/FrameWindow" Name="ConsoleRoot" >
<Property Name="Text" Value="Chat Window" />
<Property Name="TitlebarFont" Value="DejaVuSans-10" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.114991,0},{0.358182,0},{0.519469,0},{0.775455,0}}" />
<Window Type="TaharezLook/Editbox" Name="ConsoleRoot/EditBox" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedAreaRect" Value="{{0.0201637,0},{0.787097,0},{0.694549,0},{0.957693,0}}" />
<Property Name="TextParsingEnabled" Value="False" />
</Window>
</GUILayout>
</source>

Another script which is useful to mention is a '''Font''' (*.font). This describes fonts which will be used in cegui. Below is an example:

<source lang="xml"><?xml version="1.0" ?>

</source>

Another important script is the '''Imageset''' (*.imageset). This is the file which determines the visuals of each widget. In CEGUI the visual part of a widget which the user see's is a small X/Y coordinate on a larger texture file. For example, a basic Button will have the graphics defined in a .imageset to be a certain position on a texture image (*.png, *.bmp, *.jpg, etc) with a certain height and width. It may be located at Pixel 100x320 and be 50x50 in size. This will be defined in the imageset. Below is an example.

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

Lastly, '''LookNFeel''' (*.looknfeel). This is a fairly evil looking file, and to save everyone from nightmarish horrors, I will not post an example (and to save space). This is the file which determines how every widget (CEGUI speak for window/object/item) looks and acts. For example, what it looks like when you mouse over a button, or how to build the border and background of a Window. Each scheme will generally have its own LookNFeel to allow more customization of the basic construction of CEGUI Widgets.

==== Back to Getting Started ====

Now that we have a minimal idea about what scripts CEGUI uses (and don't worry, they make more sense and are less intimidating as you proceede. You will likely use .layout the most in the beginning) lets start doing something useful!

Where we left off, CEGUI was just started. But in and of itself, it doesn't know what you want to do. First thing we should do is tell it what Scheme we want to use. As mentioned above, a .Scheme contains a listing of Widget and Other scripts to include, a Scheme can include an Imageset, lookNFeel, and font to use.

<tabs>
<tab title="C++">
<source lang="cpp">
// Load the scheme
CEGUI::SchemeManager::getSingleton().create( "TaharezLook.scheme" );
</source>
</tab>
<tab title="Python">
<source lang="python">
# Load the scheme
PyCEGUI.SchemeManager.getSingleton().create( "TaharezLook.scheme" )
</source>
</tab>
</tabs>

If you wanted to use an imageset or Font which is not designated in the .Scheme file its easy to do. Simply use the associated manager to load them. Since i'm trying my best to keep this as an introductory tutorial, I'll keep to the mission and explain these managers in a later tutorial.

Next up, lets define a few defaults:

<tabs>
<tab title="C++">
<source lang="cpp">
// Set the defaults
CEGUI::System::getSingleton().setDefaultFont( "DejaVuSans-10" );
CEGUI::System::getSingleton().setDefaultMouseCursor( "TaharezLook", "MouseArrow" );
</source>
</tab>
<tab title="Python">
<source lang="python">
# Set the defaults
PyCEGUI.System.getSingleton().setDefaultFont( "DejaVuSans-10" )
PyCEGUI.System.getSingleton().setDefaultMouseCursor( "TaharezLook", "MouseArrow" )
</source>
</tab>
</tabs>

These calls will summon the CEGUI::System from global scope and set the DefaultFont, and the default Mouse Cursor. If you reference TaharezLook.scheme (located in the cegui/datafiles/schemes folder). You will see that it loaded a font named DejaVuSans-10.font with the tag in the .scheme. The MouseArrow is found inside the imageset called "TharezLook" under the tag of "MouseArrow". Pretty self explanetory I'd hope.

Alright, now CEGUI knows about some basic defaults we want to use. Lets create a window which will be the Root window we will put everything on from here on out.

CEGUI uses a Parent/Child system for organizing the windows. So the first useful thing to do is create a parent which all other windows will be the child

<tabs>
<tab title="C++">
<source lang="cpp">
CEGUI::Window* myRoot = CEGUI::WindowManager::getSingleton().createWindow( "DefaultWindow", "_MasterRoot" );
</source>
</tab>
<tab title="Python">
<source lang="python">
myRoot = PyCEGUI.WindowManager.getSingleton().createWindow( "DefaultWindow", "_MasterRoot" )
</source>
</tab>
</tabs>

The above function calls upon the WindowManager singleton, and creates a window of type "DefaultWindow" named "_MasterRoot". The default window is just that. a default window, which is blank (or transparent). You can give the root window any name you like, however, i like using _MasterRoot as its unlikely any other window I ever use will have the name.

Now that we have created the window, we need to set it as the root window.

<tabs>
<tab title="C++">
<source lang="cpp">
CEGUI::System::getSingleton().setGUISheet( myRoot );
</source>
</tab>
<tab title="Python">
<source lang="python">
PyCEGUI.System.getSingleton().setGUISheet( myRoot )
</source>
</tab>
</tabs>

This calls upon the system, and assigns myRoot as the default window. Recall myRoot was created above with the name "_MasterRoot".

==== Conclusion ====

While not a super exciting tutorial. At this point CEGUI is now setup, and we could begin adding windows and doing such GUI shenanigans as making windows, buttons, clicking, and fun. Later tutorials will demonstrate how to have CEGUI Recognize clicking, dragging of windows, typing, and more! Thanks for reading!

[[Category:Tutorials]]

CEGUI In Practice - Creating widgets

2014-03-29T14:03:42Z

Superpws: /* The Unified Dimension System */

{{VersionBadge|0.7}}
{{Series|CEGUI In Practice|2}}

== CEGUI In-Practice 2 ==

Welcome back. This is the second installment of CEGUI In-Practice tutorial series. In this we will build upon the previous tutorial, [[CEGUI In Practice - Introduction]]. We will show how to create Widgets and manage them.

=== The Widget ===

In the last example we showed how to bootstrap the system with Ogre, and gave a brief introduction to CEGUI's script files. Now we will work on understanding what a widget is and how to use them. Lets jump in and create a window which will display a box with an image in the middle of the screen:

<tabber>
C++=
<source lang="cpp">
CEGUI::Window *myImageWindow = CEGUI::WindowManager::getSingleton().createWindow("TaharezLook/StaticImage","PrettyWindow" );
</source>
|-|
Python=
<source lang="python">
myImageWindow = PyCEGUI.WindowManager.getSingleton().createWindow("TaharezLook/StaticImage","PrettyWindow" )
</source>
</tabber>

CEGUI uses numerous derived classes code-side to create windows. The base class CEGUI::Window is the generic window. the CEGUI::WindowManager calls a factory class when creating a window which returns the windows pointer. The first argument, "TaharezLook/StaticImage" tells the factory what kind of window to make. These windows are defined in .scheme, which are subsequently defined more depth in other .xml files. The second argument is the name which the window will have.

[Note: As a point to note, there is no strict requirement on naming of windows, except to avoid repeat names. Some users tend to prefer a naming convention using ParentName/ChildName. ie. "ConsoleWindow/SendButton" or "_MasterRoot/HealthBar"]

Once we have created the window, myImageWindow will be a pointer to a CEGUI::{{DoxygenClass|DefaultWindow|0.7}} which is derived from CEGUI::{{DoxygenClass|Window|0.7}}. If you look in the .scheme file you can see can see what a Widget is derived from via the TargetType= tag.

Next we need to set some properties for this window. There are two ways of doing this. The first is via the propertyset, or the second way by calling the function. The latter way can be more annoying at times, as you may have to cast the window to the correct type to get access to the member functions, but may be more intuitive depending on how you think.

=== The Unified Dimension System ===

We created our widget, now we need to position it and define its size. Lets do that via code shall we?

Before we jump in too far, we need to understand how CEGUI Handles positions. CEGUI Uses a Unified Dimension system.

<tabber>
C++=
<source lang="cpp">
CEGUI::UDim(scale,offset);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.UDim(scale,offset)
</source>
</tabber>

The first number is the relative point on the screen between (0,1). So if we were looking at the X axis (left to right on the screen) a UDim(0.5,0) would be Halfway across the screen with zero pixels offset. Udim(0.0,50) would be starting at the left side of the screen +50 pixels. You can combine them too Udim(0.75,10) would be 3/4 of the way across the screen, with an additional 10 pixels.

A point on the screen (or a UVector2) is made up of two UDims:

<tabber>
C++=
<source lang="cpp">
CEGUI::UVector2(UDim x,UDim y);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.UVector2(UDim x, UDim y)
</source>
</tabber>

As such, a CEGUI::Rect is as you would imagine, 4 UDims

<tabber>
C++=
<source lang="cpp">
CEGUI::URect(CEGUI::Udim left,CEGUI::Udim top,CEGUI::Udim right,CEGUI::Udim bottom);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.URect(PyCEGUI.Udim left, PyCEGUI.Udim top, PyCEGUI.Udim right, PyCEGUI.Udim bottom)
</source>
</tabber>

So now that we know how positions are done, lets move our created window to the middle of the screen:
==== The Widget in Practice ====

<tabber>
C++=
<source lang="cpp">
myImageWindow->setPosition(CEGUI::UVector2(CEGUI::UDim(0.5,0),CEGUI::UDim(0.5,0)));
</source>
|-|
Python=
<source lang="python">
myImageWindow.setPosition(PyCEGUI.UVector2(PyCEGUI.UDim(0.5,0), PyCEGUI.UDim(0.5,0)))
</source>
</tabber>

That may look a little ugly but break it down. setPosition takes a UVector2, and each UVector2 is made up of an X and Y Udim, which is made up of a Scale and Absolute float.

So, we have moved our window to the middle of the screen.. but CEGUI doesn't know how big to make it? So set its size to 150 pixels by 100 pixels [Note: I dropped the namespace for this to increase readability].

<tabber>
C++=
<source lang="cpp">
myImageWindow->setSize(UVector2(UDim(0,150),UDim(0,100)));
</source>
|-|
Python=
<source lang="python">
myImageWindow.setSize(UVector2(UDim(0,150),UDim(0,100)));
</source>
</tabber>

In this case we specified the Udim using 0 for scales, and the actual pixel size in the absolute argument. The Absolute argument is additive to the scale, and in this case we didn't want to have the size be affected by the scale argument. If we were creating a splash screen that took up the entire window, we would likely want the size to be UVector2(UDim(1,0),UDim(1,0) with the position being at UVector2(Udim(0,0), UDim(0,0).

Now that we have created the window to the size we want. We need to tell it what image to display! That we will do by using the PropertySet as follows.

<tabber>
C++=
<source lang="cpp">
myImageWindow->setProperty("Image","set:TaharezLook image:full_image");
</source>
|-|
Python=
<source lang="python">
myImageWindow.setProperty("Image","set:TaharezLook image:full_image")
</source>
</tabber>

The first agument is what Property we want to set, and the second argument is what value to set. The second argument is a string broken into two pieces in this example. We need to know what ImageSet we are looking in, which is referenced following the 'set:' portion. And then the image via the 'image:' portion. In this case we want it to show the full_image.

A Listing of properties for TaharezLook is available here [http://cegui.org.uk/static/TaharezLookProperties.html]

Now that we have created the window. We need to attach it to the current root window.

<tabber>
C++=
<source lang="cpp">
CEGUI::System::getSingleton().getGUISheet()->addChildWindow(myImageWindow);
</source>
|-|
Python=
<source lang="python">
PyCEGUI.System.getSingleton().getGUISheet().addChildWindow(myImageWindow)
</source>
</tabber>

This will allow the Window to be displayed.

==== Conclusion ====

So with this quick tutorial we got a very short introduction to PropertySet usage (Important!) and a little bit about how the Unified Dimension System in CEGUI Works. While still not terribly useful, we're beginning to understand how to use some of CEGUI's faculties. Next up, we'll learn how to get some interactivity from this thing.

[[Category:Tutorials]]