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

CEGUI In Practice - A Game Console

2011-07-14T04:45:52Z

Doubleyou:

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

== CEGUI InPractice 6 ==

Welcome back! This tutorial we will put together the knowledge from the past few chapters to create a functioning Console window. The last few tutorials have given us the basics. Now its time to put that knowledge to use and make something we can use in our game.

==== Game Plan ====

Okay, now lets look at what we need to do. We will want to be able to type in commands, press the send button, and have them output into the text box. We will also probably want to acknowledge when enter is pressed as thats the 'normal' feel of typing into a chat.

We discussed earlier how to send input to CEGUI ([[CEGUI In Practice - Managing input]]), so we will have to assume that you have that working (and probably built the application structure behind it). We will also assume you used the previous tutorial's layout file and naming for the console window ( [[CEGUI In Practice - Using .layout files]]).

Due to the fact that we are getting to a slightly more advanced implementation of CEGUI here, and because we may want the ConsoleWindow to do other more useful things (like parsing strings for /say commands) I'm going to create a class to encompass the CEGUI ConsoleWindow.

<source lang="cpp">

class GameConsoleWindow
{
public:
GameConsoleWindow(); // Constructor
private:
void CreateCEGUIWindow(); // The function which will load in the CEGUI Window and register event handlers
void RegisterHandlers(); // Register our handler functions
bool Handle_TextSubmitted(const CEGUI::EventArgs &e); // Handle when we press Enter after typing
bool Handle_SendButtonPressed(const CEGUI::EventArgs &e); // Handle when we press the Send button
void ParseText(CEGUI::String inMsg); // Parse the text the user submitted.
void OutputText(CEGUI::String inMsg, // Post the message to the ChatHistory listbox.
CEGUI::colour colour = CEGUI::colour( 0xFFFFFFFF)); // with a white color default

CEGUI::Window *m_ConsoleWindow; // This will be a pointer to the ConsoleRoot window.
CEGUI::String sNamePrefix; // This will be the prefix name we give the layout
static int iInstanceNumber; // This will be the instance number for this class.
};
</source>

Alright, so that will be our class. It might look daunting, but don't worry it will all make sense in the end.

==== The Constructor ====

I'm going to use the constructor as the main point of automation here. And while I believe it is normally bad practice to call functions which could potentially fail within a constructor, i'm going to anyway for ease of this tutorial. We will have it Initialize some variables, and then call the CreateCEGUIWindow function.

<source lang="cpp">
GameConsoleWindow::GameConsoleWindow()
{
m_ConsoleWindow = NULL; // Always good practice to initialize a pointer to a NULL value, helps when switching to Release Builds.
iInstanceNumber = 0;
sNamePrefix = "";
}
</source>
==== Setting up the Window ====

Now we need to setup the window. We have done this before in the .layout tutorial so we will do it again here. However, we mentioned before that you could use a prefix when loading a .layout to avoid name conflicts if you load multiple layouts. So we need to account for that. Will we need multiple consoles? Who knows, might as well build it in while we're designing it right?

Lets write the CreateCEGUIWindow function:

<source lang="cpp">
void GameConsoleWindow::CreateCEGUIWindow()
{
// Get a local pointer to the CEGUI Window Manager, Purely for convenience to reduce typing
CEGUI::WindowManager *pWindowManager = CEGUI::WindowManager::getSingletonPtr();

// Now before we load anything, lets increase our instance number to ensure no conflicts.
// I like the format #_ConsoleRoot so thats how i'm gonna make the prefix. This simply
// Increments the iInstanceNumber then puts it + a _ into the sNamePrefix string.
sNamePrefix = ++iInstanceNumber + "_";

// Now that we can ensure that we have a safe prefix, and won't have any naming conflicts lets create the window
// and assign it to our member window pointer m_ConsoleWindow
m_ConsoleWindow = pWindowManager->loadWindowLayout(inLayoutName,sNamePrefix);

// Being a good programmer, its a good idea to ensure that we got a valid window back.
if (m_ConsoleWindow)
{
// Lets add our new window to the Root GUI Window
CEGUI::System::getSingleton().getGUISheet()->addChildWindow(m_ConsoleWindow);
// Now register the handlers for the events (Clicking, typing, etc)
(this)->RegisterHandlers();
}
else
{
// Something bad happened and we didn't successfully create the window lets output the information
CEGUI::Logger::getSingleton().logEvent("Error: Unable to load the ConsoleWindow from .layout");
}
}
</source>

