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

Performing custom rendering at the right time

2011-02-26T12:11:30Z

Tss:

{{VersionBadge|0.7}} [[category: Tutorials]]
==What is this tutorial?==
This is an advanced tutorial showing one of the ways in which it is possible to hook into the CEGUI rendering process to draw custom imagery using the underlying rendering API directly.

The actual code that is shown here demonstrates a window that has a link to another window, and that link is indicated graphically by way of a line with two arrows. This was inspired by [http://www.cegui.org.uk/phpBB2/viewtopic.php?f=10&t=5389 this forum post], but I think that it is important to state that the technique can also be used for totally different purposes too.

The example code is using OpenGL, although similar things are possible with the other APIs too.

==Overview==
It is probably worthwhile discussing why some 'advanced technique' is required in order to perform certain types of custom rendering in the first place.

All of the things rendered internally by CEGUI are cached and queued for later drawing. This means that when a window draws itself, it has not at that stage actually drawn anything, but rather it has queued some instructions for what to draw when the actual rendering is performed later on.

The biggest issue with this arises when you need custom rendering that relates to a given window, as opposed to custom rendering done before or after the CEGUI::System::renderGUI call. How does one know precisely when to do this custom rendering such that it is layered correctly in regards to the other CEGUI based rendering? You can't render directly in response to the window events that signal a window's rendering has started or ended, because these events relate to CEGUI based rendering which can be – and is – cached.

What you actually need to do is hook into the part of the process that queues things for rendering, and queue your own custom object to perform whatever rendering you need. The objects that get queued are based on the CEGUI::GeometryBuffer interface, the key thing to know is that the only function of that interface used during the final rendering process is the GeometryBuffer::draw function. This means that it's possible to implement a custom GeometryBuffer whose draw function renders directly to the active CEGUI::RenderingSurface (such as the screen / back buffer), rather than drawing some buffered geometry like the regular implementation for the CEGUI::Renderer that you use.

The basic scenario is that we need a subclass of some CEGUI::Window type so we can override the Window::drawSelf function in order to queue our custom GeometryBuffer implementation. And, of course, a custom GeometryBuffer implementation that will perform whatever rendering we desire. These will now be discussed.

==Implementation==
===LinkedWindow class===
For this example, we will develop a LinkedWindow class that is based on the existing FrameWindow type. The class declaration looks like this:
<code>class LinkedWindow : public CEGUI::FrameWindow
{
public:
//! 'Namespace' string used for global events on this class.
static const CEGUI::String EventNamespace;
//! String holding the type name of this widget.
static const CEGUI::String WidgetTypeName;

//! set window that will be the target of our link line.
void setTarget(const CEGUI::Window* target);
//! return pointer that is our current link target.
const CEGUI::Window* getTarget() const;

LinkedWindow(const CEGUI::String& type, const CEGUI::String& name);
~LinkedWindow();

protected:
// overridden from base class.
void drawSelf(const CEGUI::RenderingContext& ctx);
bool testClassName_impl(const CEGUI::String& class_name) const;

//! pointer to a GeometryBuffer that will render our link line.
CEGUI::GeometryBuffer* d_linksGeometry;
//! pointer to the target window of our link line. May be zero.
const CEGUI::Window* d_target;
};</code>

The key thing included here is the drawSelf override, the rest is either boilerplate or related to the specific implementation of this demo. Perhaps it's worthwhile to point out the pointer to a GeometryBuffer though, since this will actually point to an instance of our custom implementation of GeometryBuffer and is initialised in the LinkedWindow constructor.

====The Window::drawSelf override====
Since - at least for this demo - we want our custom rendering to appear between windows, we need to ensure that the RenderingSurface we use is not a surface local to the window. Here we see the code tests to see if the surface we are given in the context is a rendering window, and if it is, we choose to use the owner of that RenderingWindow instead. This is intended to avoid the AutoRenderingSurface of a FrameWindow, though in the demo we switch this off anyway. Depending on your own specific circumstances the code below may not be entirely robust (but it will suffice for most normal uses).
<code> RenderingSurface* surface;

if (ctx.surface->isRenderingWindow())
surface = &static_cast<RenderingWindow*>(ctx.surface)->getOwner();
else
surface = ctx.surface;</code>

The next part is key, and is in fact, single most important line in the tutorial. This is where we queue our custom GeometryBuffer instance to the surface we chose above.
<code> surface->addGeometryBuffer(ctx.queue, *d_linksGeometry); </code>

Finally we call the base class implementation so that the regular FrameWindow rendering is now performed (actually, it's queued - just like our custom GeometryBuffer above!)
<code> FrameWindow::drawSelf(ctx);</code>

===LinkGeometryBuffer class===
The class declaration for LinkGeometryBuffer is as follows:
<code>class LinkGeometryBuffer : public CEGUI::GeometryBuffer
{
public:
LinkGeometryBuffer(LinkedWindow* owner);

// required interface functions for base class.
void draw() const;
void setTranslation(const CEGUI::Vector3& v) {}
void setRotation(const CEGUI::Vector3& r) {}
void setPivot(const CEGUI::Vector3& p) {}
void setClippingRegion(const CEGUI::Rect& region) {}
void appendVertex(const CEGUI::Vertex& vertex) {}
void appendGeometry(const CEGUI::Vertex* const vbuff, CEGUI::uint vertex_count) {}
void setActiveTexture(CEGUI::Texture* texture) {}
void reset() {}
CEGUI::Texture* getActiveTexture() const {return 0;}
CEGUI::uint getVertexCount() const {return 0;}
CEGUI::uint getBatchCount() const {return 0;}
void setRenderEffect(CEGUI::RenderEffect* effect) {}
CEGUI::RenderEffect* getRenderEffect() {return 0;}

protected:
//! helper that uses GL calls to render the link line
static void drawLink(const CEGUI::Vector2& source, const CEGUI::Vector2& dest,
float source_size, float dest_size);
//! helper that uses GL calls to render an arrow.
static void drawArrowRight(float x, float y, float sz);

//! LinkedWindow that created and owns the GeometryBuffer.
LinkedWindow* d_owner;
};</code>

As you can see it's pretty much just the required functions as specified by the CEGUI::GeometryBuffer interface, along with a couple of helper functions which are specific to this demo.

====The GeometryBuffer::draw override====
Below is the code for the custom drawing function. There is little to discuss, since this is just some very basic code and OpenGL calls. We basically determine the source and destination locations which will be the end points of the link line, and call a helper function that makes the GL calls to draw. It's probably worth highlighting the calls that save and restore the GL attributes, we do this because CEGUI will not expect its states to get messed up mid-way through rendering! We don't save the model-view matrix, since this is reset by each GeometryBuffer anyway.
<code> if (!d_owner->getTarget())
return;

const Rect src_area(d_owner->getUnclippedOuterRect());
const Rect dst_area(d_owner->getTarget()->getUnclippedOuterRect());

const Vector2 source(
src_area.d_right,
src_area.d_top + ((src_area.d_bottom - src_area.d_top) / 2));

const Vector2 dest(
dst_area.d_left,
dst_area.d_top + ((dst_area.d_bottom - dst_area.d_top) / 2));

glPushClientAttrib(GL_CLIENT_ALL_ATTRIB_BITS);
glPushAttrib(GL_ALL_ATTRIB_BITS);

glMatrixMode(GL_MODELVIEW);
glLoadIdentity();

glBindTexture(GL_TEXTURE_2D, 0);
glDisable(GL_SCISSOR_TEST);

glColor3f(0.1, 1, 0.2);
drawLink(source, dest, 15, 9);

glPopAttrib();
glPopClientAttrib();</code>

And that really is all there is to it!

===Registering the new window type===
The new window type is registered using the WindowFactoryManager and the templatised WindowFactory, like so:
<code>WindowFactoryManager::getSingleton().addFactory<TplWindowFactory<LinkedWindow> >();</code>

For this example, the falagard mapping that makes this usable is specified in code, but it's just as easily added to your XML scheme file:
<code>WindowFactoryManager::getSingleton().
addFalagardWindowMapping("TaharezLook/LinkedWindow",
"LinkedWindow",
"TaharezLook/FrameWindow",
"Falagard/FrameWindow");</code>

==Conclusion==
Here we have seen how to hook into the CEGUI rendering process by queueing a custom GeometryBuffer implementation along with (or instead of) the regular GeometryBuffer queued by the Window's drawSelf function. This allows any custom rendering to be performed at the correct time so it appears at the same layered position as a window in the output.

==Example Code==
===LinkedWindow Class Declaration (LinkedWindow.h)===
<code>#ifndef _LINKED_WINDOW_H
#define _LINKED_WINDOW_H

#include <elements/CEGUIFrameWindow.h>

/*!
\brief
Custom subclass of FrameWindow. The main purpose of this is so we can
override the Window::drawSelf function in order to add an instance of
our custom GeometryBuffer at an appropriate place - which will then
render the link lines when it's draw function is called.
*/
class LinkedWindow : public CEGUI::FrameWindow
{
public:
//! 'Namespace' string used for global events on this class.
static const CEGUI::String EventNamespace;
//! String holding the type name of this widget.
static const CEGUI::String WidgetTypeName;

//! set window that will be the target of our link line.
void setTarget(const CEGUI::Window* target);
//! return pointer that is our current link target.
const CEGUI::Window* getTarget() const;

LinkedWindow(const CEGUI::String& type, const CEGUI::String& name);
~LinkedWindow();

protected:
// overridden from base class.
void drawSelf(const CEGUI::RenderingContext& ctx);
bool testClassName_impl(const CEGUI::String& class_name) const;

//! pointer to a GeometryBuffer that will render our link line.
CEGUI::GeometryBuffer* d_linksGeometry;
//! pointer to the target window of our link line. May be zero.
const CEGUI::Window* d_target;
};

#endif</code>

===LinkedWindow Class Implementation (LinkedWindow.cpp)===
<code>#include <CEGUIRenderingWindow.h>
#include <CEGUIRenderingContext.h>
#include "LinkedWindow.h"
#include "LinkGeometryBuffer.h"

using namespace CEGUI;

//----------------------------------------------------------------------------//
const String LinkedWindow::EventNamespace("LinkedWindow");
const String LinkedWindow::WidgetTypeName("LinkedWindow");

//----------------------------------------------------------------------------//
LinkedWindow::LinkedWindow(const CEGUI::String& type, const CEGUI::String& name) :
FrameWindow(type, name),
d_linksGeometry(new LinkGeometryBuffer(this)),
d_target(0)
{
}

//----------------------------------------------------------------------------//
void LinkedWindow::setTarget(const CEGUI::Window* target)
{
d_target = target;
}

//----------------------------------------------------------------------------//
const Window* LinkedWindow::getTarget() const
{
return d_target;
}

//----------------------------------------------------------------------------//
LinkedWindow::~LinkedWindow()
{
delete d_linksGeometry;
}

//----------------------------------------------------------------------------//
void LinkedWindow::drawSelf(const RenderingContext& ctx)
{
RenderingSurface* surface;

if (ctx.surface->isRenderingWindow())
surface = &static_cast<RenderingWindow*>(ctx.surface)->getOwner();
else
surface = ctx.surface;

surface->addGeometryBuffer(ctx.queue, *d_linksGeometry);

FrameWindow::drawSelf(ctx);
}

//----------------------------------------------------------------------------//
bool LinkedWindow::testClassName_impl(const CEGUI::String& class_name) const
{
if (class_name == LinkedWindow::WidgetTypeName)
return true;

return FrameWindow::testClassName_impl(class_name);
}

//----------------------------------------------------------------------------//</code>

===LinkGeometryBuffer Class Declaration (LinkGeometryBuffer.h)===
<code>#ifndef _LINK_GEOMETRY_BUFFER_H
#define _LINK_GEOMETRY_BUFFER_H

#include <CEGUIGeometryBuffer.h>

class LinkedWindow;

/*!
/brief
Custom GeometryBuffer used for drawing links from a LinkedWindow to its
target window.

\note
The only part of the regular GeometryBuffer interface we will implement is
the GeometryBuffer::draw function, the rest is stubbed out. Note also that
we don't actually 'buffer' anything here, but do direct drawing within the
draw function.
*/
class LinkGeometryBuffer : public CEGUI::GeometryBuffer
{
public:
LinkGeometryBuffer(LinkedWindow* owner);

// required interface functions for base class.
void draw() const;
void setTranslation(const CEGUI::Vector3& v) {}
void setRotation(const CEGUI::Vector3& r) {}
void setPivot(const CEGUI::Vector3& p) {}
void setClippingRegion(const CEGUI::Rect& region) {}
void appendVertex(const CEGUI::Vertex& vertex) {}
void appendGeometry(const CEGUI::Vertex* const vbuff, CEGUI::uint vertex_count) {}
void setActiveTexture(CEGUI::Texture* texture) {}
void reset() {}
CEGUI::Texture* getActiveTexture() const {return 0;}
CEGUI::uint getVertexCount() const {return 0;}
CEGUI::uint getBatchCount() const {return 0;}
void setRenderEffect(CEGUI::RenderEffect* effect) {}
CEGUI::RenderEffect* getRenderEffect() {return 0;}

protected:
//! helper that uses GL calls to render the link line
static void drawLink(const CEGUI::Vector2& source, const CEGUI::Vector2& dest,
float source_size, float dest_size);
//! helper that uses GL calls to render an arrow.
static void drawArrowRight(float x, float y, float sz);

//! LinkedWindow that created and owns the GeometryBuffer.
LinkedWindow* d_owner;
};

#endif</code>

===LinkGeometryBuffer Class Implementation (LinkGeometryBuffer.cpp)===
<code>#include "LinkGeometryBuffer.h"
#include "LinkedWindow.h"
#include <GL/gl.h>

using namespace CEGUI;

//----------------------------------------------------------------------------//
LinkGeometryBuffer::LinkGeometryBuffer(LinkedWindow* owner) :
d_owner(owner)
{
}

//----------------------------------------------------------------------------//
void LinkGeometryBuffer::draw() const
{
if (!d_owner->getTarget())
return;

const Rect src_area(d_owner->getUnclippedOuterRect());
const Rect dst_area(d_owner->getTarget()->getUnclippedOuterRect());

const Vector2 source(
src_area.d_right,
src_area.d_top + ((src_area.d_bottom - src_area.d_top) / 2));

const Vector2 dest(
dst_area.d_left,
dst_area.d_top + ((dst_area.d_bottom - dst_area.d_top) / 2));

glPushClientAttrib(GL_CLIENT_ALL_ATTRIB_BITS);
glPushAttrib(GL_ALL_ATTRIB_BITS);

glMatrixMode(GL_MODELVIEW);
glLoadIdentity();

glBindTexture(GL_TEXTURE_2D, 0);
glDisable(GL_SCISSOR_TEST);

glColor3f(0.1, 1, 0.2);
drawLink(source, dest, 15, 9);

glPopAttrib();
glPopClientAttrib();
}

//----------------------------------------------------------------------------//
void LinkGeometryBuffer::drawLink(const Vector2& source, const Vector2& dest,
float source_size, float dest_size)
{
drawArrowRight(source.d_x, source.d_y, source_size);

glBegin(GL_LINES);
glVertex2f(source.d_x + (source_size - 1), source.d_y);
glVertex2f(dest.d_x - (dest_size - 1), dest.d_y);
glEnd();

drawArrowRight(dest.d_x - dest_size, dest.d_y, dest_size);
}

//----------------------------------------------------------------------------//
void LinkGeometryBuffer::drawArrowRight(float x, float y, float sz)
{
glBegin(GL_TRIANGLES);
glVertex2f(x, y - sz / 2);
glVertex2f(x, y + sz / 2);
glVertex2f(x + sz, y);
glEnd();
}

//----------------------------------------------------------------------------//</code>

===Demo App code using GLUT (main.cpp)===
<code>#include <GL/glut.h>
#include <CEGUI.h>
#include <RendererModules/OpenGL/CEGUIOpenGLRenderer.h>
#include "LinkedWindow.h"

using namespace CEGUI;

//----------------------------------------------------------------------------//
void drawFunc()
{
glClearColor(0, 0, 0, 1);
glClear(GL_COLOR_BUFFER_BIT);

System::getSingleton().renderGUI();

glutSwapBuffers();
glutPostRedisplay();
}

//----------------------------------------------------------------------------//
void moveFunc(int x, int y)
{
System::getSingleton().injectMousePosition(x, y);
}

//----------------------------------------------------------------------------//
void mouseButtonFunc(int button, int state, int, int)
{
MouseButton cegui_btn;

switch (button)
{
case GLUT_MIDDLE_BUTTON:
cegui_btn = MiddleButton;
break;

case GLUT_RIGHT_BUTTON:
cegui_btn = RightButton;
break;

default:
cegui_btn = LeftButton;
}

if (state == GLUT_UP)
System::getSingleton().injectMouseButtonUp(cegui_btn);
else
System::getSingleton().injectMouseButtonDown(cegui_btn);
}

//----------------------------------------------------------------------------//
void initialiseGLUT(int argc, char* argv[])
{
glutInit(&argc, argv);
glutInitWindowSize(800, 600);
glutInitDisplayMode(GLUT_DOUBLE );
glutCreateWindow("CEGUI Demo App");
glutDisplayFunc(drawFunc);
glutMotionFunc(moveFunc);
glutPassiveMotionFunc(moveFunc);
glutMouseFunc(mouseButtonFunc);
}

//----------------------------------------------------------------------------//
void initialiseCEGUIResources()
{
DefaultResourceProvider* rp = static_cast<DefaultResourceProvider*>(
System::getSingleton().getResourceProvider());
rp->setResourceGroupDirectory("schemes", "/usr/local/share/CEGUI/schemes");
rp->setResourceGroupDirectory("imagesets", "/usr/local/share/CEGUI/imagesets");
rp->setResourceGroupDirectory("fonts", "/usr/local/share/CEGUI/fonts");
rp->setResourceGroupDirectory("looknfeel", "/usr/local/share/CEGUI/looknfeel");

Scheme::setDefaultResourceGroup("schemes");
Imageset::setDefaultResourceGroup("imagesets");
Font::setDefaultResourceGroup("fonts");
WidgetLookManager::setDefaultResourceGroup("looknfeel");
}

//----------------------------------------------------------------------------//
void registerCustomWindow()
{
// register the new window type
WindowFactoryManager::getSingleton().
addFactory<TplWindowFactory<LinkedWindow> >();

// make a mapping that uses the existing TL/FrameWindow renderer.
WindowFactoryManager::getSingleton().
addFalagardWindowMapping("TaharezLook/LinkedWindow",
"LinkedWindow",
"TaharezLook/FrameWindow",
"Falagard/FrameWindow");
}

//----------------------------------------------------------------------------//
bool checkBoxHandler(const EventArgs& a)
{
const WindowEventArgs& wa = static_cast<const WindowEventArgs&>(a);
Checkbox* cb = static_cast<Checkbox*>(wa.window);

const String lnkWindowName(cb->getUserString("LinkedWindow"));

if (!lnkWindowName.empty())
{
Window* lw = WindowManager::getSingleton().getWindow(lnkWindowName);
lw->setVisible(cb->isSelected());
}
}

//----------------------------------------------------------------------------//
LinkedWindow* createLinkedWindow(const String& name,
float x, float y, float w, float h,
const String& title,
bool initially_hidden)
{

LinkedWindow* wnd = static_cast<LinkedWindow*>(
WindowManager::getSingleton().
createWindow("TaharezLook/LinkedWindow", name));

wnd->setPosition(UVector2(UDim(x, 0), UDim(y, 0)));
wnd->setSize(UVector2(UDim(w, 0), UDim(h, 0)));
wnd->setUsingAutoRenderingSurface(false);
wnd->setText(title);
wnd->setVisible(!initially_hidden);

return wnd;
}

//----------------------------------------------------------------------------//
Checkbox* createCheckbox(float x, float y, const String& label)
{
Checkbox* wnd = static_cast<Checkbox*>(WindowManager::getSingleton().
createWindow("TaharezLook/Checkbox"));
wnd->setPosition(UVector2(UDim(x, 0), UDim(y, 0)));
wnd->setSize(UVector2(UDim(1.0, 0), UDim(0.2, 0)));
wnd->setText(label);
wnd->subscribeEvent(Checkbox::EventCheckStateChanged, checkBoxHandler);

return wnd;
}

//----------------------------------------------------------------------------//
int main(int argc, char* argv[])
{
initialiseGLUT(argc, argv);

System::setDefaultXMLParserName("ExpatParser");
OpenGLRenderer::bootstrapSystem();
initialiseCEGUIResources();

SchemeManager::getSingleton().create("TaharezLook.scheme");
System::getSingleton().setDefaultMouseCursor("TaharezLook", "MouseArrow");

registerCustomWindow();

WindowManager& winMgr(WindowManager::getSingleton());
Window* root = winMgr.createWindow("DefaultWindow");
System::getSingleton().setGUISheet(root);

LinkedWindow* main = createLinkedWindow("main", 0.4, 0.2, 0.25, 0.25, "Main Window", false);
root->addChildWindow(main);

LinkedWindow* src1 = createLinkedWindow("src1", 0.1, 0.1, 0.2, 0.15, "Src Wnd 1", true);
root->addChildWindow(src1);

LinkedWindow* src2 = createLinkedWindow("src2", 0.1, 0.3, 0.2, 0.15, "Src Wnd 2", true);
root->addChildWindow(src2);

LinkedWindow* dst1 = createLinkedWindow("dst1", 0.7, 0.1, 0.25, 0.25, "Dst Wnd 1", false);
root->addChildWindow(dst1);

Window* tg1 = createCheckbox(0, 0, "Link Target 1");
main->addChildWindow(tg1);
src1->setTarget(tg1);
tg1->setUserString("LinkedWindow", "src1");

Window* tg2 = createCheckbox(0, 0.2, "Link Target 2");
main->addChildWindow(tg2);
tg2->setUserString("LinkedWindow", "");

Window* tg3 = createCheckbox(0, 0.4, "Link Target 3");
main->addChildWindow(tg3);
src2->setTarget(tg3);
tg3->setUserString("LinkedWindow", "src2");

Window* button = winMgr.createWindow("TaharezLook/Button");
button->setPosition(UVector2(UDim(0.0, 0), UDim(0.3, 0)));
button->setSize(UVector2(UDim(1.0, 0), UDim(0.2, 0)));
button->setText("Engage!");
button->setUserString("LinkedWindow", "main");
dst1->addChildWindow(button);
main->setTarget(button);

glutMainLoop();

OpenGLRenderer::destroySystem();

return 0;
}

//----------------------------------------------------------------------------//</code>

Creating Skins

2011-02-26T12:11:03Z

Tss:

[[category: Tutorials]]

So far this page contains a few thoughts randomly scattered around as I (centipede) learn how to create skins. It may be worth a reading though.

== What the artist should know about programming CEGUI ==
If you are more of an artist than a programmer, and you intend to make skins for CEGUI, but have practically no experience with how to program it then all those definition files (imageset, scheme, looknfeel) and other things will be wildly confusing. You need to have a basic idea of how the code works before things will make any sense, but once you do it all seems so naturally logical. The reason this wiki-entry has been written is that the author is right in the transition from foggy confusion to perfect clarity, and he wants to put his experience into writing before he becomes a silent member of the crowd of people who thinks these matters are so obvious that they hardly need to be expounded upon. If you are wise, you will add your thoughts and experience too.

The programmer lives in the C++ world whereas the artist lives in the XML world. They are brought together in the Look-plugins: FalagardLook (and previously TaharezLook and WindowsLook). It works a bit like the Model/View paradigm. The Core library is not at all concerned with how things look. It is only interested in behaviour: What state is the button in right now, and what would happen if the user moved the mouse away while keeping the button pressed etc. The core library relies on the Look-modules to supply the visual aspect. They are the ones that handles all the stuff the artist specify in the XML files.

== Child, NamedArea, states and optional configurations ==

So basically the Core has a set of logical elements/widgets which the Look-plugins turns into a set of physical elements/widgets using the information in the XML files. This is why certain things are mandatory in the looknfeel files.

Some widgets are ''logically'' composed of a few smaller widgets. A FrameWindow consists of a TitleBar and a SystemButton and a ListBox has a vertical and a horizontal Scrollbar. FalagardLook, being totally configurable as it is, can really make no assumptions about how things are arranged by the artist, so it absolutely relies on the '''<Child>''' elements of the '''<WidgetLook>''' to specify where to put those subelements in the physical space of the FrameWindow. Notice how the following code from the Vanilla.looknfeel is really just a specification of an area on the total FrameWindow where the titlebar should be placed:
<Child type="Vanilla/Titlebar" nameSuffix="__auto_titlebar__">
<Area>
<Dim type="LeftEdge" ><AbsoluteDim value="0" /></Dim>
<Dim type="TopEdge" ><AbsoluteDim value="0" /></Dim>
<Dim type="Width" ><UnifiedDim scale="1" type="Width" /></Dim>
<Dim type="Height" ><FontDim type="LineSpacing" padding="14" /></Dim>
</Area>
<Property name="AlwaysOnTop" value="False" />
</Child>

Some widgets can have a ''logical'' interaction (e.g. writing text in an EditBox) which forces the poor ignorant FalagardLook module to demand of the poor all-knowing artist to specify where to put the text. Putting it at position (0,0) it usually not a very good idea, so the artist must specify a '''<NamedArea>''' that FalagardLook can read and use when rendering text. Here is an example of a specified "client area" of a FrameWindow, which is the area inside the window where subwidgets can be placed (i.e. all the window except titlebar and border):
<NamedArea name="ClientWithTitleWithFrame">
<Area>
<Dim type="LeftEdge"><AbsoluteDim value="7" /></Dim>
<Dim type="TopEdge"><WidgetDim widget="__auto_titlebar__" dimension="BottomEdge" /></Dim>
<Dim type="RightEdge"><UnifiedDim scale="1" offset="-7" type="RightEdge" /></Dim>
<Dim type="BottomEdge"><UnifiedDim scale="1" offset="-7" type="BottomEdge" /></Dim>
</Area>
</NamedArea>

One thing worth noting above is that a FrameWindow must have not just one client area specified but four! This is because the programmer that uses CEGUI can request four different kinds of subwindows: With/without a titlebar and with/without a border. The artists must be prepared for this and perhaps even go to the extreme of painting four kinds of windows. Falagard can't possibly deduce where the client area is placed in the four situations, so it will have to know from the XML files.

== So, how DO I make a skin? ==

Here are some quick ideas on how to get around the job without spending too many hours. There is nothing wrong with reusing things. You can always add more detail later on, but for a start it would be fairly nice to have something that just resembles a GUI rather fast. Remember that in Falagard you can layer things which makes it particularly easy to reuse pixels.

'''Things you will need for a minimal gui'''

'''Assembling the stuff'''

''FrameWindow''
Remember that the titlebar and the rest are drawn separately (i.e. the titlebar is a Child of the FrameWindow and as such is a separate Falagard element).
You will most likely have a few rows of "glue pixels" between the titlebar and the bottom of the FrameWindow. [Should they be put in the titlebar or the rest? Don't know yet]

The Beginners Guide to Falagard skinning - Part I

2011-02-26T12:10:56Z

Tss:

[[category: Tutorials]]

== Introduction ==
The Falagard system in CEGUI 0.4 and up is a powerful tool.
By using it you can make your GUI elements look like you want and not how some coder thought looked cool.
Use Falagard to your advantage and you can do alot of nice things from XML that you might think needed real code.

Falagard allows you not only to define how the rendering of a window proceeds, you can create new representational features as well by creating new properties for the window and using them in your imagery configurations.

Before I go too far glorifying Falagard, we'll just jump right into it :-)

== Basics ==
Falagard is a part of the CEGUI core and is implemented in C++. It is completely possible to write a skin in C++, but it's is not very practical. You have to recompile every time you change something. Fortunately CEGUI supports creating a Falagard skin from a custom XML format.

This Falagard XML format is what we're going to be looking at throughout this tutorial. As I think learning by doing is the way to go, we'll try to produce something useful with this tutorial - a fully working look'n'feel for a regular button.

The beginning:

<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
</WidgetLook>
</Falagard>

This is the truely minimal XML that defines a widget look. A widget look contains all the information needed to render a specific type of window, a widget look is also what we would define as a look'n'feel.
The first line tells the parser that this is really a XML document. This must always be the first line of a Falagard XML skin.
The second line opens the ''Falagard'' tag. This is always the first thing we do after the ''<?xml ... ?>'' tag.
I hope you're somewhat familiar with XML or at least HTML as this tutorial might be a little difficult to understand if you're not. Now you're warned.
The third line opens a ''WidgetLook'' tag. This is where we cram all the details about our look'n'feel.
The fourth line closes the ''WidgetLook'' tag. We must always remember to close our tags.
The fifth line closes the ''Falagard'' tag. Again - always remember to close your tags.

While this simple XML snippet is good for showing you how to start out, it is completely useless as it does nothing.

To make our look'n'feel interesting we need to tell it what to do. So let's have a look at the Falagard data structure:

* WidgetLook
** Property definitions
** Properties
** Named areas
** Child components
** Imagery sections
** State imagery

This might be overwhelming. It might not. Either way it's the how it is. Falagard is a complex system...
But it's really not that hard once you get down the basics.

The look'n'feel we are going to produce is for a ''Falagard/Button'' type window. This window type is simple, and we don't have to know about all of the parts of a look'n'feel. We only need to know what we'll be using. Furthermore we'll keep it very simple which leaves us at a point where we can make something work with very little.

I'm still going to give a short description of each item in the list though:

* WidgetLook - This is where we add all the other components for our look'n'feel. Consider it '''the''' look'n'feel.

* Property definitions - A property definition is the creation of a new property in the window that gets the look'n'feel assigned.

* Properties - A property in CEGUI is a window variable that we can access from anywhere. Even outside C++ (think XML window layouts). We often assign default values to properties from a look'n'feel.

* Named areas - A named area defines a rectangle, inside the window we are skinning, with a distinct name. Often used to define where to draw some specific piece of imagery that needs special handling by CEGUI as thus cannot be completely defined in the look'n'feel.

* Child components - Some window types need child windows. This could be scrollbar, a titlebar etc. We specify what type of window this child will be customize it for the situation from the look'n'feel.

* Imagery sections - An imagery section is a collection of imagery components tagged with a name. We use imagery sections to split the renderable parts of our look'n'feel into sections which can be drawn independently. Like for example having the frame in one section and the background in another.

* State imagery - Tells CEGUI what to draw when. In a state imagery we draw all the different imagery sections we need for a specific window "situation". For our button we will have: Normal, Hover, Pushed, Disabled.

Ok. I hope this clarifies it a bit. We'll go into more detil about the different parts as we need them.

== Requirements ==
Every time you write a look'n'feel you need to make find out what the requirements are for the type of window you want to skin. To get this information you either look at the header files in the Falagard module source directory, or you reference the manual. This is available both online, here on the wiki, and in the documentation directory in the SDK as a PDF.

The online version is available on the page [["Falagard" Skinning System Documentation]]. For the list of these requirements I'm talking about the [[Falagard System base widgets reference]] is what you're looking for.
If we look in there we'll see that ''Falagard/Button'' only require 1 ''StateImagery'' definition to be present. ''Normal''.

It allows up to four ''StateImagery'' definitions to cover all its possible states: ''Normal'', ''Hover'', ''Pushed'' and ''Disabled''.

We'll start out the easy way and just make the ''Normal'' state ;-) So now our XML looks like this:

<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
<b><StateImagery name="Normal">
</StateImagery></b>
</WidgetLook>
</Falagard>

If you compare to the last XML piece, the only difference is the addition of a ''StateImagery'' tag with its name attribute set to "Normal". This makes sure that we live up to the requirement of a "Normal" state definition.
As I said earlier the ''WidgetLook'' is '''the''' look'n'feel so it is - of course - inside it we add the ''StateImagery'' tag.

This still extremely simple look'n'feel is actually a fully valid look'n'feel. It implements what is required by the manual. Though as you might have guessed it still does nothing.
To get it to render anything we have to define the imagery sections mentioned earlier.

== Imagery ==
For our look'n'feel we'll just want a single image to be stretched over the entire window area. That is each corner from the image mapped to each corner of the window.

To acheive this the first thing we need to do is to add a ''ImagerySection'' to our look'n'feel.

<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
<b><ImagerySection name="bg">
</ImagerySection></b>
<StateImagery name="Normal">
<b><Layer>
<Section section="bg" />
</Layer></b>
</StateImagery>
</WidgetLook>
</Falagard>

Now we have added the imagery section, and named it "bg". This name is just something we choose.

Inside the state imagery for the "Normal" state a layer has been added.
The ''Layer'' tag allow you to control the z-ordering of layers inside in a ''StateImagery'', but we only need one layer for this look'n'feel so let's not worry too much about that.

In the layer a ''Section'' has been added. This tag tells the layer its in that we want the ''ImagerySection'' named "bg" to be rendered as part of this layer.

This is nice. The look'n'feel is all ready and hooked up to render the imagery section "bg" as the imagery for the "Normal" state. But our imagery section is still empty, and this means our look'n'feel really is no better than the previous. It still does nothing (at least visually).

Now that we're over the really basic and boring stuff, let's make it draw that image...

To draw a single image we use the tag ''ImageryComponent''. This tag requires us to define the area in which we want the image to be drawn, as well as the image to draw.

The area is the most complex part of practically all look'n'feels. It is designed to be flexible and uses an extended version of the unified coordinate system of CEGUI 0.4 and up.
Besides the regular two numbers containing the relative and absolute component of the coordinate or size Falagard also allows us to use the dimensions of images, windows, text and even properties.
We can also perform arithmetic operations on these dimensions to a certain extent.

Any area needs to define 4 dimensions to fully describe the area. There is some flexibility in how you define the dimensions though.
Probably the most common is to use one of "LeftEdge", "TopEdge", "RightEdge" or "BottomEdge". These map to edges of the window that recieves the look'n'feel, but you can specify "Width" and "Height" instead of "RightEdge" and "BottomEdge".

The look'n'feel we're creating only needs a simple area that covers the entire widget. We'll take the XML required for that in two steps.

<Area>
<Dim type="LeftEdge">
</Dim>
<Dim type="TopEdge">
</Dim>
<Dim type="RightEdge">
</Dim>
<Dim type="BottomEdge">
</Dim>
</Area>

The area itself is created with the ''Area'' tag. Inside it we have the 4 dimensions. We must explicitly state the type of dimension for each one. The order is important:

* LeftEdge
* TopEdge
* RightEdge / Width
* BottomEdge / Height

You don't have to use '''both''' width and height. For example using "RightEdge" and "Height" is fine.

This tells the area how to interpret the dimensions that we are now going to add:

<Area>
<Dim type="LeftEdge">
'''<AbsoluteDim value="0" />'''
</Dim>
<Dim type="TopEdge">
'''<AbsoluteDim value="0" />'''
</Dim>
<Dim type="RightEdge">
'''<UnifiedDim scale="1" offset="0" type="RightEdge" />'''
</Dim>
<Dim type="BottomEdge">
'''<UnifiedDim scale="1" offset="0" type="BottomEdge" />'''
</Dim>
</Area>

Inside each ''Dim'' tag we have added a dimension. Let's take them one at a time.

# <AbsoluteDim value="0" /> - This tell it to put our "LeftEdge" ''Dim'' at pixel position 0. All dimensions are always relative to window that has the look'n'feel, so 0 will in this case be the left edge of our widget as we planned.

# <AbsoluteDim value="0" /> - Just the same as before. But this time we're in a "TopEdge" ''Dim'' so it will result in the top edge of our window.

# <UnifiedDim scale="1" offset="0" type="RightEdge" /> - A unified dimension. This one has a scale (relative) component of exactly one. And a offset (absolute) value of zero. As type we've set "RightEdge". This is what the scale component get multiplied by to get some thing useful (pixel values). One times RightEdge will equal RightEdge, which is exactly the window dimension we want.

# <UnifiedDim scale="1" offset="0" type="BottomEdge" /> - Same as before but the bottom edge of our window as the dimension.

Now the area to span our entire is worked out, let's add that ''ImageryComponent'' and give it its area.

<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
<ImagerySection name="bg">
<b><ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
</ImageryComponent></b>
</ImagerySection>
<StateImagery name="Normal">
<Layer>
<Section section="bg" />
</Layer>
</StateImagery>
</WidgetLook>
</Falagard>

Now the area is in place.
The ''ImageryComponent'' tag has been added to our ''ImagerySection'' and inside it we have out the area we just created.
All thats missing now is the image!

We'll assume we have a imageset loaded called "MyImages". And inside this imageset we have the image "ButtonBG" defined.
This is the image we'll use for our button.

The XML looks like this

<Image imageset="MyImages" image="ButtonBG" />

Simple eh?

We also wanted the image to be stretched across the whole area of the ''ImageryComponent''. The default formatting in top/left alignment. Not good enough...

We add the formatting tags

<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />

Vertical format must come first. Both sets stretching as the formatting. Which is what we need.
That's all we wanted in the look'n'feel so let's have a look at the XML for this extremely simple button skin.

<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
<ImagerySection name="bg">
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<b><Image imageset="MyImages" image="ButtonBG" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" /></b>
</ImageryComponent>
</ImagerySection>
<StateImagery name="Normal">
<Layer>
<Section section="bg" />
</Layer>
</StateImagery>
</WidgetLook>
</Falagard>

The three new tags just got added after the area in the ''ImageryComponent'', and we're done :)

== Label ==
You might have noticed that I have'nt talked about the label until now.
We'll need to take a look at it now or we won't get any text on our button.
With Falagard you have full control of how the text is rendered.

For our look'n'feel we want the text to be centered both vertically and horizontally in the widget. We also want the text to wrap (word wrap) if it's too long to render as one line without being clipped.

We'll make a new ''ImagerySection'' for our label. This gives us a nice seperation of parts to render. "bg" being the background, and a new section called "label" to represent the - You guessed it - label.
Inside this new ''ImagerySection'' we add a ''TextComponent'' which we'll set up to render the text like we want.

<ImagerySection name="label">
<TextComponent>
</TextComponent>
</ImagerySection>

Like a ''ImageryComponent'' a ''TextComponent'' must have an area. For our button we'll allow text to span the entire window. This means that we can reuse the ''Area'' from before.

A ''TextComponent'' by default renders the text of the window that has the look'n'feel assigned.
This is exactly what we want for our button.

The formatting we wanted is easily made by using the same tag we used before (to format the background image) but with another type. The formattings supported are different for ''TextComponent'' and ''ImageryComponent''.

Let's look at the XML for this new ''ImagerySection'' "label":

<ImagerySection name="label">
<TextComponent>
<b><Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<VertFormat type="CentreAligned" />
<HorzFormat type="WordWrapCentreAligned" /></b>
</TextComponent>
</ImagerySection>

We added the same area as in the "bg" ''ImagerySection'', and added the formattings we wanted. Take a look at [[Falagard System XML Enumerations reference]] for the complete listing of supported formattings (and lots of other stuff).

This ''ImagerySection'' is done. It will render the label with the correct formatting using a white colour. By not specifying a colour we always choose white, which is useful as we can modulate it into any colour we choose later on. Which we of course will :-)

To actually use this new "label" section we must add it to our state imagery like we did with the "bg" section earlier. So here's what the XML looks like so far:

<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
<b><ImagerySection name="label">
<TextComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<VertFormat type="CentreAligned" />
<HorzFormat type="WordWrapCentreAligned" />
</TextComponent>
</ImagerySection></b>
<ImagerySection name="bg">
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="MyImages" image="ButtonBG" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<StateImagery name="Normal">
<Layer>
<Section section="bg" />
'''<Section section="label" />'''
</Layer>
</StateImagery>
</WidgetLook>
</Falagard>

This look'n'feel adds the fully working label (still white) to our button skin. This is starting to become a useful look'n'feel, so let's give it the final touch by adding handling of the three other states ''Hover'', ''Pushed'' and ''Disabled'' that we left out before.

== Colours ==
We want to use different text colours for each of these states. We also want to able to customize those colours on a per widget basis.
This is made possible by the property definition.

A ''PropertyDefinition'' creates a new property in the window that gets the look'n'feel assigned. The property we create is a simple string value, but '''we''' choose what it's used for. '''Not''' CEGUI.

In total we have 4 states for our button counting the new ones, so we'll add 4 new properties to store the text colour for each state. The XML is like so:

<PropertyDefinition name="NormalTextColour" initialValue="FFFFFFFF" redrawOnWrite="true" />
<PropertyDefinition name="HoverTextColour" initialValue="FFFF0000" redrawOnWrite="true" />
<PropertyDefinition name="PushedTextColour" initialValue="FF00FF00" redrawOnWrite="true" />
<PropertyDefinition name="DisabledTextColour" initialValue="7F888888" redrawOnWrite="true" />

*''name'' is the name the new property will be available under.
*''initialValue'' is the default value for the property.
*''redrawOnWrite'' when set to true the window will be redrawn when the value of the property changes.

These properties will be available from both C++ code and in XML window layouts. So choosing a good name is a good idea.
You can create properties that you don't use for anything inside the look'n'feel. These will still become available which can be a good way of creating new variables for windows that you might need in your application.

The default values represent colours in the format CEGUI would expect a colour for a built-in property.
Colours for CEGUI are always written in hexadecimal.

The format is: "AARRGGBB" where:
* AA = Alpha
* RR = Red
* GG = Green
* BB = Blue

This gives our properties the values of
* white for ''Normal''
* red for ''Hover''
* green for ''Pushed''
* 50% tranparent grey for ''Disabled''

Setting a new value for any of these properties will make sure the button is re-rendered to show the new colour.

The only places in the look'n'feel that know which state we are in are the ''StateImagery'' tags. The ''Section'' tags inside these allow for colours to be specified. The XML for the label in the ''Normal'' state looks like this:

<Section name="label">
<ColourProperty name="NormalTextColour" />
</Section>

The ''ColourProperty'' tag inside our ''Section'' ensures that all imagery in the imagery section "label" has its colour modulated by the value of the property "NormalTextColour". The imagery section "label" render only white text, so by doing this we ensure that the colour rendered is exactly that of the value of the property "NormalTextColour".

We now know what to do so lets look at the XML so far for this look'n'feel:

<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
<b><PropertyDefinition name="NormalTextColour" initialValue="FFFFFFFF" redrawOnWrite="true" />
<PropertyDefinition name="HoverTextColour" initialValue="FFFF0000" redrawOnWrite="true" />
<PropertyDefinition name="PushedTextColour" initialValue="FF00FF00" redrawOnWrite="true" />
<PropertyDefinition name="DisabledTextColour" initialValue="7F888888" redrawOnWrite="true" /></b>
<ImagerySection name="label">
<TextComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<VertFormat type="CentreAligned" />
<HorzFormat type="WordWrapCentreAligned" />
</TextComponent>
</ImagerySection>
<ImagerySection name="bg">
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="MyImages" image="ButtonBG" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<StateImagery name="Normal">
<Layer>
<Section section="bg" />
<b><Section section="label">
<ColourProperty name="NormalTextColour" />
</Section></b>
</Layer>
</StateImagery>
<b><StateImagery name="Hover">
<Layer>
<Section section="bg" />
<Section section="label">
<ColourProperty name="HoverTextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Pushed">
<Layer>
<Section section="bg" />
<Section section="label">
<ColourProperty name="PushedTextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="bg" />
<Section section="label">
<ColourProperty name="DisabledTextColour" />
</Section>
</Layer>
</StateImagery></b>
</WidgetLook>
</Falagard>

Not too hard was it? The look'n'feel reached a whole new level with these changes, as state is reflected in the text colour.

To sum up what we've made:
* A look'n'feel for the ''Falagard/Button'' window type.
* Static background image.
* Formatted label.
* Label colour dependent on current state.

----

That will be enough for this time. It's getting early ;-)

I hope this tutorial is useful and that it will help expose Falagard more broadly.

Please give feedback in the discussion page so I can improve the tutorial where needed.

--[[User:lindquist|lindquist]] 06:10, 6 Dec 2005 (CET)

The Beginners Guide to Falagard skinning - Part II

2011-02-26T12:10:49Z

Tss:

[[category: Tutorials]]

== Introduction ==
Last time we looked at the essential basics to get something running with Falagard. This is great, but a simplistic look'n'feel for a button is a bit boring. So lets step forward and learn something new.

In this tutorial we will create a look'n'feel for the ''Editbox'' window type. This widget is interactive and uses new parts of the Falagard system, making it an excellent target for another tutorial.

So let's get started...

== Requirements ==
We'll start out by looking at the requirements for the ''Editbox'' window type. Like always, the information we're looking for can be found in the [[Falagard System base widgets reference]].

In there we'll see that the ''Editbox'' is a bit more complex than the ''Button''. But fear not - we'll get through every part of it ;-)

Let's start out with the ''StateImagery'' needed for this widget:
* Enabled
* Disabled
* ReadOnly
* ActiveSelection
* InactiveSelection

Unlike the ''Button'' we don't have any optional states. ''Enabled'' and ''Disabled'' should speak for themselves. ''ReadOnly'' is used when the ''Editbox'' is in read-only mode (easy huh?).

The ''ActiveSelection'' state is somewhat special. It should define what imagery to render for the selection graphics itself when the window is in an activated state (has focus).
''InactiveSelection'' is the same, except it is used when the window is '''not''' active (does'nt have focus).

Besides the ''StateImagery'' needed, a ''Editbox'' also requires a ''NamedArea'' called '''TextArea''' and a ''ImagerySection'' named '''Carat''' (yes, car'''a'''t).
We'll have a much closer look at these later on.

The initial XML (with the parts we know about) looks like this:

<?xml version="1.0" ?>
<Falagard>
<ImagerySection name="Carat">
</ImagerySection>
<StateImagery name="Enabled">
</StateImagery>
<StateImagery name="Disabled">
</StateImagery>
<StateImagery name="ReadOnly">
</StateImagery>
<StateImagery name="ActiveSelection">
</StateImagery>
<StateImagery name="InactiveSelection">
</StateImagery>
</Falagard>

We'll fill it out as we go...

== Imagery ==
This look'n'feel will use a frame consisting of 8 different images from our favorite imageset ''MyImages''. Furthermore we'll have a single image stretched to fill the hole in this frame. The images will have names that are easy to interpret:
{| cellpadding="15" border="1"
|+ Frame setup
| TL || align="center" | T || TR
|-
| align="center" | L || Bg|| align="center" |R
|-
| BL || align="center" | B || BR
|}

Each prefixed with '''Editbox'''. Forming imagenames like '''EditboxTL''' etc.

The ''FrameComponent'' tag may only occur inside an ''ImagerySection''. Just like the ''ImageryComponent'' and ''TextComponent'' that we used in part I.

Using the ''FrameComponent'' is very much like using the ''ImageryComponent'' all the tags allowed are the same, but a ''FrameComponent'' allows up to nine images to be specified. It's purpose is to make making frames easy :-)
A ''FrameComponent'' is special in the way it handles formatting compared to ''ImageryComponent'' though. Any formatting options are only applied to the background image - if it's specified. Yes. We don't have to set all nine of them. We can just choose the image "positions" we need. In our case we'll use all of them tough...

Let's look at the XML for this ''FrameComponent'':

<FrameComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image type="TopLeftCorner" imageset="MyImages" image="EditboxTL" />
<Image type="TopEdge" imageset="MyImages" image="EditboxT" />
<Image type="TopRightCorner" imageset="MyImages" image="EditboxTR" />
<Image type="RightEdge" imageset="MyImages" image="EditboxR" />
<Image type="BottomRightCorner" imageset="MyImages" image="EditboxBR" />
<Image type="BottomEdge" imageset="MyImages" image="EditboxB" />
<Image type="BottomLeftCorner" imageset="MyImages" image="EditboxBL" />
<Image type="LeftEdge" imageset="MyImages" image="EditboxL" />
<Image type="Background" imageset="MyImages" image="EditboxBg" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</FrameComponent>

You should recognise the area. It's the full area of the window, exactly like the areas we used in part I.
Reason: We want the frame and background to cover the entire window. Simple :-)

Nine images are specifed. The order does not matter.
But note that compared to the ''ImageryComponent'' used last time, we must specify a type attribute for the images.
This is so Falagard knows where to place this image in the frame.
These are of course listed in the [[Falagard System XML Enumerations reference]].

The format both horizontally and vertically is ''Stretched''. This ensures that the background image is stretched to fill as much as possible of the "hole" created by the border images (TL,T,TR etc.).

We'll use this frame for all the 3 states (''Enabled'', ''Disabled'', ''ReadOnly''), but we want the colours to be a little different in each state. In part I we created a new property to hold the colour of the Text. To show a different approach, we'll "hard-code" the frame colours into this look'n'feel.

CEGUI supports using a colour rectangle to modulate the colours of anything it renders. This makes it possible to "apply" nice colour gradients to our frame imagery.

The ''Normal'' state will use the colours, unmodified from the image file.

The ''Disabled'' state will use gray to darken the frame imagery

In the ''ReadOnly'' state we'll create a gradient that is white in the top-left corner, and slightly grayish for the three other corners. When applied to the imagery this will result in the top-left corner using exactly the same colours as in the image file, and the three other corners being slightly darkened.

To use this frame component we must - like stated earlier - fit it in a ''ImagerySection''. We'll call this new imagery section "frame".

This is all the we need to write up the xml for this frame, and use it in our states, so now the XML looks like this:

<?xml version="1.0" ?>
<Falagard>
<b><ImagerySection name="frame">
<FrameComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image type="TopLeftCorner" imageset="MyImages" image="EditboxTL" />
<Image type="TopEdge" imageset="MyImages" image="EditboxT" />
<Image type="TopRightCorner" imageset="MyImages" image="EditboxTR" />
<Image type="RightEdge" imageset="MyImages" image="EditboxR" />
<Image type="BottomRightCorner" imageset="MyImages" image="EditboxBR" />
<Image type="BottomEdge" imageset="MyImages" image="EditboxB" />
<Image type="BottomLeftCorner" imageset="MyImages" image="EditboxBL" />
<Image type="LeftEdge" imageset="MyImages" image="EditboxL" />
<Image type="Background" imageset="MyImages" image="EditboxBg" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</FrameComponent>
</ImagerySection></b>
<ImagerySection name="Carat">
</ImagerySection>
<StateImagery name="Enabled">
<b><Layer>
<Section section="frame" />
</Layer></b>
</StateImagery>
<StateImagery name="Disabled">
<b><Layer>
<Section section="frame">
<Colours topLeft="FF7F7F7F" topRight="FF7F7F7F" bottomLeft="FF7F7F7F" bottomRight="FF7F7F7F" />
</Section>
</Layer></b>
</StateImagery>
<StateImagery name="ReadOnly">
<b><Layer>
<Section section="frame">
<Colours topLeft="FFFFFFFF" topRight="FFDFDFDF" bottomLeft="FFDFDFDF" bottomRight="FFDFDFDF" />
</Section>
</Layer></b>
</StateImagery>
<StateImagery name="ActiveSelection">
</StateImagery>
<StateImagery name="InactiveSelection">
</StateImagery>
</Falagard>

The frame component has been added, and the ''Enabled'', ''Disabled'' and ''ReadOnly'' states have been set up to use them. The only new thing is really the ''Colours'' tag inside the ''Section'' tags for "frame".

It behaves just like the ''ColourProperty'' tag we used in part I, except you can specify a colour to use for each corner.
It's attributes
* topLeft
* topRight
* bottomLeft
* bottomRight
Each specify a single colour of the same format we used for ''ColourProperty'' (AARRGGBB in hex).

== Text ==
Remeber something about a ''NamedArea''? Either way we're going to look at it now. The ''Editbox'' widget requires us to define a named area so it knows where to render, the text we type in, the caret (the marker that shows us where the characters we type will be inserted) and our selection.

In this look'n'feel, we want the text to be rendered inside our frame. That is we dont want the text to cover the frame imagery itself, only the background of it. Falagard provides a ''ImageDim'' tag that we can use to extract the width and height from the images we used for the frame. Falagard also provides a ''DimOperator'' tag that we can use to do a little math on our dimensions. These features will be the core of our ''NamedArea'' which will be named '''TextArea''' (Stated in the requirements... Remember?)

The only thing we must (and may) specify in a ''NamedArea'' is a ''Area''.

If we take a look back at the ''Area'' tag, we know that it must specify four dimensions. ''LeftEdge'', ''TopEdge'', ''RightEdge'' and ''BottomEdge''. You might remember that we can specify ''Width'' instead of ''RightEdge'', and ''Height'' instead of ''BottomEdge''. But we're not going to do that. Just so you know (and don't forget) ;-)

We start out with a "empty" XML and fill it out as we go. For now it looks like this:

<NamedArea name="TextArea">
<Area>
<Dim type="LeftEdge">
</Dim>
<Dim type="TopEdge">
</Dim>
<Dim type="RightEdge">
</Dim>
<Dim type="BottomEdge">
</Dim>
</Area>
</NamedArea>

We start out with the left edge. In the frame we used the image named '''EditboxL''' for the left edge. And as the area we want to define is to lie inside the frame, we'll use the width of this specific image as the left edge of our area.
The XML for this ''ImageDim'' is like so:

<ImageDim imageset="MyImages" image="EditboxL" dimension="Width" />

The top edge is very similar except we'll use the height of the image named '''EditboxT''' instead.

<ImageDim imageset="MyImages" image="EditboxT" dimension="Height" />

The right edge is a bit more tricky. To start out we'll use a ''UnifiedDim'' that gives us the right edge of our widget.

<UnifiedDim scale="1" offset="0" type="RightEdge">
</Unified>

We use a seperate tag to close it, as by itself this ''UnifiedDim'' is not good enough. We still need the take the frame into accout. The image dimension we're after is the width of the image '''EditboxR'''. We must subtract this width from the right edge to ensure that the frame imagery is not overwritten by a long text string in the ''Editbox''.

The ''DimOperator'' can do this for us with XML like this:

<UnifiedDim scale="1" offset="0" type="RightEdge">
<b><DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxR" dimension="Width" />
</DimOperator></b>
</Unified>

The ''DimOperator'' tag requires us to specify the attribute ''op'' with the name of the operation we want to perform as the value. The operations supported by Falagard are:
* Add
* Subtract
* Multiply
* Divide
We used ''Subtract'' to "move back" a little from our right edge to make sure we leave the frame imagery for the right edge alone.

The bottom edge of the area is very similar to the right. There are two differences. First we want the ''UnifiedDim'' to take the bottom edge of our window and not the right edge. Second we want to subtract the height of the image named '''EditboxB''' instead too.

This gives us this XML:

<UnifiedDim scale="1" offset="0" type="BottomEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxB" dimension="Height" />
</DimOperator>
</Unified>

If we put these four dimensions into our ''NamedArea'' it looks like this:

<NamedArea name="TextArea">
<Area>
<Dim type="LeftEdge">
<b><ImageDim imageset="MyImages" image="EditboxL" dimension="Width" /></b>
</Dim>
<Dim type="TopEdge">
<b><ImageDim imageset="MyImages" image="EditboxT" dimension="Height" /></b>
</Dim>
<Dim type="RightEdge">
<b><UnifiedDim scale="1" offset="0" type="RightEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxR" dimension="Width" />
</DimOperator>
</Unified></b>
</Dim>
<Dim type="BottomEdge">
<b><UnifiedDim scale="1" offset="0" type="BottomEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxB" dimension="Height" />
</DimOperator>
</Unified></b>
</Dim>
</Area>
</NamedArea>

This is the complete ''NamedArea'' for our ''Editbox'' look'n'feel. If we fit it inside our full look'n'feel it will look like the XML below. Notice that the ''NamedArea'' is specifed before the ''ImagerySection''. This is required by Falagard.

<?xml version="1.0" ?>
<Falagard>
<b><NamedArea name="TextArea">
<Area>
<Dim type="LeftEdge">
<ImageDim imageset="MyImages" image="EditboxL" dimension="Width" />
</Dim>
<Dim type="TopEdge">
<ImageDim imageset="MyImages" image="EditboxT" dimension="Height" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxR" dimension="Width" />
</DimOperator>
</Unified>
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxB" dimension="Height" />
</DimOperator>
</Unified>
</Dim>
</Area>
</NamedArea></b>
<ImagerySection name="frame">
...
... saving space ...
...
</ImagerySection>
<ImagerySection name="Carat">
</ImagerySection>
<StateImagery name="Enabled">
<Layer>
<Section section="frame" />
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="frame">
<Colours topLeft="FF7F7F7F" topRight="FF7F7F7F" bottomLeft="FF7F7F7F" bottomRight="FF7F7F7F" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="ReadOnly">
<Layer>
<Section section="frame">
<Colours topLeft="FFFFFFFF" topRight="FFDFDFDF" bottomLeft="FFDFDFDF" bottomRight="FFDFDFDF" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="ActiveSelection">
</StateImagery>
<StateImagery name="InactiveSelection">
</StateImagery>
</Falagard>

We don't reference '''TextArea''' anywhere. Just specifying it is all that is required according to the [[Falagard System base widgets reference]].

== Caret ==
The ''Editbox'' has a caret. This is a marker that shows us where we are typing and allows us to tell if we are inserting in the middle of the text or at the end etc. The text is split around it by CEGUI so we don't draw over the text rendering the point we're editing unreadable. All this is currently handled internally and all you need to do is create a ''ImagerySection'' name '''Carat'''.

note by Pompei2: You're reading right, the ''ImagerySection'' is named '''Carat''' although the right word is a caret.

When CEGUI needs render the caret (and the text) it will fetch this ''ImagerySection'' and render it at the appropriate position in the text.
We do not need to make a ''TextComponent'' in a ''Editbox'' to get the text to render. Because of the pecularities of the caret (and selection which we will handle later) it's all done automatically, by using the ''NamedArea'' '''TextArea''' we just specified along with the real pixel area of the window, to confine rendering to right rectangle on the screen.

Enough details. We just want to render a single image named '''EditboxCaret''' stretched vertically inside the '''TextArea'''.

Creating the ''ImagerySection'' is very much like creating the background for the ''Button'' in part I, the only real difference being the ''Area'' used. We'll look at the XML for this area, it's all made up by stuff we've already seen.

<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="Width">
<ImageDim imageset="MyImages" image="EditboxCaret" dimension="Width" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>

The first and second (left/top edges) ''Dim''s have the familiar ''AbsoluteDim'' with a value of zero. Nothing new here.

The third ''Dim'' on the other hand is new. It's now specified as "Width" and not "RightEdge" like we have done so far. Inside we have a ''ImageDim'' for the width of the caret image we're using. If we had used the regular ''UnifiedDim'', the caret itself would have the width our textarea (because the caret resides in the text area) and would have been very ugly...

The fourth dimension is the familiar ''UnifiedDim'' we have used in all the earlier areas.

We know from part I how to make a ''ImagerySection'' with a ''ImageryComponent''. This is all we need to render this single-image caret. The XML for our look'n'feel is nearing completion.

<?xml version="1.0" ?>
<Falagard>
<NamedArea name="TextArea">
...
... saving space ...
...
</NamedArea>
<ImagerySection name="frame">
...
... saving space ...
...
</ImagerySection>
<ImagerySection name="Carat">
<b><ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="Width">
<ImageDim imageset="MyImages" image="EditboxCaret" dimension="Width" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="MyImages" image="EditboxCaret" />
<VertFormat type="Stretched" />
</ImageryComponent></b>
</ImagerySection>
<StateImagery name="Enabled">
<Layer>
<Section section="frame" />
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="frame">
<Colours topLeft="FF7F7F7F" topRight="FF7F7F7F" bottomLeft="FF7F7F7F" bottomRight="FF7F7F7F" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="ReadOnly">
<Layer>
<Section section="frame">
<Colours topLeft="FFFFFFFF" topRight="FFDFDFDF" bottomLeft="FFDFDFDF" bottomRight="FFDFDFDF" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="ActiveSelection">
</StateImagery>
<StateImagery name="InactiveSelection">
</StateImagery>
</Falagard>

We only specify the vertical formatting for the new ''ImageryComponent'' because we are specifying the area to exactly match the width of the image, and thus any formatting would have no effect. ''LeftAligned'' (the default) is just fine.

Now we just need to do something in the ''ActiveSelection'' and ''InactiveSelection'' states...

== Selection ==
When the user has selected text in the ''Editbox'', either with the mouse or the keyboard, CEGUI render the selection using the two additional states '''ActiveSelection''' and '''InactiveSelection'''.

The the window is active (has focus) it will use the state '''ActiveSelection''', if if does not have focus (inactive) yet still has a selection '''InactiveSelection''' will be used.

For the selection in this look'n'feel, we'll use a single image stretched over the selection area. This image will contain plain white in the image file so we can apply any colour(s) we choose to the selection imagery.
Let's call it '''White'''.

For '''ActiveSelection''' we'll use a classic blue colour, for inactive the same, except we'll make it 50% transparent.
We can avoid a colour tag in the '''ActiveSelection''' state if we specify the colours to use directly in the ''ImageryComponent''. We'll do that to show how it works.

We'll create a new ''ImagerySection'' for this "selection brush" named '''selection'''. XML follows:

<ImagerySection name="selection">
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="MyImages" image="White" />
<Colours topLeft="FF26458A" topRight="FF26458A" bottomLeft="FF26458A" bottomRight="FF26458A" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>

We use a default area that you should recognise by now. CEGUI will automatically use the right size for the selection.
The image we use is the one called '''White''' from our favorite imageset '''MyImages'''. Like always ;-)
A colour tag has been added as well to make our selection some kind of blue...
The vertical and horizontal formatting is ''Stretched'' which is generally what you would want to do in a situation like this.

We'll "call" this ''ImagerySection'' from the '''ActiveSelection''' and '''InactiveSelection''' states. In the '''InactiveSelection''' state we'll further modulate the colours used by passing a 50% transparent white. This will have the effect of using the same colour as in the active state, but make that colour 50% transparent. We could have just specified the full colour to use in each state and remove the ''Colours'' tag from the ''ImageryComponent'', but I wanted to show that multiple modulations are possible with Falagard.

The states are the last thing missing from the look'n'feel, so let's take a look at the final XML (yay :-P ).

<?xml version="1.0" ?>
<Falagard>
<NamedArea name="TextArea">
<Area>
<Dim type="LeftEdge">
<ImageDim imageset="MyImages" image="EditboxL" dimension="Width" />
</Dim>
<Dim type="TopEdge">
<ImageDim imageset="MyImages" image="EditboxT" dimension="Height" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxR" dimension="Width" />
</DimOperator>
</Unified>
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxB" dimension="Height" />
</DimOperator>
</Unified>
</Dim>
</Area>
</NamedArea>
<ImagerySection name="frame">
<FrameComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image type="TopLeftCorner" imageset="MyImages" image="EditboxTL" />
<Image type="TopEdge" imageset="MyImages" image="EditboxT" />
<Image type="TopRightCorner" imageset="MyImages" image="EditboxTR" />
<Image type="RightEdge" imageset="MyImages" image="EditboxR" />
<Image type="BottomRightCorner" imageset="MyImages" image="EditboxBR" />
<Image type="BottomEdge" imageset="MyImages" image="EditboxB" />
<Image type="BottomLeftCorner" imageset="MyImages" image="EditboxBL" />
<Image type="LeftEdge" imageset="MyImages" image="EditboxL" />
<Image type="Background" imageset="MyImages" image="EditboxBg" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</FrameComponent>
</ImagerySection>
<ImagerySection name="Carat">
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="Width">
<ImageDim imageset="MyImages" image="EditboxCaret" dimension="Width" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="MyImages" image="EditboxCaret" />
<VertFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<b><ImagerySection name="selection">
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="MyImages" image="White" />
<Colours topLeft="FF26458A" topRight="FF26458A" bottomLeft="FF26458A" bottomRight="FF26458A" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection></b>
<StateImagery name="Enabled">
<Layer>
<Section section="frame" />
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="frame">
<Colours topLeft="FF7F7F7F" topRight="FF7F7F7F" bottomLeft="FF7F7F7F" bottomRight="FF7F7F7F" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="ReadOnly">
<Layer>
<Section section="frame">
<Colours topLeft="FFFFFFFF" topRight="FFDFDFDF" bottomLeft="FFDFDFDF" bottomRight="FFDFDFDF" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="ActiveSelection">
<b><Layer>
<Section section="selection" />
</Layer></b>
</StateImagery>
<StateImagery name="InactiveSelection">
<b><Layer>
<Section section="selection">
<Colours topLeft="7FFFFFFF" topRight="7FFFFFFF" bottomLeft="7FFFFFFF" bottomRight="7FFFFFFF" />
</Section>
</Layer></b>
</StateImagery>
</Falagard>

That's it folks. The look'n'feel is done. Hopefully you're starting to play around with the XML and making the look'n'feel suit you (or your artist ;-) ).
Again, feel free to add comments in the discussion page.

Stay tuned for part III...

--[[User:lindquist|lindquist]] 00:41, 14 Dec 2005 (CET)

Overview of GUI files

2011-02-26T12:10:39Z

Tss:

[[category: Tutorials]]

There are a lot of files that go into creating a GUI with CEGUI. Here is an overview (thanks to lindquist for the original version). An expanded version of this brief overview would be quite useful.

==Overview of CEGUI resource files==
==='''.imageset Files'''===
An imageset is an xml file describing a set of images contained in an image file.
When an imageset is loaded, images from that file become available to the application via the [http://www.cegui.org.uk/api_reference/classCEGUI_1_1ImagesetManager.html ImagesetManager].

Editor: [http://www.cegui.org.uk/phpBB2/viewtopic.php?t=1346 CEImagesetEditor in the works by Martignasse.]

==='''[[Scheme files|.scheme Files]]'''===
A scheme file is an xml file describing the binding of widgets defined in a looknfeel file and the base Falagard widget set. Once loaded the components in the scheme file are available via the [http://www.cegui.org.uk/api_reference/classCEGUI_1_1WindowManager.html WindowManager]. A detailed description of [[Scheme files]] is also available.

Editor: none

==='''.looknfeel Files'''===
These are also xml files, which define the visual aspect of widgets declared in the scheme file.

Editor: none

==='''.layout Files'''===
A layout file is also in xml format. It describes a set of widgets to create and their positions, sizes, and other attributes. Basically this describes the final on-screen layout of your GUI, hence the name.

Editor: [[The_"official"_layout_editor]]

==='''.font Files'''===
These simple xml files give the location of a font file (like a TrueType .ttf file) and define a few extra properties about how CEGUI should use that font.

Editor:

==About [[%22Falagard%22_Skinning_System_Documentation | Falagard]]==
Falagard is the part of the API that makes it possible to create a completly new set of widgets (at the visual level) from xml files.

You can, with a looknfeel, describe a widget and make it appear as you want (by using images defined in some imageset) and finally bind it to one of the widgets from a Falagard Base widget set in a scheme file.

Link: [[%22Falagard%22_Skinning_System_Documentation | Falagard documentation]]

==Related Documents==
* [[XML File formats]] - Detailed documentation of the various XML file formats.

Create ImageButtons

2011-02-26T12:10:14Z

Tss:

[[category: Tutorials]]

If you write a GUI for a game, at some time comes the point where you want to create the most exciting kind of buttons: ImageButtons ! But care, I'm not talking about a default button frame, that has a picture instead of a text, I'm talking about ''completely'' self-drawn buttons. I've found two ways to accomplish that task, both are nice.

== Preparations ==
There are a few tasks we have to accomplish before being able to create an ImageButton.

=== Draw it ! ===
The most important thing is, of course, draw the pictures. If you don't want to accomplish this, ask your graphics artist :)
You have to draw 4 pictures/button, wich represents the four states:
#Normal: That is how the button looks like most of the time.
#Hover: This is how the button should look when the mouse comes over it.
#Pushed: When the user clicks the mouse button (and holds it down a bit) over the button, it looks like this.
#Disabled: You can imagine what this is.

This is the file we'll use for this HOWTO and as you see, i didn't ask my graphics artist to do one :p
You can find all other files (source code, data files) there too.
[[http://pompei2.cesar4.be/cegui/imgButton/]]
Edit: shit the link is currently dead ... I hope I find the files so I can upload them again, but atm everything that is written here must be enough. On questions/problems just ask in the forum.

=== The Imageset ===
When I talk about an Imageset, I mean two files: The picture file (.tga, .png, or whatever) and the description (.imageset) file. The picture file can contain a lot of images, but its size has to be a power of two. The description file is an xml file wich gives a name to a (rectangular) location in the picture. So you can call the location (150,150,32,32) "UnitIcon" for example.

'''An example for a .imageset file:'''
<?xml version="1.0" encoding="UTF-8"?>

<Imageset Name="THEButton" Imagefile="THEButton.png" >
<Image Name="btnNormal" XPos="0" YPos="0" Width="64" Height="20" />
<Image Name="btnHover" XPos="0" YPos="20" Width="64" Height="20" />
<Image Name="btnPushed" XPos="0" YPos="40" Width="64" Height="20" />
<Image Name="btnDisabl" XPos="0" YPos="60" Width="64" Height="20" />
</Imageset>
We will use this imageset in our examples. It defines four named images: btnNormal, btnHover, btnPushed and btnDisabl (saved in the file "THEButton.png"). The whole imageset is called "THEButton" and saved in a file named "THEButton.imageset".

How to use this imageset now ? This is very simple, you just have to do this in your initialisation code:
// Load the THEButton Imageset that has the pictures for our button.
CEGUI::ImagesetManager::getSingleton().createImageset( "THEButton.imageset" );
That's all ! Of course, you should do this in a try/catch block.

If, for some wicked reason, you want to do something in code with this imageset, you can either save the pointer that the function above returns, or you just get that pointer if you know the name of the imageset (what you usually do), using this function:
CEGUI::Imageset *m_pImageSet = CEGUI::ImagesetManager::getSingleton().getImageset( "THEButton" );

Enough about imagesets.

== The programmer's job ==
Now we can create the button itself (in two different ways):

=== The first way: mainly in code ===
One way is to create the button in code, you usually do this if you only know wich button to display at runtime. Maybe a strategy game is the best to illustrate this. Imagine you have the buttonspanel, a place on screen with an array of buttons. The buttons that are present there depend on something (like wich unit is currently selected or so). The first thing you have to do, is not in code. Create one layout file for every button. The file should look somewhat like this:

'''Content of button1.layout version 0.1'''
<?xml version="1.0" encoding="UTF-8" ?>
<GUILayout>
<Window Type="TaharezLook/ImageButton" Name="btnNewGame">
<Property Name="UnifiedPosition" Value="{{0,0},{0,0}}" />
<Property Name="UnifiedSize" Value="{{0,64},{0,20}}" />
<nowiki>
</nowiki>
<Property Name="NormalImage" Value="set:THEButton image:btnNormal" />
<Property Name="HoverImage" Value="set:THEButton image:btnHover" />
<Property Name="PushedImage" Value="set:THEButton image:btnPushed" />
<Property Name="DisabledImage" Value="set:THEButton image:btnDisabl" />
<nowiki></nowiki>
</Window>
</GUILayout>

If you have an imagebutton but you want it to have a caption, you could write this kind of layout file:

'''Content of button1.layout version 0.2'''
<?xml version="1.0" encoding="UTF-8" ?>
<GUILayout>
<Window Type="TaharezLook/ImageButton" Name="btnNewGame">
<Property Name="UnifiedPosition" Value="{{0,0},{0,0}}" />
<Property Name="UnifiedSize" Value="{{0,64},{0,20}}" />
<nowiki>
</nowiki>
<Property Name="NormalImage" Value="set:THEButton image:btnNormal" />
<Property Name="HoverImage" Value="set:THEButton image:btnHover" />
<Property Name="PushedImage" Value="set:THEButton image:btnPushed" />
<Property Name="DisabledImage" Value="set:THEButton image:btnDisabl" />
<nowiki></nowiki>
<Window Type="TaharezLook/StaticText" Name="btnNewGame_text__">
<nowiki>
</nowiki>
<Property Name="UnifiedPosition" Value="{{0,0},{0,0}}" />
<Property Name="UnifiedSize" Value="{{1,0},{1,0}}" />
<nowiki></nowiki>
<Property Name="FrameEnabled" Value="False" />
<Property Name="BackgroundEnabled" Value="False" />
<nowiki></nowiki>
<Property Name="HorzFormatting" Value="WordWrapCentred" />
<Property Name="VertFormatting" Value="Middle" />
<nowiki>

</nowiki>
<Property Name="Disabled" Value="True" />
<nowiki></nowiki>
<Property Name="Text">New game</Property>
</Window>
</Window>
</GUILayout>

This adds a child window of type StaticText, with no border and background, that takes all the place in the button, so we can center it. If your caption has to be not centered, play with the values.

A problem that comes up now, is that if the user clicks on the button, the click will be absorbed by the StaticText, and won't reach the button. That's bad. I searched around and found the following two propertys:
<Property Name="MousePassThroughEnabled" Value="True" />
<Property Name="DistributeCapturedInputs" Value="True" />
But both didn't seem to work as expected, I asked the forums and lindquist told me that "If all you want is a simple label added to the ImageButton then adding a TextComponent in the looknfeel is a much cleaner solution.". He is probably right, but I didn't struggle with looknfeels yet. If you achieved this, you can tell me or add a chapter to this wiki :)

The solution he suggested (and the only one wich worked, if i remember correctly, is disabling the staticText (like in the complete code written above)

<Property Name="Disabled" Value="True" />

Now all you need to do to load and show the button are the following four lines of code.

CEGUI::Window *w = CEGUI::WindowManager::getSingleton().loadWindowLayout( "button1.layout" );
rootWin->addChildWindow( w );
w->setPosition( CEGUI::UVector2( CEGUI::UDim(0.5f,-32.0f), CEGUI::UDim(0.5f,-10.0f) ) );
w->setVisible( true );
Supposing rootWin is your current root window, or any other window you want to put the button in.
We set the position to be the center (0.5f) minus the half the height/width of the button, so the button is really centered.
Of course, you can do everything else you want before (and while) showing the button.

That's it ! now you can work with the button however you want :)

=== The second way: Let the power of layout guide you ===
I suppose you read the first way, because they are very similar and I won't rewrite the whole code here. The main difference is that if you like layouts, you'll already have declared all your windows in layout files. The the "'''Content of button1.layout version 0.2'''" won't be alone in a layout file of its own, but it will be in your already existing layout files.
You still have to load the Imageset. I Provided a sample, named imgButtonSample.layout

That's it ! If you got suggestions, corrections or whatever feedback, just tell me.
----

--[[User:Pompei2|Pompei2]] 11:18, 11 January 2007 (PST)

--[[User:fezztah|fezztah]]
To properly centre the label on an image button vertically as well as horizontally I had to change the line: <Property Name="VertFormatting" Value="Middle" /> such that Value="VertCentred" instead. I'm not sure if the original is a mistake so I won't alter it in case it has some other purpose.

Create a CheckListboxItem

2011-02-26T12:10:06Z

Tss:

[[category: Tutorials]]

Sometimes you need a list where the items are checkable. The ItemListbox introduced in CEGUI 0.5 accepts all sorts of items, as long as they inherit ItemEntry. I'm going to teach you how to create a CheckListboxItem to put in your list.

==Getting started!==
I'm assuming you are just using a standard imageset, with a standard scheme (currently TaharezLook and WindowsLook are supported).

We are first going to get started by writing the looknfeel entry. This is the most important part of this tutorial, as its basically 70% of what we need to do to achieve our goal. First of all, this entry has a few states:

#Enabled: How the item looks when the item is enabled.
#Disabled: How the item looks when the item is disabled.
#SelectedEnabled: How the item looks when the item is selected and is enabled.
#SelectedDisabled: How the item looks when the item is selected and is disabled.

==Writing the requirements==

Open the appriopiate looknfeel file (WindowsLook.looknfeel or TaharezLook.looknfeel), and place this at the bottom (inside the Falagard tags though!)

''' Our start '''
<WidgetLook name="WindowsLook/CheckListboxItem">
</WidgetLook>

We first need to define a WidgetLook, this is where all the action happens in. It takes one attribute, name. This is simply the name of the widget you are defining. Now we are going to add the states. These states are necessary for the item to respond to certain events. For example, when the item is disabled, the state Disabled is used.

<WidgetLook name="WindowsLook/CheckListboxItem">
<StateImagery name="Enabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
</WidgetLook>

We define a state via StateImagery. It requires the attribute name which specifies what state its in. Don't worry about Layer for now. Section is always used. This part takes care of actually changing the look. It requires a attribute section, this is actually WHAT to change, in this case the label. TextColour is a simple colour (black), we will define it below. Now as you can see the Enabled state just sets the text colour to black, thats all it does. Same goes for Disabled (remember this is an item, items are not commonly disabled).

Now we are going to take a look at the other two states.

<WidgetLook name="WindowsLook/CheckListboxItem">
<StateImagery name="Enabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedEnabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedDisabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
</WidgetLook>

These states pretty much speak for themselves altough there are more sections listed. Section not only defines what to change, also defines what needs to be shown. In the Enabled state we dont want it to look like its selected, so there is no selection section. Note that the order of which you put the Sections are also the Z order. In this case we are putting the selection image first, and then text. If we would do it the other way around, we wouldn't see the text.

Now we are going to add the definitions of some colors and property's.

<WidgetLook name="WindowsLook/CheckListboxItem">
<PropertyDefinition name="TextColour" initialValue="FF000000" redrawOnWrite="true" />
<PropertyDefinition name="SelectedTextColour" initialValue="FFFFFFFF" redrawOnWrite="true" />
<PropertyDefinition name="SelectionBrush" initialValue="set:WindowsLook image:Background" redrawOnWrite="true" />
<PropertyDefinition name="SelectionColour" initialValue="FF3030FF" redrawOnWrite="true" />
<Property name="Selectable" value="True" />
<StateImagery name="Enabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedEnabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedDisabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
</WidgetLook>

Our first PropertyDefinition just defines a text for a colour used in the StateImagery sections. Same goes for the other PropertyDefinitions except the SelectionBrush. Instead of defining a color, it defines a image. In this case it uses the WindowsLook Background image defined in the imageset. Then we got a Property, which simply implies some sort of setting. In this case, we make it a item by adding the Property 'Selectable' and setting it to true as we want it to act like an item.

==Writing the functional parts==

We now need to add the parts where the background, text and the selection gets drawn. This seems hard, but isn't actually. We are going to start off with a NamedArea. This is required for a listbox item as the listbox needs to know how big the item is to fit it into the list.

<WidgetLook name="WindowsLook/CheckListboxItem">
<PropertyDefinition name="TextColour" initialValue="FF000000" redrawOnWrite="true" />
<PropertyDefinition name="SelectedTextColour" initialValue="FFFFFFFF" redrawOnWrite="true" />
<PropertyDefinition name="SelectionBrush" initialValue="set:WindowsLook image:Background" redrawOnWrite="true" />
<PropertyDefinition name="SelectionColour" initialValue="FF3030FF" redrawOnWrite="true" />
<Property name="Selectable" value="True" />
<b><NamedArea name="ContentSize">
<Area>
<Dim type="LeftEdge" >
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge" >
<AbsoluteDim value="0" />
</Dim>
<Dim type="Width" >
<FontDim type="HorzExtent" padding="6" />
</Dim>
<Dim type="Height" >
<FontDim type="LineSpacing" />
</Dim>
</Area>
</NamedArea></b>
<StateImagery name="Enabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedEnabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedDisabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
</WidgetLook>

I am assuming you know what the basics like the Area, Dim and such. Though FontDim is used to change the size of the item depending on a label. The part we just added now defines the size of the item.
Instead of adding the whole code here again, I'm only showing the additions from now on.

Ok! Now we are going to add the actual Checkbox. This is crucial for our goal, as it allows the item to be checked upon click. We dont have to write the states and all that for the Checkbox, we just use Child! Just place this under our NamedArea and above the first StateImagery.

<Child type ="WindowsLook/Checkbox" nameSuffix="__auto__checkbox">
<Area>
<Dim type="LeftEdge">
<UnifiedDim scale="0" type="LeftEdge" />
<AbsoluteDim value="3" />
</Dim>
<Dim type="TopEdge">
<UnifiedDim scale="0" type="TopEdge" />
</Dim>
<Dim type="Width">
<UnifiedDim scale="1" type="Width" />
</Dim>
<Dim type="Height">
<UnifiedDim scale="1" type="Height"/>
</Dim>
</Area>
</Child>

This adds a WindowsLook/Checkbox to our item. The suffix is necessary to make the name unique. the rest is pretty straight forward - it adds the checkbox on the left side of the item, starting from 3 pixels to make it look smooth.

Now we need a label, this part is simple and I will not spend as much time on clarifying it, it basically explains itself.

<ImagerySection name="label">
<TextComponent>
<Area>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="LeftEdge">
<AbsoluteDim value="18" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="-3" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
</TextComponent>
</ImagerySection>

The TextComponent simply states this this can contain text. The Dim's are just positioning. Note the LeftEdge, the label starts at 18 pixels from the left. This is because the first ~15 pixels are occupied by the checkbox.

Now something important! The selection image.

<ImagerySection name="selection">
<ImageryComponent>
<Area>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
<ImageProperty name="SelectionBrush" />
<ColourProperty name="SelectionColour" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>

Note that we give it the name selection, as used in the StateImagery. The Area part is just positioning and fitting again. The Dim's used there simply make sure the whole item is filled. ImageProperty defines the image to use. We have defined SelectionBrush at the top of our WidgetLook. It simply fills the Area with that image now. ColourProperty colors the image, we have also defined SelectionColour at the top of the WidgetLook. VertFormat and HorzFormat are stretched, if its not stretched, it will only draw one pixel of the image, making it near invisible. Stretching it just makes sure the whole area is covered.

That was it! We wrote our looknfeel entry!!

<WidgetLook name="WindowsLook/CheckListboxItem">
<PropertyDefinition name="TextColour" initialValue="FF000000" redrawOnWrite="true" />
<PropertyDefinition name="SelectedTextColour" initialValue="FFFFFFFF" redrawOnWrite="true" />
<PropertyDefinition name="SelectionBrush" initialValue="set:WindowsLook image:Background" redrawOnWrite="true" />
<PropertyDefinition name="SelectionColour" initialValue="FF3030FF" redrawOnWrite="true" />
<Property name="Selectable" value="True" />
<NamedArea name="ContentSize">
<Area>
<Dim type="LeftEdge" >
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge" >
<AbsoluteDim value="0" />
</Dim>
<Dim type="Width" >
<FontDim type="HorzExtent" padding="6" />
</Dim>
<Dim type="Height" >
<FontDim type="LineSpacing" />
</Dim>
</Area>
</NamedArea>
<Child type ="WindowsLook/Checkbox" nameSuffix="__auto__checkbox">
<Area>
<Dim type="LeftEdge">
<UnifiedDim scale="0" type="LeftEdge" />
<AbsoluteDim value="3" />
</Dim>
<Dim type="TopEdge">
<UnifiedDim scale="0" type="TopEdge" />
</Dim>
<Dim type="Width">
<UnifiedDim scale="1" type="Width" />
</Dim>
<Dim type="Height">
<UnifiedDim scale="1" type="Height"/>
</Dim>
</Area>
</Child>
<ImagerySection name="label">
<TextComponent>
<Area>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="LeftEdge">
<AbsoluteDim value="18" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="-3" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
</TextComponent>
</ImagerySection>
<ImagerySection name="selection">
<ImageryComponent>
<Area>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
<ImageProperty name="SelectionBrush" />
<ColourProperty name="SelectionColour" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<StateImagery name="Enabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedEnabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedDisabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
</WidgetLook>

Pfew am I glad thats done.

==Coding our item==

We have come to the part where we actually try out our new item. We need to do a few things to call this one finished. First, we need to create the CheckListboxItem class. Then we are going to add the window factory to the system. Last but not least is adding the Falagard mapping. We'll start with the CheckListboxItem class.

====CheckListItem.h====
#ifndef _CHECKLISTITEM_
#define _CHECKLISTITEM_
#include <stdio.h>
#include <stdlib.h>
#include <CEGUI.h>
<br>
namespace CEGUI
{
class CheckListboxItem : public ItemEntry
{
protected:
public:
CheckListboxItem(const String &type, const String &name);
virtual ~CheckListboxItem();
static const String WidgetTypeName;
};
CEGUI_DECLARE_WINDOW_FACTORY(CheckListboxItem)
}
#endif

As you can see, this class inherits ItemEntry. This is necessary as its THE thing that makes this item working properly. Pay special attention to <b>CEGUI_DECLARE_WINDOW_FACTORY(CheckListboxItem)</b>. This tells CEGUI that we are declarating the window.

====CheckListItem.cpp====
#include "CheckListItem.h"
<br>
namespace CEGUI
{
CEGUI_DEFINE_WINDOW_FACTORY(CheckListboxItem)
const String CheckListboxItem::WidgetTypeName("CEGUI/CheckListboxItem");
CheckListboxItem::CheckListboxItem(const String &type, const String &name) :
ItemEntry(type, name)
{
}
CheckListboxItem::~CheckListboxItem()
{
}
}

<b>CEGUI_DEFINE_WINDOW_FACTORY(CheckListboxItem)</b> is quite important here. It tells CEGUI where we are placing the code that comes with the window. As you can see this class is quite empty, you are, of course, free to add anything you like to this class - these are just the mere basics.

Now, there is one more important thing to do. Register this window properly in CEGUI.

namespace CEGUI
{
void bindCEGUI()
{
CEGUI::WindowFactoryManager& wfMgr = CEGUI::WindowFactoryManager::getSingleton();
wfMgr.addFactory(&CEGUI_WINDOW_FACTORY(CheckListboxItem));
wfMgr.addFalagardWindowMapping("WindowsLook/CheckListboxItem", "CEGUI/ItemEntry", "WindowsLook/CheckListboxItem", "Falagard/ItemEntry");
}
}

addFalagardWindowMappings parameters are as follows: Name, Type, LooknFeel, WindowRenderer. Just put this code somewhere in your main file or on another place that you are sure is executed before using our new item. Also note, in order to use <b>CEGUI_WINDOW_FACTORY()</b> you need to be in the CEGUI namespace.

'''Example'''

====main.cpp====
#include <stdio.h>
#include <stdlib.h>
#include "SDLLoader.h"
#include "CheckListItem.h"
void doStuff();
<br>
namespace CEGUI
{
void bindCEGUI()
{
CEGUI::WindowFactoryManager& wfMgr = CEGUI::WindowFactoryManager::getSingleton();
wfMgr.addFactory(&CEGUI_WINDOW_FACTORY(CheckListboxItem));
wfMgr.addFalagardWindowMapping("WindowsLook/CheckListboxItem", "CEGUI/ItemEntry", "WindowsLook/CheckListboxItem", "Falagard/ItemEntry");
}
}
int main (int argc, char **argv)
{
SDLLoader sdl;
sdl.init();
CEGUI::bindCEGUI();
doStuff();
sdl.main_loop();
return 0;
}
<br>
void doStuff()
{
CEGUI::System * m_System = CEGUI::System::getSingletonPtr();
CEGUI::Logger::getSingletonPtr()->setLoggingLevel(CEGUI::Insane);
CEGUI::WindowManager * m_WndMgr = CEGUI::WindowManager::getSingletonPtr();
CEGUI::Window * m_Root = m_System->getGUISheet();
<br>
CEGUI::ItemListbox * lb = (CEGUI::ItemListbox*)m_WndMgr->createWindow("WindowsLook/ItemListbox", "Lol");
lb->setSize(CEGUI::UVector2(CEGUI::UDim(0.3f, 0.0f), CEGUI::UDim(0.3f, 0.0f)));
lb->setPosition(CEGUI::UVector2(CEGUI::UDim(0.1f, 0.0f), CEGUI::UDim(0.1f, 0.0f)));
m_Root->addChildWindow(lb);
<br>
CEGUI::CheckListboxItem * check = (CEGUI::CheckListboxItem*)m_WndMgr->createWindow("WindowsLook/CheckListboxItem", "Test");
check->setText("Test");
lb->addChildWindow(check);
}

As you can see in the main function, the function that registers the window is called before actually creating it. Dont pay any attention to the sdl initiation - it's just my personal test environment.

Congratulations! You have just created a CheckListboxItem. This was a very good practice because you also learned the technique required to write a completely new widget.

Please contact me if you have any question, comments, feedback - anything, email me at [mailto:levia@openfrag.org levia at openfrag dot com].

--[[User:Levia|Levia]] 21:10, 5 April 2007 (GMT+1)

Identifying Multiple Event Sources From A Single Callback

2011-02-26T12:09:48Z

Tss:

[[category: Tutorials]]

Sometimes you would like to identify the sender of an event from within your callback function. For example, you would like to execute some common code for your buttons, like triggering a sound to be played on CEGUI::PushButton::EventClicked. Here is an example [http://www.cegui.org.uk/api_reference/classCEGUI_1_1PushButton.html CEGUI::PushButton] we would like to wire up:

<code><cpp/>
CEGUI::PushButton* pushButton =
static_cast<CEGUI::PushButton*>
(CEGUI::WindowManager::getSingleton().createWindow("WindowsLook/Button", "TheButton"));

pushButton->subscribeEvent(CEGUI::PushButton::EventClicked,
CEGUI::Event::Subscriber(&MainMenu::OnButtonClick, this));
</code>

To do this, simply cast the [http://www.cegui.org.uk/api_reference/classCEGUI_1_1EventArgs.html CEGUI::EventArgs] in your callback to a [http://www.cegui.org.uk/api_reference/classCEGUI_1_1WindowEventArgs.html CEGUI::WindowEventArgs]. The CEGUI::WindowEventArgs object contains a pointer to the [http://www.cegui.org.uk/api_reference/classCEGUI_1_1Window.html CEGUI::Window] that sent the event. Now its as easy as calling CEGUI::Window::getName(). Obviously, you can do much more now that you have a pointer to the window who fired the event, but this is just an example:

<code><cpp/>
bool MainMenu::OnButtonClick(const CEGUI::EventArgs& e)
{
const CEGUI::MouseEventArgs& we =
static_cast<const CEGUI::MouseEventArgs&>(e);

CEGUI::String senderID = we.window->getName();

if (senderID == "TheButton")
{
// code for dealing with a "TheButton"
}

return true;
}
</code>

Cool window effects

2011-02-26T12:09:30Z

Tss:

[[category: Tutorials]]

= Inactive windows become transparent =
'''WARNING ! As for now (02.07.2007), this code does make all your tooltips transparent, I'm working on a solution.'''

'''Problem solved (02.07.2007). If you used the old code, please replace by the new.'''

Please discuss this snippet within the [[http://www.cegui.org.uk/phpBB2/viewtopic.php?p=11786 cool window effects - Inactive windows become trans.]] thread.

Do you know about the [http://vizzzion.org/images/blog/composite.png cool effects that the composite extension can create] on linux ? There are many. I wanted to implement one into my game: make the [http://img337.imageshack.us/img337/9398/windowtransparencyue1.png inactive windows become transparent] and only the active one be 100% opaque. (see the links in this sentence for screenshots.) This effect can be interesting if you want your users to concentrate 100% on the active window and the inactive ones aren't important at this moment. But what if the user has to see two windows or more at the same time (and with full opacity) ? We'll see how to handle this.

== The theory ==
There is more then one way to achieve this, but I'll only present the one I chose. CEGUI has something that is called global events. These are events that are fired independently on the widget they apply to. I'll try with an example: sometimes you need to know when a button is clicked, no matter what button it is, you want to know it for EVERY button. This is what global events are for.

We'll subscribe to two global events: "a window gets activated" and "a window gets closed". When a window gets activated, we add it to a stack which we use to keep track of the windows and the order they where activated. We also make the last active window become transparent. When a window gets closed, we remove it from the stack and activate the one that is on the top of the stack now. (that is the window that was active just before the one we just closed.)

We keep the root window away from it, that means we never make the root window transparent, because this would make the tooltips become transparent. You need to have an empty root window that is a container for your other windows.

== The praxis (code) ==
Now let's go ! First, we need to register callback functions to the two global events:
<code><cpp/>
CEGUI::GlobalEventSet::getSingleton( ).subscribeEvent( CEGUI::Window::EventNamespace + "/" + CEGUI::Window::EventActivated,
CEGUI::Event::Subscriber(&onWindowActivated) );
CEGUI::GlobalEventSet::getSingleton( ).subscribeEvent( CEGUI::Window::EventNamespace + "/" + CEGUI::Window::EventDestructionStarted,
CEGUI::Event::Subscriber(&onWindowClosed) );</code>

We also need a stack to keep track of the windows. I chose to use the std::list type instead of the std::stack, because we need to be able to either delete all references of one element or to search the stack. So here it is:
<code><cpp/>std::list<CEGUI::Window *> pWinHistory;</code>

Also, don't forget to put your root window just before setting it as the root window:
<code><cpp/>pWinHistory.push_back(pMyRootWindow);
CEGUI::System::getSingleton().setGUISheet(pMyRootWindow);
</code>

One thing you need to know about the root window is that you need an empty root window, containing one or more child windows that contain all GUI items. Your root window will never become transparent, thus you need an empty "container" root window.

And now we implement our two callback functions. I excessively commented the functions.

onWindowActivated:
<code><cpp/>/// Called everytime a window gets activated.
/** This function is called by CEGUI every time that a window gets the focus.
*
* Currently, we use this function to keep track of the order that windows where
* active, so when closing a window we can activate the last one, as this isn't
* done automatically by CEGUI.
*
* \param e The event arguments.
*
* \return Always true.
*
* \author Pompei2
*/
bool onWindowActivated( const CEGUI::EventArgs &ea )
{
try {
const CEGUI::WindowEventArgs& we = static_cast<const CEGUI::WindowEventArgs&>(ea);
CEGUI::Window *pLastWin = pWinHistory.back( );

// We only work with FrameWindows.
if( !we.window->testClassName( CEGUI::FrameWindow::EventNamespace ) )
return true;

// If it is the same window as before, ignore it.
if( pLastWin == we.window )
return true;

if( pLastWin != CEGUI::System::getSingleton().getGUISheet() ) {
// If every time a window gets activated we make the last active window become
// transparent, this will result in all inactive windows being transparent.
pLastWin->setProperty( "Alpha", "0.25" );

// But we never make the root window transparent, as this would make all tooltips
// become transparent, and we don't want this !
}

// We need the active window to not inherit the transparence of its parents.
we.window->setProperty( "InheritsAlpha", "false" );

// Finally, we add the new window to the stack.

// One could also check if it's already present in the stack and if yes, just put it on the top.
// You would have to do this if you want to set the transparency depending on the window's position
// in the stack (see "Extending the effect").
pWinHistory.push_back( we.window );
} catch( CEGUI::Exception& e ) {
fprintf( stderr, "CEGUI error: %s\n", e.getMessage( ).c_str( ) );
return true;
}

return true;
}</code>

And onWindowClosed:
<code><cpp/>/// Called everytime a window gets closed.
/** This function is called by CEGUI just before a window gets closed.
*
* Currently, we use this function to activate the previous window
* when closing this one, as it's not done automatically by CEGUI.
*
* \param e The event arguments.
*
* \return Always true.
*
* \author Pompei2
*/
bool onWindowClosed( const CEGUI::EventArgs &ea )
{
try {
const CEGUI::WindowEventArgs& we = static_cast<const CEGUI::WindowEventArgs&>(ea);
CEGUI::Window *pLastWin = NULL;

// We only work with FrameWindows.
if( !we.window->testClassName( CEGUI::FrameWindow::EventNamespace ) )
return true;

// Delete the current window from the stack.
// CARE: std::list::remove removes ALL occurences of we.window from the stack !
// This is VERY important to know, as if you activate window A, then window B and then A again,
// the stack will contain A twice: {A,B,A}.
pWinHistory.remove( we.window );

// Now we get the window that was active before the current one:
pLastWin = m_pWinHistory.back( );

// re-activate it (like windos, linux, .. all do).
pLastWin->activate( );

// And set it to be opaque again.
// You could either do this here or you do this in the onWindowActivate function, the result is the same,
// as the call to CEGUI::Window::activate above results in onWindowActivate to be called.
pLastWin->setProperty( "Alpha", "1.0" );
} catch( CEGUI::Exception& e ) {
fprintf( stderr, "CEGUI error: %s\n", e.getMessage( ).c_str( ) );
return true;
}

return true;
}</code>

That's all.

One important thing you might not know yet, is that CEGUI DOESN'T activate a window that gets shown. you have to manually activate a window when you create it (and want it to be active, of course).

== Extending the effect ==
* You could also automatically activate a window as soon as it's shown. for this you could subscribe to the "a window gets shown" global event and then just call ea.window->activate( );
Edit: Hmm I tried this one but wasn't able to get it to work. If someone has success, please tell us how you did it in the forums.

* You could try to make the window's transparency degree dependent on its position in the stack. That means the most recent windows get less transparent while the "oldest" windows get very transparent. To do this, just loop trough the stack - that would be a list - and set every window's transparency accordingly. Do this when a window gets active AND when a window gets closed. You would also need to never have the same window twice in the stack, as it would screw your results up.

--[[User:Pompei2|Pompei2]] 06:00, 6 May 2007 (PDT)

----
----
you can add more cool effects here.