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

CEGUI In Practice - Creating widgets

2011-06-11T13:14:47Z

Chrisvj:

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

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

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.

<tabs>
<tab title="C++">
<source lang="cpp">
CEGUI::UDim(scale,offset);
</source>
</tab>
<tab title="Python">
<source lang="python">
PyCEGUI.UDim(scale,offset)
</source>
</tab>
</tabs>

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:

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

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

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

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

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

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

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

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.

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

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.

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

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 - Using .layout files

2011-06-10T21:46:34Z

Chrisvj:

{{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]]<br />
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:
<tabs>
<tab title="C++">
<source lang="cpp">CEGUI::Window::setProperty("TitlebarFont","DejaVuSans-10");</source>
</tab>
<tab title="Python">
<source lang="python">
PyCEGUI.Window.setProperty("TitlebarFont","DejaVuSans-10")</source>
</tab>
</tabs>
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. Sofar 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]]