Alright so that created the window. And after the window was created, we Registered its handlers. Lets look at how we go about
registering those handlers. Below is the RegisterHandlers function, it will probably look familiar if you have been reading along:

<source lang="cpp">
void GameConsoleWindow::RegisterHandlers()
{
// Alright now we need to register the handlers. We mentioned above we want to acknowledge when the user presses Enter, and
// when they click the 'Send' button. So we need to register each of those events

// First lets register the Send button. Our buttons name is "ConsoleRoot/SendButton", but don't forget we prepended a name to
// all the windows which were loaded. So we need to take that into account here.
m_ConsoleWindow->getChild(sNamePrefix + "ConsoleRoot/SendButton")->subscribeEvent(
CEGUI::PushButton::EventClicked, // If we recall our button was of type CEGUI::PushButton in the .scheme
// and we want to acknowledge the EventClicked action.
CEGUI::Event::Subscriber( // What function to call when this is clicked. Remember, all functions
// are contained within (this) class.
&GameConsoleWindow::Handle_SendButtonPressed, // Call Handle_SendButtonPressed member of GameConsoleWindow
this)); // Using (this) instance we're in right now

// Now for the TextSubmitted, we will be registering the event on the edit box, which is where the users cursor will be when
//they press Enter. I'm not going to break this down as much, because I believe that is very ugly to read, but was a good
//way of expressing it. Here is the function call.
m_ConsoleWindow->getChild(sNamePrefix + "ConsoleRoot/EditBox")->subscribeEvent(CEGUI::Editbox::EventMouseClick,
CEGUI::Event::Subscriber(&GameConsoleWindow::Handle_TextSubmitted,this));
}
</source>

That last line looks pretty ugly, but remember if you include namespace CEGUI; you won't have all those Ugly CEGUI:: prefixing all the code. As you can see, once you get the hang of registering events its pretty easy. One thing to note, is there are more than one way to account for certain actions. On the button, you could also have registered for:

<source lang="cpp">
CEGUI::PushButton::EventMouseClick
CEGUI::PushButton::EventMouseButtonDown
CEGUI::PushButton::EventMouseButtonUp
</source>
Depending on what result you were looking for, and where you wanted the action to take place. For example, windows interfaces usually react on the MouseButtonUp, allowing the user to click it, and then slide off the mouse if it wasn't what they really wanted to press.

==== The Handlers ====

Now that we have registered the events, we need to actually write the functions which will handle those events. We need to handle both the Text Submitted, and the SendButton's event.

<source lang="cpp">
bool GameConsoleWindow::Handle_TextSubmitted(const CEGUI::EventArgs &e)
{
// The following line of code is not really needed in this particular example, but is good to show. The EventArgs by itself
// only has limited uses. You will find it more useful to cast this to another type of Event. In this case WindowEventArgs
// could be much more useful as we are dealing with a CEGUI::Window. Notably, this will allow you access to the .window
// member of the argument, which will have a pointer to the window which called the event. You can imagine that would be
// useful!
const CEGUI::WindowEventArgs* args = static_cast<const CEGUI::WindowEventArgs*>(&e);

// Now we need to get the text that is in the edit box right now.
CEGUI::String Msg = mWindow->getChild(sNamePrefix + "ConsoleRoot/EditBox")->getText();

// Since we have that string, lets send it to the TextParser which will handle it from here
(this)->ParseText(Msg);

// Now that we've finished with the text, we need to ensure that we clear out the EditBox. This is what we would expect
// To happen after we press enter
m_ConsoleWindow->getChild(sNamePrefix + "ConsoleRoot/EditBox")->setText("");

return true;
}
</source>

Now you might be wondering why we didn't just Parse the text in here? Well If the user presses Enter, or presses the Send button the text will either way have to be parsed, and it will be parsed in the same manner. So why write the same code twice?

Below is the code for handling the SendButton being pressed. I know I just harped on rewriting code, and this will ironically look alot like the Code for when text has been submitted. But thats because we don't really need the button to do much. We probably could have just had the ButtonPress trigger the Handle_TextSubmitted above when we registered the handlers, but what if we wanted a clicking noise to be played when the player pressed the button? Then we would need a seperate handler for the Send button. Anyway 'nuff said, lets show the code.

<source lang="cpp">
bool GameConsoleWindow::Handle_SendButtonPressed(const CEGUI::EventArgs &e)
{
CEGUI::String Msg = mWindow->getChild(sNamePrefix + "ConsoleRoot/EditBox")->getText();
(this)->ParseText(Msg);
m_ConsoleWindow->getChild(sNamePrefix + "ConsoleRoot/EditBox")->setText("");

return true;
}
</source>

==== Parsing that Text ====

This portion is not going to be so much CEGUI Related as it will be string manipulation.

<source lang="cpp">

void GameConsoleWindow::ParseText(CEGUI::String inMsg)
{

// I personally like working with std::string. So i'm going to convert it here.
std::string inString = inMsg.c_str();

if (inString.length() >= 1) // Be sure we got a string longer than 0
{
if (inString.at(0) == '/') // Check if the first letter is a 'command'
{
std::string::size_type commandEnd = inString.find(" ", 1);
std::string command = inString.substr(1, commandEnd - 1);
std::string commandArgs = inString.substr(commandEnd + 1, inString.length() - (commandEnd + 1));
//convert command to lower case
for(std::string::size_type i=0; i < command.length(); i++)
{
command[i] = tolower(command[i]);
}

// Begin processing

if (command == "say")
{
std::string outString = "You:" + inString; // Append our 'name' to the message we'll display in the list
mConsole->OutputMessage(outString);
}
else if (command == "quit")
{
// do a /quit
}
else if (command == "help")
{
// do a /help
}
else
{
std::string outString = "<" + inString + "> is an invalid command.";
(this)->OutputText(outString,CEGUI::colour(1.0f,0.0f,0.0f)); // With red ANGRY colors!
}
} // End if /
else
{
(this)->OutputText(inString); // no commands, just output what they wrote
}
}
}
</source>

Phew, thats kinda an annoying function isn't it? Well, the point to note is that it checks for a forward slash, if it finds one then it enters the if/else conditions to see if it found an applicable command. If it does it does something. In this example it handles the actions right there, if you were to write it a little more advanced, it could goto a (this)->ShowHelp() or (this)->QuitGame().

The point to note is the OutputText. That will add the items to the ListBox of Chat history. We will work on that function now.

==== OutputText ====

A point to note here. A CEGUI::Listbox window doesn't naturally word wrap. And wordwrapping is a very nice thing to have in a chat window, as everyone has different resolutions on their screens, and some people REALLY like to ramble! (But not this magnificant author of course!). So we will use a Custom created widget which is available on the forums [http://www.cegui.org.uk/phpBB2/viewtopic.php?f=10&t=4322]. you could use a normal listbox, but you wouldn't get word-wrapping.

<source lang="cpp">
void GameConsoleWindow::OutputText(std::string message, CEGUI::colour colour)
{

// Get a pointer to the ChatBox so we don't have to use this ugly getChild function everytime.
CEGUI::Listbox *outputWindow = static_cast<CEGUI::Listbox*>(m_ConsoleWindow->getChild("ConsoleRoot/ChatBox"));

CEGUI::FormattedListboxTextItem *newItem=0; // This will hold the actual text and will be the listbox segment / item

newItem = new CEGUI::FormattedListboxTextItem(message,CEGUI::HTF_WORDWRAP_LEFT_ALIGNED); // Instance the Item with Left
// wordwrapped alignment
newItem->setTextColours(colour); // Set the text color
outputWindow->addItem(newItem); // Add the new ListBoxTextItem to the ListBox
}
</source>

==== Conclusion ====

And that ladies and gentleman, is our Console box. Not too terrible was it? Now of course, remember there are many ways to skin the proverbial cat. This is just an example of ways to do things. If you would like some homework, you could investigate why the SendButton does weird things when you drag and resize the window. I'll give you a hint, look at the way we're defining how big the ConsoleRoot is and where its child windows are placed... and what implications we might have by using relative scales for things.. Okay, i guess that was a big hint wasn't it!

Till next time...

[[Category:Tutorials]]

CEGUI In Practice - A Game Console

2011-07-14T04:35:19Z

Doubleyou: /* Parsing that Text */

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

== CEGUI InPractice 6 ==

Welcome back! This tutorial we will put together the knowledge from the past few chapters to create a functioning Console window. The last few tutorials have given us the basics. Now its time to put that knowledge to use and make something we can use in our game.

==== Game Plan ====

Okay, now lets look at what we need to do. We will want to be able to type in commands, press the send button, and have them output into the text box. We will also probably want to acknowledge when enter is pressed as thats the 'normal' feel of typing into a chat.

We discussed earlier how to send input to CEGUI ([[CEGUI In Practice - Managing input]]), so we will have to assume that you have that working (and probably built the application structure behind it). We will also assume you used the previous tutorial's layout file and naming for the console window ( [[CEGUI In Practice - Using .layout files]]).

Due to the fact that we are getting to a slightly more advanced implementation of CEGUI here, and because we may want the ConsoleWindow to do other more useful things (like parsing strings for /say commands) I'm going to create a class to encompass the CEGUI ConsoleWindow.

<source lang="cpp">

class GameConsoleWindow
{
public:
GameConsoleWindow(); // Constructor
private:
void CreateCEGUIWindow(); // The function which will load in the CEGUI Window and register event handlers
void RegisterHandlers(); // Register our handler functions
bool Handle_TextSubmitted(const CEGUI::EventArgs &e); // Handle when we press Enter after typing
bool Handle_SendButtonPressed(const CEGUI::EventArgs &e); // Handle when we press the Send button
void ParseText(CEGUI::String inMsg); // Parse the text the user submitted.
void OutputText(CEGUI::String inMsg, // Post the message to the ChatHistory listbox.
CEGUI::Colour colour = CEGUI::Colour( 0xFFFFFFFF)); // with a white color default

CEGUI::Window *m_ConsoleWindow; // This will be a pointer to the ConsoleRoot window.
CEGUI::String sNamePrefix; // This will be the prefix name we give the layout
static int iInstanceNumber; // This will be the instance number for this class.
};
</source>

Alright, so that will be our class. It might look daunting, but don't worry it will all make sense in the end.

==== The Constructor ====

I'm going to use the constructor as the main point of automation here. And while I believe it is normally bad practice to call functions which could potentially fail within a constructor, i'm going to anyway for ease of this tutorial. We will have it Initialize some variables, and then call the CreateCEGUIWindow function.

<source lang="cpp">
GameConsoleWindow::GameConsoleWindow()
{
m_ConsoleWindow = NULL; // Always good practice to initialize a pointer to a NULL value, helps when switching to Release Builds.
iInstanceNumber = 0;
sNamePrefix = "";
}
</source>
==== Setting up the Window ====

Now we need to setup the window. We have done this before in the .layout tutorial so we will do it again here. However, we mentioned before that you could use a prefix when loading a .layout to avoid name conflicts if you load multiple layouts. So we need to account for that. Will we need multiple consoles? Who knows, might as well build it in while we're designing it right?

Lets write the CreateCEGUIWindow function:

<source lang="cpp">
void GameConsoleWindow::CreateCEGUIWindow()
{
// Get a local pointer to the CEGUI Window Manager, Purely for convenience to reduce typing
CEGUI::WindowManager *pWindowManager = CEGUI::WindowManager::getSingletonPtr();

// Now before we load anything, lets increase our instance number to ensure no conflicts.
// I like the format #_ConsoleRoot so thats how i'm gonna make the prefix. This simply
// Increments the iInstanceNumber then puts it + a _ into the sNamePrefix string.
sNamePrefix = ++iInstanceNumber + "_";

// Now that we can ensure that we have a safe prefix, and won't have any naming conflicts lets create the window
// and assign it to our member window pointer m_ConsoleWindow
m_ConsoleWindow = pWindowManager->loadWindowLayout(inLayoutName,sNamePrefix);

// Being a good programmer, its a good idea to ensure that we got a valid window back.
if (m_ConsoleWindow)
{
// Lets add our new window to the Root GUI Window
CEGUI::System::getSingleton().getGUISheet()->addChildWindow(m_ConsoleWindow);
// Now register the handlers for the events (Clicking, typing, etc)
(this)->RegisterHandlers();
}
else
{
// Something bad happened and we didn't successfully create the window lets output the information
CEGUI::Logger::getSingleton().logEvent("Error: Unable to load the ConsoleWindow from .layout");
}
}
</source>

Alright so that created the window. And after the window was created, we Registered its handlers. Lets look at how we go about
registering those handlers. Below is the RegisterHandlers function, it will probably look familiar if you have been reading along:

<source lang="cpp">
void GameConsoleWindow::RegisterHandlers()
{
// Alright now we need to register the handlers. We mentioned above we want to acknowledge when the user presses Enter, and
// when they click the 'Send' button. So we need to register each of those events

// First lets register the Send button. Our buttons name is "ConsoleRoot/SendButton", but don't forget we prepended a name to
// all the windows which were loaded. So we need to take that into account here.
m_ConsoleWindow->getChild(sNamePrefix + "ConsoleRoot/SendButton")->subscribeEvent(
CEGUI::PushButton::EventClicked, // If we recall our button was of type CEGUI::PushButton in the .scheme
// and we want to acknowledge the EventClicked action.
CEGUI::Event::Subscriber( // What function to call when this is clicked. Remember, all functions
// are contained within (this) class.
&GameConsoleWindow::Handle_SendButtonPressed, // Call Handle_SendButtonPressed member of GameConsoleWindow
this)); // Using (this) instance we're in right now

// Now for the TextSubmitted, we will be registering the event on the edit box, which is where the users cursor will be when
//they press Enter. I'm not going to break this down as much, because I believe that is very ugly to read, but was a good
//way of expressing it. Here is the function call.
m_ConsoleWindow->getChild(sNamePrefix + "ConsoleRoot/EditBox")->subscribeEvent(CEGUI::Editbox::EventMouseClick,
CEGUI::Event::Subscriber(&GameConsoleWindow::Handle_TextSubmitted,this));
}
</source>

That last line looks pretty ugly, but remember if you include namespace CEGUI; you won't have all those Ugly CEGUI:: prefixing all the code. As you can see, once you get the hang of registering events its pretty easy. One thing to note, is there are more than one way to account for certain actions. On the button, you could also have registered for:

<source lang="cpp">
CEGUI::PushButton::EventMouseClick
CEGUI::PushButton::EventMouseButtonDown
CEGUI::PushButton::EventMouseButtonUp
</source>
Depending on what result you were looking for, and where you wanted the action to take place. For example, windows interfaces usually react on the MouseButtonUp, allowing the user to click it, and then slide off the mouse if it wasn't what they really wanted to press.

==== The Handlers ====

Now that we have registered the events, we need to actually write the functions which will handle those events. We need to handle both the Text Submitted, and the SendButton's event.

<source lang="cpp">
bool GameConsoleWindow::Handle_TextSubmitted(const CEGUI::EventArgs &e)
{
// The following line of code is not really needed in this particular example, but is good to show. The EventArgs by itself
// only has limited uses. You will find it more useful to cast this to another type of Event. In this case WindowEventArgs
// could be much more useful as we are dealing with a CEGUI::Window. Notably, this will allow you access to the .window
// member of the argument, which will have a pointer to the window which called the event. You can imagine that would be
// useful!
const CEGUI::WindowEventArgs* args = static_cast<const CEGUI::WindowEventArgs*>(&e);

// Now we need to get the text that is in the edit box right now.
CEGUI::String Msg = mWindow->getChild(sNamePrefix + "ConsoleRoot/EditBox")->getText();

// Since we have that string, lets send it to the TextParser which will handle it from here
(this)->ParseText(Msg);

// Now that we've finished with the text, we need to ensure that we clear out the EditBox. This is what we would expect
// To happen after we press enter
m_ConsoleWindow->getChild(sNamePrefix + "ConsoleRoot/EditBox")->setText("");

return true;
}
</source>

Now you might be wondering why we didn't just Parse the text in here? Well If the user presses Enter, or presses the Send button the text will either way have to be parsed, and it will be parsed in the same manner. So why write the same code twice?

Below is the code for handling the SendButton being pressed. I know I just harped on rewriting code, and this will ironically look alot like the Code for when text has been submitted. But thats because we don't really need the button to do much. We probably could have just had the ButtonPress trigger the Handle_TextSubmitted above when we registered the handlers, but what if we wanted a clicking noise to be played when the player pressed the button? Then we would need a seperate handler for the Send button. Anyway 'nuff said, lets show the code.

<source lang="cpp">
bool GameConsoleWindow::Handle_SendButtonPressed(const CEGUI::EventArgs &e)
{
CEGUI::String Msg = mWindow->getChild(sNamePrefix + "ConsoleRoot/EditBox")->getText();
(this)->ParseText(Msg);
m_ConsoleWindow->getChild(sNamePrefix + "ConsoleRoot/EditBox")->setText("");

return true;
}
</source>

==== Parsing that Text ====

This portion is not going to be so much CEGUI Related as it will be string manipulation.

<source lang="cpp">

void GameConsoleWindow::ParseText(CEGUI::String inMsg)
{

// I personally like working with std::string. So i'm going to convert it here.
std::string inString = inMsg.c_str();

if (inString.length() >= 1) // Be sure we got a string longer than 0
{
if (inString.at(0) == '/') // Check if the first letter is a 'command'
{
std::string::size_type commandEnd = inString.find(" ", 1);
std::string command = inString.substr(1, commandEnd - 1);
std::string commandArgs = inString.substr(commandEnd + 1, inString.length() - (commandEnd + 1));
//convert command to lower case
for(std::string::size_type i=0; i < command.length(); i++)
{
command[i] = tolower(command[i]);
}

// Begin processing

if (command == "say")
{
std::string outString = "You:" + inString; // Append our 'name' to the message we'll display in the list
mConsole->OutputMessage(outString);
}
else if (command == "quit")
{
// do a /quit
}
else if (command == "help")
{
// do a /help
}
else
{
std::string outString = "<" + inString + "> is an invalid command.";
(this)->OutputText(outString,CEGUI::Colour(1.0f,0.0f,0.0f)); // With red ANGRY colors!
}
} // End if /
else
{
(this)->OutputText(inString); // no commands, just output what they wrote
}
}
}
</source>

Phew, thats kinda an annoying function isn't it? Well, the point to note is that it checks for a forward slash, if it finds one then it enters the if/else conditions to see if it found an applicable command. If it does it does something. In this example it handles the actions right there, if you were to write it a little more advanced, it could goto a (this)->ShowHelp() or (this)->QuitGame().

The point to note is the OutputText. That will add the items to the ListBox of Chat history. We will work on that function now.

==== OutputText ====

A point to note here. A CEGUI::Listbox window doesn't naturally word wrap. And wordwrapping is a very nice thing to have in a chat window, as everyone has different resolutions on their screens, and some people REALLY like to ramble! (But not this magnificant author of course!). So we will use a Custom created widget which is available on the forums [http://www.cegui.org.uk/phpBB2/viewtopic.php?f=10&t=4322]. you could use a normal listbox, but you wouldn't get word-wrapping.

<source lang="cpp">
void GameConsoleWindow::OutputText(std::string message, CEGUI::Colour colour)
{

// Get a pointer to the ChatBox so we don't have to use this ugly getChild function everytime.
CEGUI::Listbox *outputWindow = static_cast<CEGUI::Listbox*>(m_ConsoleWindow->getChild("ConsoleRoot/ChatBox"));

CEGUI::FormattedListboxTextItem *newItem=0; // This will hold the actual text and will be the listbox segment / item

newItem = new CEGUI::FormattedListboxTextItem(message,CEGUI::HTF_WORDWRAP_LEFT_ALIGNED); // Instance the Item with Left
// wordwrapped alignment
newItem->setTextColours(colour); // Set the text color
outputWindow->addItem(newItem); // Add the new ListBoxTextItem to the ListBox
}
</source>

==== Conclusion ====

And that ladies and gentleman, is our Console box. Not too terrible was it? Now of course, remember there are many ways to skin the proverbial cat. This is just an example of ways to do things. If you would like some homework, you could investigate why the SendButton does weird things when you drag and resize the window. I'll give you a hint, look at the way we're defining how big the ConsoleRoot is and where its child windows are placed... and what implications we might have by using relative scales for things.. Okay, i guess that was a big hint wasn't it!

Till next time...

[[Category:Tutorials]]

CEGUI In Practice - Introduction

2011-06-20T09:14:17Z

Doubleyou:

{{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 =====
<tabs>
<tab title="C++">
<source lang="cpp">
#include "CEGUI.h"
#include "RendererModules/Ogre/CEGUIOgreRenderer.h"
</source>
</tab>
<tab title="Python">
<source lang="python">
import PyCEGUI
import PyCEGUIOgreRenderer
</source>
</tab>
</tabs>

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

2011-06-20T08:55:44Z

Doubleyou:

{{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 =====
<tabs>
<tab title="C++">
<source lang="cpp">
#include "CEGUI.h"
#include "RendererModules/Ogre/CEGUIOgreRenderer.h"
</source>
</tab>
<tab title="Python">
<source lang="python">
import PyCEGUI
import PyCEGUIOgreRenderer
</source>
</tab>
</tabs>

===== 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 Scheem 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]]