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

Building from source

2011-12-18T02:06:52Z

Pav: Added Category:HowTo

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' with plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see [[CEED]] for a detailed description.

CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.

{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}

===Dependencies===
CEED requires a Python 2 interpreter, version 2.6 or higher.
Apart from [[PyCEGUI]] (the CEGUI Python bindings), it depends on the following libraries:
* PyOpenGL
* Qt4, PySide (+ PySide Tools)
* Boost.Python

<tabs>
<tab title="Windows">
{{Todo|Windows dependencies notes}}
</tab>
<tab title="Mac">
{{Todo|Mac dependencies notes}}
</tab>
<tab title="Arch Linux">
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
</tab>
<tab title="Debian">
;Wheezy

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:

{{CLI||sudo apt-get update}}
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}

</tab>
<tab title="Fedora">
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
</tab>
</tabs>

===Running===
{{Todo|Update this section when CEED/CEGUI 0.8 is released}}
If you're following the directory structure outlined in [[#Building|Building]], you should have something like:
cegui (root working directory)
cegui/CEED (CEED repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

Running the main ''ceed-gui'' application could be as simple as:
{{CLI|~/cegui/CEED|2=PYTHONPATH=.:$PYTHONPATH python2 bin/ceed-gui}}

If you don't have PyCEGUI installed system-wide but built it in ''cegui/cegui_mk2/build'', you can run ''ceed-gui'' like this:
{{CLI|~/cegui/CEED|2=PYTHONPATH=../cegui_mk2/build/lib:.:$PYTHONPATH python2 bin/ceed-gui}}

====Running from Mercurial====
If you've cloned the CEED mercurial repository, you will most likely get the following error when you try to run ''ceed-gui'':
ImportError: No module named mainwindow
This is because the compiled .ui files are not part of the repository. Edit the file ''ceed/version.py'' with your favorite text editor and change the value of '''CEED_developerMode''' from '''False''' to '''True'''.

=Troubleshooting=
If you encounter a problem that's not listed here, please make a post on the appropriate forum: [http://www.cegui.org.uk/phpBB2/viewforum.php?f=10 CEGUI], [http://www.cegui.org.uk/phpBB2/viewforum.php?f=15 CEED].

For comments about this article, you may use it's discussion page.

=Related articles=
* [[Eclipse and CEGUI]]
* [[Contribution|Contributing to the development of CEGUI]]

[[Category:HowTo]]

Building from source

2011-12-18T01:58:12Z

Pav: /* Dependencies */ Make PyCEGUI a link

Building from source

2011-12-18T01:55:11Z

Pav: /* Documentation */ Typo

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' with plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see [[CEED]] for a detailed description.

CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.

{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}

===Dependencies===
CEED requires a Python 2 interpreter, version 2.6 or higher.
Apart from PyCEGUI (the CEGUI Python bindings), it depends on the following libraries:
* PyOpenGL
* Qt4, PySide (+ PySide Tools)
* Boost.Python

<tabs>
<tab title="Windows">
{{Todo|Windows dependencies notes}}
</tab>
<tab title="Mac">
{{Todo|Mac dependencies notes}}
</tab>
<tab title="Arch Linux">
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
</tab>
<tab title="Debian">
;Wheezy

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:

{{CLI||sudo apt-get update}}
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}

</tab>
<tab title="Fedora">
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
</tab>
</tabs>

===Running===
{{Todo|Update this section when CEED/CEGUI 0.8 is released}}
If you're following the directory structure outlined in [[#Building|Building]], you should have something like:
cegui (root working directory)
cegui/CEED (CEED repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

Running the main ''ceed-gui'' application could be as simple as:
{{CLI|~/cegui/CEED|2=PYTHONPATH=.:$PYTHONPATH python2 bin/ceed-gui}}

If you don't have PyCEGUI installed system-wide but built it in ''cegui/cegui_mk2/build'', you can run ''ceed-gui'' like this:
{{CLI|~/cegui/CEED|2=PYTHONPATH=../cegui_mk2/build/lib:.:$PYTHONPATH python2 bin/ceed-gui}}

====Running from Mercurial====
If you've cloned the CEED mercurial repository, you will most likely get the following error when you try to run ''ceed-gui'':
ImportError: No module named mainwindow
This is because the compiled .ui files are not part of the repository. Edit the file ''ceed/version.py'' with your favorite text editor and change the value of '''CEED_developerMode''' from '''False''' to '''True'''.

=Troubleshooting=
If you encounter a problem that's not listed here, please make a post on the appropriate forum: [http://www.cegui.org.uk/phpBB2/viewforum.php?f=10 CEGUI], [http://www.cegui.org.uk/phpBB2/viewforum.php?f=15 CEED].

For comments about this article, you may use it's discussion page.

=Related articles=
* [[Eclipse and CEGUI]]
* [[Contribution|Contributing to the development of CEGUI]]

Talk:Building from source

2011-12-18T01:48:52Z

Pav: Request for help finishing the article

This is an attempt to document everything needed to build and run CEGUI 0.8 and CEED. I've chosen to include everything in one page so that general information about the whole CEGUI project is available (without duplication) but mostly because I use a common directory structure so that both projects fit into place and run (it could have been a series but I, personally, think this is better).

* Needs review
* Help eliminate TODOs, especially Windows & Mac related instructions
* Remove the notice about the article being incomplete
* Comments? Suggestions?
[[User:Pav|Pav]] 01:48, 18 December 2011 (UTC)

Building from source

2011-12-18T01:31:28Z

Pav: /* Building */ Remove todo about directory structure - it's fine

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' which plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see [[CEED]] for a detailed description.

CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.

{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}

===Dependencies===
CEED requires a Python 2 interpreter, version 2.6 or higher.
Apart from PyCEGUI (the CEGUI Python bindings), it depends on the following libraries:
* PyOpenGL
* Qt4, PySide (+ PySide Tools)
* Boost.Python

<tabs>
<tab title="Windows">
{{Todo|Windows dependencies notes}}
</tab>
<tab title="Mac">
{{Todo|Mac dependencies notes}}
</tab>
<tab title="Arch Linux">
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
</tab>
<tab title="Debian">
;Wheezy

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:

{{CLI||sudo apt-get update}}
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}

</tab>
<tab title="Fedora">
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
</tab>
</tabs>

===Running===
{{Todo|Update this section when CEED/CEGUI 0.8 is released}}
If you're following the directory structure outlined in [[#Building|Building]], you should have something like:
cegui (root working directory)
cegui/CEED (CEED repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

Running the main ''ceed-gui'' application could be as simple as:
{{CLI|~/cegui/CEED|2=PYTHONPATH=.:$PYTHONPATH python2 bin/ceed-gui}}

If you don't have PyCEGUI installed system-wide but built it in ''cegui/cegui_mk2/build'', you can run ''ceed-gui'' like this:
{{CLI|~/cegui/CEED|2=PYTHONPATH=../cegui_mk2/build/lib:.:$PYTHONPATH python2 bin/ceed-gui}}

====Running from Mercurial====
If you've cloned the CEED mercurial repository, you will most likely get the following error when you try to run ''ceed-gui'':
ImportError: No module named mainwindow
This is because the compiled .ui files are not part of the repository. Edit the file ''ceed/version.py'' with your favorite text editor and change the value of '''CEED_developerMode''' from '''False''' to '''True'''.

=Troubleshooting=
If you encounter a problem that's not listed here, please make a post on the appropriate forum: [http://www.cegui.org.uk/phpBB2/viewforum.php?f=10 CEGUI], [http://www.cegui.org.uk/phpBB2/viewforum.php?f=15 CEED].

For comments about this article, you may use it's discussion page.

=Related articles=
* [[Eclipse and CEGUI]]
* [[Contribution|Contributing to the development of CEGUI]]

Contribution

2011-12-18T01:26:47Z

Pav: Add links to general guidelines and coding standards

The article describes how you can contribute to a CEGUI project with the help of [http://bitbucket.org BitBucket].

We prefer your contribution through BitBucket, because it simplifies the development process for both you and us. If your contribution needs a bit more tuning, we just say so and you make another commit to your BitBucket repository. After we are satisfied with the quality of the fixes, we simply pull them from you repository. And since your repository is located under your nickname, we will know you can be trusted. So it's a win-win for everybody.

If you prefer video tutorials, you can [http://www.youtube.com/watch?v=ZjFOvLGnAiU watch this tutorial].

While this is a practical guide, you should also read [http://www.cegui.org.uk/docs/current/devel.html the general guidelines] and the [http://www.cegui.org.uk/docs/current/code_standards.html Coding Standards] from the CEGUI Developer Documentation.

'''Note''': This tutorial describes contribution to [[CEED]] (CEGUI Editor) as a user '''kornerr''' as an example.

== Import CEED repository to BitBucket ==

Go to [https://bitbucket.org/repo/import Repositories -> import repository].

Input the following:
{| class="wikitable"
| Source
| Mercurial repository
|-
| URL
| http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED
|-
| Requires authorization
| No
|-
| Name
| CEED
|-
| Private
| No
|-
| Language
| Python (CEGUI itself is C++)
|-
| Description
| CEED contribution
|-
| Website
| Leave blank
|-
| Wiki
| Leave blank
|-
| Issue tracking
| Leave blank
|}

Press '''Import'''.

BitBucket will import the repository:

[[Image:Ceed_contrib_import_repo.png]]

Wait a bit, and you're done:

[[Image:Ceed contrib import repo done.png]]

== Clone from BitBucket to your machine ==
cd ~
hg clone https://bitbucket.org/kornerr/ceed

This will clone CEED repository from BitBucket to your home directory.

== Make changes, commit, and push ==

Make changes. Mine were:
diff --git a/compatibility/looknfeel/cegui.py b/compatibility/looknfeel/cegui.py
--- a/compatibility/looknfeel/cegui.py
+++ b/compatibility/looknfeel/cegui.py
@@ -95,6 +95,9 @@
log = ""

root = ElementTree.fromstring(data)
+ # Fix for Python < 2.7.
+ if not hasattr(root, "iter"):
+ root.iter = root.getiterator

# version 7 has a version attribute
root.set("version", "7")

Commit with a meaningful message, e.g., in my case it was:
hg commit -m "XML iterator fix for Python < 2.7. tested on Python 2.6"

And push it back to BitBucket:
kornerr@koren:~/ceed$ '''hg push'''
pushing to https://bitbucket.org/kornerr/ceed
searching for changes
http authorization equired
realm: Bitbucket.org HTTP
user: '''kornerr'''
password:
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 1 changesets with 1 changes to 1 files
remote: bb/acl: kornerr is allowed. accepted payload.

You can see your changes at BitBucket now:

[[Image:Ceed_contrib_push.png]]

'''Note: Please, don't try to merge many fixes into single commit. Place each fix into its own commit. It will be easier for us to understand your fixes and accept it faster.'''

== Contact CEGUI developer(s) ==
Use IRC, mail, or mantis. Tell the URL of your repository and list the changesets you want into upstream.

== Further contributions ==
If you will contribute again later, you need to first update your BitBucket repository to upstream version, and only then make changes. Please, do it, otherwise your fixes may be rejected simply because we can't spend hours in figuring out how to apply your old changes to the latest version.

To update your BitBucket repository to upstream version, go to your clone of BitBucket repository on your machine and do:
hg pull -u http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

Then simply push the changes back to your BitBucket repository:
hg push

Building from source

2011-12-18T01:12:51Z

Pav: /* Related Articles */

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)
{{Todo|Check directory structure so that CEED (which depends on CEGUI) works}}

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' which plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see [[CEED]] for a detailed description.

CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.

{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}

===Dependencies===
CEED requires a Python 2 interpreter, version 2.6 or higher.
Apart from PyCEGUI (the CEGUI Python bindings), it depends on the following libraries:
* PyOpenGL
* Qt4, PySide (+ PySide Tools)
* Boost.Python

<tabs>
<tab title="Windows">
{{Todo|Windows dependencies notes}}
</tab>
<tab title="Mac">
{{Todo|Mac dependencies notes}}
</tab>
<tab title="Arch Linux">
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
</tab>
<tab title="Debian">
;Wheezy

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:

{{CLI||sudo apt-get update}}
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}

</tab>
<tab title="Fedora">
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
</tab>
</tabs>

===Running===
{{Todo|Update this section when CEED/CEGUI 0.8 is released}}
If you're following the directory structure outlined in [[#Building|Building]], you should have something like:
cegui (root working directory)
cegui/CEED (CEED repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

Running the main ''ceed-gui'' application could be as simple as:
{{CLI|~/cegui/CEED|2=PYTHONPATH=.:$PYTHONPATH python2 bin/ceed-gui}}

If you don't have PyCEGUI installed system-wide but built it in ''cegui/cegui_mk2/build'', you can run ''ceed-gui'' like this:
{{CLI|~/cegui/CEED|2=PYTHONPATH=../cegui_mk2/build/lib:.:$PYTHONPATH python2 bin/ceed-gui}}

====Running from Mercurial====
If you've cloned the CEED mercurial repository, you will most likely get the following error when you try to run ''ceed-gui'':
ImportError: No module named mainwindow
This is because the compiled .ui files are not part of the repository. Edit the file ''ceed/version.py'' with your favorite text editor and change the value of '''CEED_developerMode''' from '''False''' to '''True'''.

=Troubleshooting=
If you encounter a problem that's not listed here, please make a post on the appropriate forum: [http://www.cegui.org.uk/phpBB2/viewforum.php?f=10 CEGUI], [http://www.cegui.org.uk/phpBB2/viewforum.php?f=15 CEED].

For comments about this article, you may use it's discussion page.

=Related articles=
* [[Eclipse and CEGUI]]
* [[Contribution|Contributing to the development of CEGUI]]

Building from source

2011-12-18T01:07:30Z

Pav: /* Troubleshooting */

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)
{{Todo|Check directory structure so that CEED (which depends on CEGUI) works}}

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' which plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see [[CEED]] for a detailed description.

CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.

{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}

===Dependencies===
CEED requires a Python 2 interpreter, version 2.6 or higher.
Apart from PyCEGUI (the CEGUI Python bindings), it depends on the following libraries:
* PyOpenGL
* Qt4, PySide (+ PySide Tools)
* Boost.Python

<tabs>
<tab title="Windows">
{{Todo|Windows dependencies notes}}
</tab>
<tab title="Mac">
{{Todo|Mac dependencies notes}}
</tab>
<tab title="Arch Linux">
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
</tab>
<tab title="Debian">
;Wheezy

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:

{{CLI||sudo apt-get update}}
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}

</tab>
<tab title="Fedora">
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
</tab>
</tabs>

===Running===
{{Todo|Update this section when CEED/CEGUI 0.8 is released}}
If you're following the directory structure outlined in [[#Building|Building]], you should have something like:
cegui (root working directory)
cegui/CEED (CEED repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

Running the main ''ceed-gui'' application could be as simple as:
{{CLI|~/cegui/CEED|2=PYTHONPATH=.:$PYTHONPATH python2 bin/ceed-gui}}

If you don't have PyCEGUI installed system-wide but built it in ''cegui/cegui_mk2/build'', you can run ''ceed-gui'' like this:
{{CLI|~/cegui/CEED|2=PYTHONPATH=../cegui_mk2/build/lib:.:$PYTHONPATH python2 bin/ceed-gui}}

====Running from Mercurial====
If you've cloned the CEED mercurial repository, you will most likely get the following error when you try to run ''ceed-gui'':
ImportError: No module named mainwindow
This is because the compiled .ui files are not part of the repository. Edit the file ''ceed/version.py'' with your favorite text editor and change the value of '''CEED_developerMode''' from '''False''' to '''True'''.

=Troubleshooting=
If you encounter a problem that's not listed here, please make a post on the appropriate forum: [http://www.cegui.org.uk/phpBB2/viewforum.php?f=10 CEGUI], [http://www.cegui.org.uk/phpBB2/viewforum.php?f=15 CEED].

For comments about this article, you may use it's discussion page.

=Related Articles=
* [[Eclipse_and_CEGUI]]

Building from source

2011-12-18T01:00:30Z

Pav: /* Running */

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)
{{Todo|Check directory structure so that CEED (which depends on CEGUI) works}}

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' which plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see [[CEED]] for a detailed description.

CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.

{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}

===Dependencies===
CEED requires a Python 2 interpreter, version 2.6 or higher.
Apart from PyCEGUI (the CEGUI Python bindings), it depends on the following libraries:
* PyOpenGL
* Qt4, PySide (+ PySide Tools)
* Boost.Python

<tabs>
<tab title="Windows">
{{Todo|Windows dependencies notes}}
</tab>
<tab title="Mac">
{{Todo|Mac dependencies notes}}
</tab>
<tab title="Arch Linux">
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
</tab>
<tab title="Debian">
;Wheezy

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:

{{CLI||sudo apt-get update}}
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}

</tab>
<tab title="Fedora">
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
</tab>
</tabs>

===Running===
{{Todo|Update this section when CEED/CEGUI 0.8 is released}}
If you're following the directory structure outlined in [[#Building|Building]], you should have something like:
cegui (root working directory)
cegui/CEED (CEED repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

Running the main ''ceed-gui'' application could be as simple as:
{{CLI|~/cegui/CEED|2=PYTHONPATH=.:$PYTHONPATH python2 bin/ceed-gui}}

If you don't have PyCEGUI installed system-wide but built it in ''cegui/cegui_mk2/build'', you can run ''ceed-gui'' like this:
{{CLI|~/cegui/CEED|2=PYTHONPATH=../cegui_mk2/build/lib:.:$PYTHONPATH python2 bin/ceed-gui}}

====Running from Mercurial====
If you've cloned the CEED mercurial repository, you will most likely get the following error when you try to run ''ceed-gui'':
ImportError: No module named mainwindow
This is because the compiled .ui files are not part of the repository. Edit the file ''ceed/version.py'' with your favorite text editor and change the value of '''CEED_developerMode''' from '''False''' to '''True'''.

=Troubleshooting=
{{Todo|Problems? -> Forum!}}

=Related Articles=
* [[Eclipse_and_CEGUI]]

Building from source

2011-12-18T00:28:47Z

Pav: /* Directories */ Remove extra spaces

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)
{{Todo|Check directory structure so that CEED (which depends on CEGUI) works}}

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' which plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see [[CEED]] for a detailed description.

CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.

{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}

===Dependencies===
CEED requires a Python 2 interpreter, version 2.6 or higher.
Apart from PyCEGUI (the CEGUI Python bindings), it depends on the following libraries:
* PyOpenGL
* Qt4, PySide (+ PySide Tools)
* Boost.Python

<tabs>
<tab title="Windows">
{{Todo|Windows dependencies notes}}
</tab>
<tab title="Mac">
{{Todo|Mac dependencies notes}}
</tab>
<tab title="Arch Linux">
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
</tab>
<tab title="Debian">
;Wheezy

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:

{{CLI||sudo apt-get update}}
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}

</tab>
<tab title="Fedora">
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
</tab>
</tabs>

===Running===
{{Todo|Running}}

=Troubleshooting=
{{Todo|Problems? -> Forum!}}

=Related Articles=
* [[Eclipse_and_CEGUI]]

Building from source

2011-12-18T00:25:06Z

Pav: /* Dependencies */ Dependency CEGUI -> PyCEGUI

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)
{{Todo|Check directory structure so that CEED (which depends on CEGUI) works}}

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' which plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see [[CEED]] for a detailed description.

CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.

{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}

===Dependencies===
CEED requires a Python 2 interpreter, version 2.6 or higher.
Apart from PyCEGUI (the CEGUI Python bindings), it depends on the following libraries:
* PyOpenGL
* Qt4, PySide (+ PySide Tools)
* Boost.Python

<tabs>
<tab title="Windows">
{{Todo|Windows dependencies notes}}
</tab>
<tab title="Mac">
{{Todo|Mac dependencies notes}}
</tab>
<tab title="Arch Linux">
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
</tab>
<tab title="Debian">
;Wheezy

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:

{{CLI||sudo apt-get update}}
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}

</tab>
<tab title="Fedora">
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
</tab>
</tabs>

===Running===
{{Todo|Running}}

=Troubleshooting=
{{Todo|Problems? -> Forum!}}

=Related Articles=
* [[Eclipse_and_CEGUI]]

Template:Todo

2011-12-17T23:48:52Z

Pav: Remove extraneous lines #2 :/

<noinclude>
A ''Todo'' box used to mark missing content. Automatically adds the WIP category.

====Usage====

<nowiki>{{Todo|Complete this section.}}</nowiki>

====Example====

{{Todo|Complete this section.}}</noinclude><includeonly>{{Box|Todo:|{{{1}}}|#DDDDBB|#FFFFDD}}[[Category:WIP]]</includeonly>

Template:Todo

2011-12-17T23:47:30Z

Pav: Remove extraneous lines

<noinclude>
A ''Todo'' box used to mark missing content. Automatically adds the WIP category.

====Usage====

<nowiki>{{Todo|Complete this section.}}</nowiki>

====Example====

{{Todo|Complete this section.}}</noinclude>
<includeonly>{{Box|Todo:|{{{1}}}|#DDDDBB|#FFFFDD}}[[Category:WIP]]</includeonly>

Template:Todo

2011-12-17T23:45:14Z

Pav: Add WIP category

<noinclude>
A ''Todo'' box used to mark missing content. Automatically adds the WIP category.

====Usage====

<nowiki>{{Todo|Complete this section.}}</nowiki>

====Example====

{{Todo|Complete this section.}}</noinclude>
<includeonly>
{{Box|Todo:|{{{1}}}|#DDDDBB|#FFFFDD}}
[[Category:WIP]]
</includeonly>

Building from source

2011-12-17T23:11:13Z

Pav: /* Directories */ Add todo about stable source packages

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)
{{Todo|Check directory structure so that CEED (which depends on CEGUI) works}}

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

{{Todo|Add instructions on where to extract the stable source packages (when available) so that we maintain a common directory structure}}

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' which plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see [[CEED]] for a detailed description.

CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.

{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}

===Dependencies===
CEED requires a Python 2 interpreter, version 2.6 or higher.
Apart from CEGUI, it depends on the following libraries:
* PyOpenGL
* Qt4, PySide (+ PySide Tools)
* Boost.Python

<tabs>
<tab title="Windows">
{{Todo|Windows dependencies notes}}
</tab>
<tab title="Mac">
{{Todo|Mac dependencies notes}}
</tab>
<tab title="Arch Linux">
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
</tab>
<tab title="Debian">
;Wheezy

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:

{{CLI||sudo apt-get update}}
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}

</tab>
<tab title="Fedora">
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
</tab>
</tabs>

===Running===
{{Todo|Running}}

=Troubleshooting=
{{Todo|Problems? -> Forum!}}

=Related Articles=
* [[Eclipse_and_CEGUI]]

Building from source

2011-12-17T23:00:44Z

Pav: /* Dependencies */ Close </tabs> (oops)

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)
{{Todo|Check directory structure so that CEED (which depends on CEGUI) works}}

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' which plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see [[CEED]] for a detailed description.

CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.

{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}

===Dependencies===
CEED requires a Python 2 interpreter, version 2.6 or higher.
Apart from CEGUI, it depends on the following libraries:
* PyOpenGL
* Qt4, PySide (+ PySide Tools)
* Boost.Python

<tabs>
<tab title="Windows">
{{Todo|Windows dependencies notes}}
</tab>
<tab title="Mac">
{{Todo|Mac dependencies notes}}
</tab>
<tab title="Arch Linux">
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
</tab>
<tab title="Debian">
;Wheezy

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:

{{CLI||sudo apt-get update}}
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}

</tab>
<tab title="Fedora">
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
</tab>
</tabs>

===Running===
{{Todo|Running}}

=Troubleshooting=
{{Todo|Problems? -> Forum!}}

=Related Articles=
* [[Eclipse_and_CEGUI]]

Building from source

2011-12-17T22:58:11Z

Pav: /* CEED */ General, Dependencies

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)
{{Todo|Check directory structure so that CEED (which depends on CEGUI) works}}

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' which plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
CEED is the new CEGUI unified editor. It can edit layouts and imagesets, supports projects and multiple open file tabs, visual and source editing, preview and more. Please see [[CEED]] for a detailed description.

CEED is written in [http://www.python.org/ Python] so there's no need to build it; all that's required is Python2 and it's dependencies.

{{Note|If you'd rather use a stable package that includes dependencies, please follow [[Downloads]]}}

===Dependencies===
CEED requires a Python 2 interpreter, version 2.6 or higher.
Apart from CEGUI, it depends on the following libraries:
* PyOpenGL
* Qt4, PySide (+ PySide Tools)
* Boost.Python

<tabs>
<tab title="Windows">
{{Todo|Windows dependencies notes}}
</tab>
<tab title="Mac">
{{Todo|Mac dependencies notes}}
</tab>
<tab title="Arch Linux">
You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR).
{{Note|The packages from AUR may have been included in the ''[community]'' repository by now so check there first.}}
</tab>
<tab title="Debian">
;Wheezy

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list and then:

{{CLI||sudo apt-get update}}
{{CLI||sudo apt-get install cmake python-opengl pyside-tools boost-python}}

</tab>
<tab title="Fedora">
You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools.
</tab>

===Running===
{{Todo|Running}}

=Troubleshooting=
{{Todo|Problems? -> Forum!}}

=Related Articles=
* [[Eclipse_and_CEGUI]]

Building from source

2011-12-17T16:33:04Z

Pav: /* Documentation */

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)
{{Todo|Check directory structure so that CEED (which depends on CEGUI) works}}

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' which plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
{{Todo|Short description}}
{{Todo|Note and link to prebuilt binary downloads}}

===Dependencies===
{{Todo|Dependencies general}}

====Windows====
{{Todo|Windows deps & notes}}

====Mac====
{{Todo|Mac deps & notes}}

====Linux====
{{Todo|Linux deps & notes}}

=====Distro1=====
{{Todo|Distro specific deps & notes}}

===Running===
{{Todo|Running}}

=Troubleshooting=
{{Todo|Problems? -> Forum!}}

=Related Articles=
* [[Eclipse_and_CEGUI]]

Building from source

2011-12-17T16:32:11Z

Pav: /* Documentation */

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)
{{Todo|Check directory structure so that CEED (which depends on CEGUI) works}}

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}

The documentation is written in doxygen format so you need [http://www.doxygen.org/ Doxygen] to build it. If you want to generate the nice class diagrams too, you need to install [http://graphviz.org/ Graphviz].

Building the docs with the default options is easy:
{{CLI|~/cegui/cegui_mk2/build|cd ../source/doc/doxygen}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|doxygen}}

This will create a directory named ''html'' which plenty of files, just open ''index.html''.

If you'd rather change some of doxygen's options, you can edit the file ''source/doc/doxygen/doxyfile'' or, alternatively, use ''doxywizard'' (GUI).
To change doxygen's output directory, one might do something like this:
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|mkdir ../../../build/doc}}
{{CLI|~/cegui/cegui_mk2/source/doc/doxygen|nano doxyfile or use your editor of choice to edit ''doxyfile''}}

Find the line
OUTPUT_DIRECTORY =
and change it to
OUTPUT_DIRECTORY = ../../../build/doc

Now run doxygen and it will create the html docs in ''build/doc''.

==CEED==
{{Todo|Short description}}
{{Todo|Note and link to prebuilt binary downloads}}

===Dependencies===
{{Todo|Dependencies general}}

====Windows====
{{Todo|Windows deps & notes}}

====Mac====
{{Todo|Mac deps & notes}}

====Linux====
{{Todo|Linux deps & notes}}

=====Distro1=====
{{Todo|Distro specific deps & notes}}

===Running===
{{Todo|Running}}

=Troubleshooting=
{{Todo|Problems? -> Forum!}}

=Related Articles=
* [[Eclipse_and_CEGUI]]

Building from source

2011-12-17T05:56:10Z

Pav: /* Running the samples */

{{VersionBadge|0.8}}
{{notice|message=This article is a work in progress and thus incomplete}}

=Obtaining the source=
{{Note|If you'd rather use precompiled SDKs, please follow [[Downloads]].}}
==Stable Releases==
Source code from the stable mercurial branches is released at various points in time and made available as source code packages. These packages can be found on the [[Downloads]] page.

==Mercurial==
The source code is kept in mercurial repositories at sourceforge.net. There are code repositories for the main CEGUI libraries as well as for other related items.

A mercurial client (GUI or <abbr title="Command-line Interface">CLI</abbr>) is required to access the mercurial repositories and download code. The command necessary to obtain a copy of the code is 'clone':
hg clone SOURCE DESTINATION
where ''source'' is the URL of the repository to clone and ''destination'' is the local directory. To download a copy of CEGUI and place it in the ''cegui-source'' directory, you might use the following command:
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source

Once you have this, the cloned repository is updated to the default (latest, unstable) code, so you most likely will want to switch to a stable branch instead, like this:
hg update -C v0-8
{{Warning|Be aware that the -C option here will discard any local file changes without additional warning}}

===Repositories===
The available repositories can be found [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/ here] where you can also browse their code from your web browser. A couple of examples:
* Core CEGUI libraries - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/cegui_mk2 cegui_mk2]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui-source
* CEED unified editor - [http://crayzedsgui.hg.sourceforge.net/hgweb/crayzedsgui/CEED CEED]
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED

{{Note|The difference between the ''hg clone'' URLs and the web-interface URLs is ''hgroot'' vs ''hgweb''}}

=Building=
CEGUI uses [http://www.cmake.org/ CMake] as a build system. CMake is cross-platform and open source so it's available on many platforms. There are binaries available for Windows, Mac and Linux, although on Linux your distribution will most probably have a CMake package ready. Make sure you install it before continuing.
{{Note|CMake does not build the code directly, it generates native makefiles and workspaces that can be used in the compiler environment of your choice.}}
Thanks to CMake and CEGUI's modular design, configuring and building CEGUI is a breeze.

The following instructions assume you have a ''cegui'' directory somewhere on your system so that all CEGUI related projects reside in it.
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
cegui/CEED (editor)
cegui/... (something else)
{{Todo|Check directory structure so that CEED (which depends on CEGUI) works}}

==CEGUI==
This section will focus on building the core CEGUI libraries, which is all you need to use CEGUI in a project. Most people will also want [[Building from source#CEED|CEED]], the unified editor for CEGUI, but it is not required.

===Dependencies===
CEGUI can be built without any dependencies to outside libraries. However, typical configurations require [http://en.wikipedia.org/wiki/FreeType FreeType], a rendering module, an XML parser, and an image codec. CEGUI already provides support for several external libraries thanks to its modular design:

{| class="wikitable"
|-
! Feature
! Supported Libraries
|-
| Bi-Directional Language
| MiniBIDI, FriBIDI
|-
| Font
| FreeType
|-
| Image Codec
| DevIL, FreeImage, OGRE, SILLY
|-
| Memory Management
| OGRE, nedmalloc
|-
| Regular Expression
| PCRE
|-
| Rendering
| Direct3D, Irrlicht, OGRE, OpenGL
|-
| Resource Providers
| Default (standard cross-platform file-access), minizip, OGRE
|-
| Scripting
| Lua, Python
|-
| XML
| Expat, LibXML2, RapidXml, TinyXML, Xerces-C++
|}

CMake will automatically detect which external libraries exist on your system and will build CEGUI accordingly so make sure you install any external libraries you want to use before proceeding.
{{Todo|Does the above ^ work on Windows and Mac?}}
{{Note|You can turn off individual CEGUI modules from building (even if you have the required libraries installed) by changing the default [[Building from source#Build Options|Build Options]].}}

===Directories===
If you're following the directory structure outlined above, you should have something like:
cegui (root working directory)
cegui/cegui_mk2 (core CEGUI)
Create the directory ''cegui/cegui_mk2/build'' and clone the ''cegui_mk2'' repository inside cegui/cegui_mk2 with the name ''source''. Example:
{{CLI|~/cegui|mkdir cegui_mk2/build}}
{{CLI|~/cegui|hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/source}}
The result should be:
cegui/cegui_mk2 (core CEGUI)
cegui/cegui_mk2/build (will build here)
cegui/cegui_mk2/source (the mercurial repository copy)

===Build Options===
There are several build options (or variables) supported by the CEGUI build system. To view them, you can use the command like or CMake GUI.

====Using the command line====
Enter the ''build'' directory and issue the following cmake command:
{{CLI|~/cegui/cegui_mk2|cd build}}
{{CLI|~/cegui/cegui_mk2/build|cmake -LH ../source}}
{{Note|On systems that default to python3 (like Arch Linux) you have to tell it to use python2 like this:}}
{{CLI|~/cegui/cegui_mk2/build|2=cmake -LH -DPYTHON_EXECUTABLE=/usr/bin/python2 ../source}}
CMake will run, it will look for the build systems available on your platform, will look for dependencies and then will print a list of variables, along with their description. For example:
// Select whether bi-directional text is enabled and which library should be used:
0: Disabled.
1: Use integrated minibidi library.
2: Use external fribidi library.
CEGUI_BIDI_SUPPORT:STRING=0
// Specifies whether to use embedded GLEW when external library was found
CEGUI_BUILD_EMBEDDED_GLEW:BOOL=OFF

====Using CMake GUI====
Start cmake-gui, select our ''source'' and ''build'' directories and click the ''Configure'' button. The available options will be listed in the main window. You can hover the mouse over an option and CMake will show a tooltip with a more detailed description.

{{Note|Changing the options and building is explained below, in [[#Building|Building]].}}

===Building===
====Configuring and Generating makefiles====
The first step is to use CMake to configure the build and generate native makefiles. Without making any configuration changes, the command would be:
{{CLI|~/cegui/cegui_mk2/build|cmake ../source}}
The same can be done using the CMake GUI. Select the ''source'' and ''build'' directories, click configure and finally click generate.

The build options can be changed via the GUI or via the CLI. If, for example, we want to turn off the slotted installation option and the python bindings we would run cmake like this:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source -DCEGUI_SLOTTED_INSTALLATION:BOOL=OFF -DCEGUI_BUILD_PYTHON_MODULES:BOOL=OFF}}
{{Note|The python bindings are required by [[#CEED|CEED]] so don't disable them if you plan to use it.}}

Another noteworthy option is the installation path, which is where CEGUI will be installed if you plan to install it via ''make install''. Change the value of the CMAKE_INSTALL_PREFIX configuration variable to set it. Example:
{{CLI|~/cegui/cegui_mk2/build|2=cmake ../source <other options here> -DCMAKE_INSTALL_PREFIX:PATH=/opt}}
so it will be installed in /opt/CEGUI (or /opt/CEGUI-0.8 if you use slotted installation).

====Make====
The second (and last required) step is using the generated native makefiles to build it. This is specific to your build environment; you may need to open the generated solution with MSVC or Xcode, or simply issue the ''make'' command.

<tabs>
<tab title="GNU Make">
* You can speed ''make'' up significantly if you have a multi-core CPU by adding the ''-jN'' parameter, when N is the number of CPU cores on your machine.
{{CLI|~/cegui/cegui_mk2/build|make -j4}}
* Optionally, run ''make install'' to install the binaries and the shared datafiles on your system.
</tab>
<tab title="MSVC">
{{Todo|MSVC notes}}
</tab>
<tab title="Xcode">
{{Todo|Xcode notes}}
</tab>
</tabs>

===Running the samples===
Now that the build has finished, you can run the sample applications to check your build. The binaries should be in the ''bin'' directory:
cegui/cegui_mk2/build/bin

The samples may fail to run initially because they can't find the required data files.
According to ''"cegui/cegui_mk2/source/Samples/common/include/CEGUISamplesConfig.h.in"'', the samples will look for the datafiles on ''"../datafiles"'' on Windows and on ''${CMAKE_INSTALL_PREFIX}/${CEGUI_DATA_INSTALL_DIR}'' on other platforms.

It is possible to change this path without rebuilding, using the environment variable ''CEGUI_SAMPLE_DATAPATH''.
<tabs>
<tab title="Linux">
{{CLI|~/cegui/cegui_mk2/build|2=CEGUI_SAMPLE_DATAPATH=../source/datafiles bin/CEGUIDemo8-0.8}}
</tab>
<tab title="Windows">
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=SET CEGUI_SAMPLE_DATAPATH="C:\Users\User\cegui\cegui_mk2\source\datafiles"}}
{{CLI|C:\Users\User\cegui\cegui_mk2\build|2=bin/CEGUIDemo8-0.8.exe}}
</tab>
</tabs>

===Documentation===
{{Note|The documentation for stable releases can be found online [http://www.cegui.org.uk/docs/current here]}}
{{Todo|Doxygen howto}}

==CEED==
{{Todo|Short description}}
{{Todo|Note and link to prebuilt binary downloads}}

===Dependencies===
{{Todo|Dependencies general}}

====Windows====
{{Todo|Windows deps & notes}}

====Mac====
{{Todo|Mac deps & notes}}

====Linux====
{{Todo|Linux deps & notes}}

=====Distro1=====
{{Todo|Distro specific deps & notes}}

===Running===
{{Todo|Running}}

=Troubleshooting=
{{Todo|Problems? -> Forum!}}

=Related Articles=
* [[Eclipse_and_CEGUI]]

Building from source

2011-12-17T05:35:29Z

Pav: /* CEGUI */ Add section about running the samples

Building from source

2011-12-17T05:32:48Z

Pav: /* Make */ Use tabs for platform specific notes

Building from source

2011-12-17T04:59:28Z

Pav: /* GNU Make */ Use Template:CLI

Building from source

2011-12-17T04:58:07Z

Pav: /* Configuring and Generating makefiles */ Use Template:CLI

Template:CLI

2011-12-17T04:55:59Z

Pav:

<noinclude>
A generic command line prompt and command.

====Usage====
* <nowiki>{{CLI||command --with --parameters}}</nowiki>
* <nowiki>{{CLI|/current/path|command --with --parameters}}</nowiki>
* <nowiki>{{CLI|~/path|2=a command that includes then equal (=) sign}}</nowiki>

====Example====

{{CLI||command --with --parameters}}
{{CLI|/current/path|command --with --parameters}}
{{CLI|~/path|2=a command that includes then equal (=) sign}}
</noinclude><includeonly> {{#if:{{{1|}}}|<span style="color:#080">[</span>|}}<span style="color:#888">{{{1}}}</span>{{#if:{{{1|}}}|<span style="color:#080">]</span>|}}<span style="color:#080">$ </span>{{{2}}}</includeonly>

Building from source

2011-12-17T04:52:01Z

Pav: /* Using the command line */ Use Template:CLI

Building from source

2011-12-17T04:45:38Z

Pav: /* Directories */ Use Template:CLI

Template:CLI

2011-12-17T04:42:35Z

Pav: Created page with "<noinclude> A generic command line prompt and command. ====Usage==== * <nowiki>{{CLI||command --with --parameters}}</nowiki> * <nowiki>{{CLI|/current/path|command --with --param..."

<noinclude>
A generic command line prompt and command.

====Usage====
* <nowiki>{{CLI||command --with --parameters}}</nowiki>
* <nowiki>{{CLI|/current/path|command --with --parameters}}</nowiki>

====Example====

{{CLI||command --with --parameters}}
{{CLI|/current/path|command --with --parameters}}
</noinclude><includeonly> {{#if:{{{1|}}}|<span style="color:#080">[</span>|}}<span style="color:#888">{{{1}}}</span>{{#if:{{{1|}}}|<span style="color:#080">]</span>|}}<span style="color:#080">$ </span>{{{2}}}</includeonly>

Building from source

2011-12-17T04:02:08Z

Pav: /* Using the command line */ color CLI prompt

Building from source

2011-12-17T04:00:55Z

Pav: /* Directories */ color CLI prompt

Building from source

2011-12-17T03:43:22Z

Pav: /* GNU Make */

Building from source

2011-12-17T03:36:52Z

Pav: /* GNU Make */ Remove ccache, doesn't belong here

Building from source

2011-12-16T19:37:03Z

Pav: /* Building */

Building from source

2011-12-16T15:52:12Z

Pav: /* Build Options */

Building from source

2011-12-16T15:15:39Z

Pav: /* Building */

Building from source

2011-12-16T14:41:56Z

Pav: /* Dependencies */ CMake auto-detection

Building from source

2011-12-16T14:29:01Z

Pav: /* Building */

Building from source

2011-12-16T13:28:01Z

Pav: Work in progress

Template:Todo

2011-12-16T12:56:59Z

Pav: Created page with "<noinclude> A ''Todo'' box used to mark missing content. ====Usage==== <nowiki>{{Todo|Complete this section.}}</nowiki> ====Example==== {{Todo|Complete this section.}}</noinc..."

<noinclude>
A ''Todo'' box used to mark missing content.

====Usage====

<nowiki>{{Todo|Complete this section.}}</nowiki>

====Example====

{{Todo|Complete this section.}}</noinclude><includeonly>{{Box|Todo:|{{{1}}}|#DDDDBB|#FFFFDD}}</includeonly>

Template:Warning

2011-12-16T11:00:32Z

Pav: Created page with "<noinclude> '''A 'Warning' box used to report potential danger. ====Usage==== <nowiki>{{Warning|This text should be heeded.}}</nowiki> ====Example==== {{Warning|This text sho..."

<noinclude>
'''A 'Warning' box used to report potential danger.

====Usage====

<nowiki>{{Warning|This text should be heeded.}}</nowiki>

====Example====

{{Warning|This text should be heeded.}}</noinclude><includeonly>{{Box|Warning:|{{{1}}}|#DDBBBB|#FFDDDD}}</includeonly>

Template:Note

2011-12-16T10:59:37Z

Pav: Created page with "<noinclude> '''A 'Note' box used to emphasize important information.''' ====Usage==== <nowiki>{{Note|This text should be noted.}}</nowiki> ====Example==== {{Note|This text sh..."

<noinclude>
'''A 'Note' box used to emphasize important information.'''

====Usage====

<nowiki>{{Note|This text should be noted.}}</nowiki>

====Example====

{{Note|This text should be noted.}}</noinclude><includeonly>{{Box|Note:|{{{1}}}|#BBBBDD|#DDDDFF}}</includeonly>

Template:Box

2011-12-16T10:55:56Z

Pav: Generic message box

<noinclude>

'''A generic message box.'''

====Usage====
* <nowiki>{{Box||Content without heading}}</nowiki>
* <nowiki>{{Box|Example:|Content with heading}}</nowiki>
* <nowiki>{{Box|Example:|Content followed by border-color|#DF0000}}</nowiki>
* <nowiki>{{Box|Example:|Content followed by border-color and background-color|#DF0000|#FFDFDF}}</nowiki>

====Example====

{{Box||Content without heading}}
{{Box|Example:|Content with heading}}
{{Box|Example:|Content followed by border-color|#DF0000}}
{{Box|Example:|Content followed by border-color and background-color|#DF0000|#FFDFDF}}
</noinclude><includeonly><div style="padding: 5px; margin: 0.50em 0; background-color: {{{4}}}; border: thin solid {{{3|#000}}}; overflow: hidden;"><strong> {{{1}}} </strong>{{{2}}}</div></includeonly>

Porting tips and changes from 0.7.X to 0.8.X

2011-12-16T09:47:52Z

Pav: Rotation property changes

{{VersionBadge|0.7}}

{{Section|1=Introduction|2=
This is work in progress, so while this page will be kept as up-to-date as possible, what you read here on any given day will never be definitive and is subject to further change until such time as a stable release is made. There are no current download packages contain the code this page relates to; this code is only available from the cegui_mk2/trunk directory in the subversion repository (see [[Obtaining the library source from Subversion]]).
}}
{{Section|1=Major renames/API changes|2=
* CEGUI::Window was renamed to CEGUI::Widget as Widget is the coined term for that, WindowManager renamed to WidgetManager, etc... (not in mercurial yet!)
* The stock/standard window renderer set (now widget renderer set) FalagardWRBase was renamed to StandardWRSet to avoid confusion with core [[Falagard]] facilities (not in mercurial yet!)
* Image class is now an abstract interface. BasicImage implementation is provided, and used for internally created Image objects.
* Imageset class is removed. You now use the new ImageManager to access defined images.
* ImagesetManager class is removed. You now use the new ImageManager.
* Windows now don't have absolute names! Every window's name only has to be unique in it's parent window.
}}
{{Section|1=Name this section|2=
* Image::draw renamed to Image::render
* PropertyHelper has been turned into a template class, instead of PropertyHelper::uintToString you do PropertyHelper<uint>::toString, instead of PropertyHelper::stringToUint you do PropertyHelper<uint>::fromString
* All instances of the word caret that were incorrectly spelt 'carat' have been corrected. This affects all APIs, properties, events and datafiles.
* Window::EventWindowUpdated renamed to Window::EventUpdated and the associated string is changed from "WindowUpdate" to "Updated"
* ListHeader::SegmentNameSuffix changed type from character array to CEGUI::String
* EventMouseEnters renamed to EventMouseEntersSurface (old name removed)
* EventMouseLeaves renamed to EventMouseLeavesSurface (old name removed)
* BiDiVisualMapping renamed to BidiVisualMapping. Also renamed the files, so CEGUIBiDiVisualMapping.h is now CEGUIBidiVisualMapping.h
* class colour renamed to Colour, as a side effect the "colour" interpolator is now "Colour" interpolator, this breaks animation definitions!
* Point typedef removed, please use Vector2 instead
* Many event string values changed to match the C++ name (but without the Event prefix). A list of which strings changed value will appear here soon.
* Window::setRestoreCapture renamed to Window::setRestoreOldCapture
* CEGUI now supports custom memory allocation, see [[Memory Allocation]] to check if this concerns you or not.
* Window::addChildWindow renamed to Window::addChild, Window::removeChildWindow renamed to Window::removeChild, several other methods (mostly in layout containers) changed from *ChildWindow* to *Child*
* CEGUI::String can now be just a typedef or a class, depending on String configuration (CEGUI can now use std::string as CEGUI::String for apps not requiring unicode)
* Window::getChild_impl method completely removed, it was only used by Window::getParentPixelSize, shouldn't be hard to replace
* Vector2, Vector3, Size and Rect are now templated, you should use Vector2<float> (or just Vector2<> as a shortcut since float is the default type) instead of Vector2, UVector2 class was removed, UVector2 is now just a typedef to Vector2<UDim>. Same with Vector3, Size and Rect.
* Texture::saveToMemory is renamed Texture::blitToMemory.
* Renderer and Texture interfaces changed in order to support named textures.
* Window::isDisabled(localOnly) is now split into Window::isDisabled (= old isDisabled(true) and Window::isEffectiveDisabled (= old isDisabled(false))
* Window::isVisible(localOnly) is now split into Window::isVisible (= old isDisabled(true) and Window::isEffectiveVisible (= old isVisible(false))
* WindowManager::loadWindowLayout is renamed to WindowManager::loadLayoutFromFile
* NamedXMLResourceManager::create is renamed to NamedXMLResourceManager::createFromFile (Ex. CEGUI::SchemeManager::createFromFile)
* Property from Window called "ZOrderChangeEnabled" renamed to "ZOrderingEnabled"
* Property from Window called "MouseButtonDownAutoRepeat" renamed to "MouseAutoRepeatEnabled"
* Property from Window called "CustomTooltipType" renamed to "TooltipType"
* Property from Window called "RiseOnClick" renamed to "RiseOnClickEnabled"
* Property from Window called "UnifiedAreaRect" renamed to "Area", "UnifiedSize" renamed to "Size", etc...
* CEGUI::DefaultLogger no longer throws const char* but a real exception in setLogFilename - http://www.cegui.org.uk/mantis/view.php?id=443
* CEGUI now has inbuilt copy, cut, paste support, if you used a custom solution, you might want to check CEGUI::Clipboard and System::injectCopy,Cut,PasteRequest
* CEGUI::ProgressBar::getStep renamed to getStepSize for consistency with setStepSize
* CEGUI::WidgetLookManager::parseLookNFeelSpecification is now called parseLookNFeelSpecificationFromFile, variants for loading from string and raw data container have been added
* XRotation, YRotation, ZRotation properties merged into the new Rotation property, which is a Quaternion.
}}
{{Section|1=PyCEGUI|2=
* EventSet.subscribeEvent now has a different, more pythonic syntax, any python callable (bound member function, free function, lambda, functor, ...) is allowed (EventSet.subscribeEvent("EventName", instance, "someMethodInIt") is now EventSet.subscribeEvent("EventName", instance.someMethodInIt)
}}
[[Category:Manuals]]

CEED

2011-12-15T15:16:36Z

Pav: /* Arch Linux */

Upcoming CEGUI unified editor. Currently in the early stages. Includes project management and multi-file/multi-tab editing.

== Install ==

CEED depends on an yet unreleased CEGUI 0.8, so you will need to set up a special environment to run it.

[http://www.cegui.org.uk/phpBB2/viewtopic.php?f=15&t=5566 Original post at the forums]

=== Dependencies ===

You need CMake, Python >= 2.6, PyOpenGL, PySide (+ utils/tools), Boost.Python.

==== Debian Wheezy ====

PySide is part of Sid at the moment, so you have to add its repository address to your /etc/apt/sources.list

apt-get install cmake python-opengl pyside-tools boost-python

==== Arch Linux ====

You need at least python2, boost, python-opengl, pyside (AUR), pyside-tools (AUR). PySide will bring in several other packages and will probably take a few hours to compile.

Note: You probably need to add "-DPYTHON_EXECUTABLE=/usr/bin/python2" (without the quotes) to the cmake command line below because Arch Linux defaults to python 3 but the python modules CMake script expects python2.

==== Fedora ====

You need boost-devel, python-devel, python-opengl, python-pyside, pyside-tools

=== Build CEGUI and PyCEGUI ===

mkdir -p cegui_mk2/build
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/cegui_mk2 cegui_mk2/cegui
hg clone http://crayzedsgui.hg.sourceforge.net/hgroot/crayzedsgui/CEED
cd cegui_mk2/build
cmake -DCEGUI_BUILD_PYTHON_MODULES=ON ../cegui
make

== Launch ==

cd CEED
./runwrapper.sh
python CEED.py

or
$ cd CEED/bin
$ PYTHONPATH=../../cegui_mk2/build/lib:../:$PYTHONPATH python2 ./ceed-gui

You will see a window like this:

[[Image:Ceed_main_window.png]]

=== Troubleshooting ===
* If it fails to import ceed.ui.* then you probably need to edit version.py and set CEED_developerMode to True.
$ nano ../ceed/version.py
* If the data files are missing you need to run the 'maintenance' script like this:
[CEED/bin]$ cd ..
[CEED]$ python2 ./maintenance fetch-datafiles

== Project ==

Unlike old editors (CELayoutEditor and CEImagesetEditor), CEED has a notion of a project. Each project has its own combination of resources and runs its own CEGUI version to render your CEGUI resources. This allows you to have more that one scheme loaded at a time.

To create a new project, you should go to '''File -> New project'''.

The dialog appears. You should input project name and location of the ".project" file. '''Note''': parent directory of the ".project" file must exist.

[[Image:Ceed_new_project.png]]

After you press '''OK''', Project settings window appears.

=== Project settings ===

(The window is also accessible from '''Edit -> Project settings''')

[[Image:Ceed_project_settings.png]]

CEED can create assets for CEGUI versions: 0.6 to 0.8. 0.7 is the latest stable, so select it.

Point "Resource directory" to the place where "fonts", "schemes" and the rest directories are located, then press '''Apply'''. It will change the paths below.

Press '''OK''' and will load your resources. If it fails to, it will show you a warning dialog:

[[Image:Ceed_new_project_warning.png]]

In our case, the resource directory does not have "schemes" subdirectory, as noted on the last line. Correct the paths and retry.

=== Project resources ===

Currently CEED can only work with imagesets and layouts. Add them to your project by clicking with the right mouse button on '''Project manager''' and selecting '''Add existing file(s)''':

[[Image:Ceed_project_add_existing.png]]

Select the necessary imagesets and layouts, and save the project.

=== Layouts ===

[[Image:Ceed_layout.png]]

To create a new widget, drag it from the left bottom panel.

To edit it, you can either do it visually, or switch to "Code" tab seen below, and edit it manually. There's also "Preview" tab, where you can test your layout in real time.

=== Imagesets ===

[[Image:Ceed_imageset.png]]

To create a new image, press tool bar button second from the right, or click with the right mouse button on the image itself and select '''Create image''':

[[Image:Ceed_imageset_create_image.png]]

It creates a 50 x 50 rectangle centered at where mouse cursor is. Move and resize it as you see fit.

== Settings ==
Go to '''Edit -> Application settings'''.

[[Image:Ceed_application_settings.png]]

There are many settings you can tweak. One of the most important might be '''Shortcuts'''. It allows you to assign shortcuts to zoom, image creation, opening a project, and so on.

== Notes ==

Currently you may have problems with Imagesets that use TGA, since some versions of Qt may be built without TGA support. CEGUI 0.8 has all imagery as PNG (CEGUI 0.7 used TGA), and we advise you to use PNG instead of TGA.

The Beginners Guide to Falagard skinning - Part II

2011-12-11T23:30:58Z

Pav: /* Imagery */ Fix doc link

{{VersionBadge|0.4}}
{{Series|The Beginners Guide to Falagard|2}}

== 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 [http://www.cegui.org.uk/docs/current/fal_wr_ref.html Falagard Window Renderer Requirements].

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:

<source lang="xml">
<?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>
</source>

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

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 [http://www.cegui.org.uk/docs/current/fal_enum_ref.html Falagard XML Enumeration 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:

<source lang="xml">
<?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>
</source>

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:

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

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:

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

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

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

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.

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

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:

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

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:

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

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

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

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.

<source lang="xml">
<?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>
</source>

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.

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

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.

<source lang="xml">
<?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>
</source>

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:

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

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

<source lang="xml">
<?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>
<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>
<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">
<Layer>
<Section section="selection" />
</Layer>
</StateImagery>
<StateImagery name="InactiveSelection">
<Layer>
<Section section="selection">
<Colours topLeft="7FFFFFFF" topRight="7FFFFFFF" bottomLeft="7FFFFFFF" bottomRight="7FFFFFFF" />
</Section>
</Layer>
</StateImagery>
</Falagard>
</source>

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]] 00:41, 14 Dec 2005 (CET)

[[Category:Tutorials]]

The Beginners Guide to Falagard skinning - Part II

2011-12-11T23:28:43Z

Pav: /* Requirements */ Fix doc link

{{VersionBadge|0.4}}
{{Series|The Beginners Guide to Falagard|2}}

== 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 [http://www.cegui.org.uk/docs/current/fal_wr_ref.html Falagard Window Renderer Requirements].

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:

<source lang="xml">
<?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>
</source>

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

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:

<source lang="xml">
<?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>
</source>

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:

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

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:

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

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

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

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.

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

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:

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

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:

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

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

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

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.

<source lang="xml">
<?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>
</source>

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.

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

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.

<source lang="xml">
<?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>
</source>

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:

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

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

<source lang="xml">
<?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>
<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>
<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">
<Layer>
<Section section="selection" />
</Layer>
</StateImagery>
<StateImagery name="InactiveSelection">
<Layer>
<Section section="selection">
<Colours topLeft="7FFFFFFF" topRight="7FFFFFFF" bottomLeft="7FFFFFFF" bottomRight="7FFFFFFF" />
</Section>
</Layer>
</StateImagery>
</Falagard>
</source>

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]] 00:41, 14 Dec 2005 (CET)

[[Category:Tutorials]]

The Beginners Guide to Falagard skinning - Part I

2011-12-11T23:26:01Z

Pav: /* Label */ Fix doc link

{{VersionBadge|0.4}}
{{Series|The Beginners Guide to Falagard|1}}

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

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

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 and in the documentation directory in the SDK as a PDF.

The online version is available on the page [http://www.cegui.org.uk/docs/current/fal_man.html Falagard skinning system for CEGUI]. For the list of these requirements I'm talking about the [http://www.cegui.org.uk/docs/current/fal_wr_ref.html Falagard Window Renderer Requirements] 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:

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

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.

<source lang="xml">
<?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>
</source>

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.

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

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:

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

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.

<source lang="xml">
<?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>
</source>

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

<source lang="xml">
<Image imageset="MyImages" image="ButtonBG" />
</source>

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

<source lang="xml">
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</source>

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.

<source lang="xml">
<?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>
</source>

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.

<source lang="xml">
<ImagerySection name="label">
<TextComponent>
</TextComponent>
</ImagerySection>
</source>

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

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

We added the same area as in the "bg" ''ImagerySection'', and added the formattings we wanted. Take a look at [http://www.cegui.org.uk/docs/current/fal_enum_ref.html Falagard XML Enumeration 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:

<source lang="xml">
<?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>
</source>

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:

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

* ''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:

<source lang="xml">
<Section name="label">
<ColourProperty name="NormalTextColour" />
</Section>
</source>

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:

<source lang="xml">
<?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>
</source>

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]] 06:10, 6 Dec 2005 (CET)

[[Category:Tutorials]]

Animation System

2011-12-10T15:41:06Z

Pav: /* Via Falagard looknfeel XML */ Add colour animation example

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.2}}

== Prerequisites ==
'''You have to inject time pulses (see System::injectTimePulse), otherwise CEGUI has no idea time is passing and the animations will always be stuck at the position they started at.'''

== Basic concepts ==
In UI lots of animations are likely to be shared (for example widget specific animation), so CEGUI splits the animation between definition and instance. You can have one animation definition animating large amount of Windows, having only one animation per window is also fine (one animation with only one instance). Animation definitions aren't tied to window type, the only condition is that the target must have all affected (target properties of all affectors inside the animation) and source properties (all source properties in key frames, if any).

== Purpose of animation classes ==

=== Animation Definition (class {{DoxygenClass|Animation|0.7}}) ===
This class holds defining data for animations. Specifically duration, replay mode, auto start and list of Affectors. This class doesn't directly animate anything. You have to instantiate it via CEGUI::AnimationManager::instantiateAnimation.

=== Affector (class {{DoxygenClass|Affector|0.7}}) ===
Affector affects (changes the value of) one property. It holds application method (more about that later), target property, used interpolator and list of key frames.

=== Key Frame (class {{DoxygenClass|KeyFrame|0.7}}) ===
Key frame represents the value of affected property at given time position. It holds value, source property and time position. Key frames can use values of properties of the affected window. If source property is not empty, property is saved when animation starts and used as value for this key frame.

=== Animation Instance (class {{DoxygenClass|AnimationInstance|0.7}}) ===
This class uses animation definition to animate Window. It holds animation position and playback speed.

=== Animation Manager (class {{DoxygenClass|AnimationManager|0.7}}) ===
Singleton class. You use it to create new animation definitions and instantiate existing animation definitions. (You should not construct Animation definitions or Animation instances directly, always use Animation Manager).

=== Interpolator (class {{DoxygenClass|Interpolator|0.7}}) ===
To be able to animate smoothly between 2 discrete keyframes, interpolators had to be introduced. You don't have to use them directly, everything is done for you in the animation classes. You only need to understand their internals if you need custom interpolator (as all basic interpolators are included in CEGUI, if you find some property that can't be animated with stock interpolators, let us know).

== Defining animations ==

=== Via code ===
This sample animation takes 0.3 seconds and in that time, it fades the window and rotates it 10 degrees around Y axis.
<source lang="cpp">
{
CEGUI::Animation* anim = CEGUI::AnimationManager::getSingleton().createAnimation("Testing");
anim->setDuration(0.3f); // duration in seconds
anim->setReplayMode(CEGUI::Animation::RM_Once); // when this animation is started, only play it once, then stop

// now we define affector inside our Testing animation
{
// this affector changes YRotation and interpolates keyframes with float interpolator
CEGUI::Affector* affector = anim->createAffector("YRotation", "float");
// at 0.0 seconds, the animation should set YRotation to 10.0 degrees
affector->createKeyFrame(0.0f, "0.0");
// at 0.3 seconds, YRotation should be 0 degrees and animation should progress towards this in an accelerating manner
affector->createKeyFrame(0.3f, "10.0", CEGUI::KeyFrame::P_QuadraticAccelerating);
}

// animation can have more than one affectors! lets define another affector that changes Alpha
{
// this affector will again use float interpolator
CEGUI::Affector* affector = anim->createAffector("Alpha", "float");
affector->createKeyFrame(0.0f, "1.0"); // at 0.0 seconds, set alpha to 0.5
affector->createKeyFrame(0.3f, "0.5", CEGUI::KeyFrame::P_QuadraticDecelerating); // at 1.0 seconds, set alpha to 1.0, now decelerating!
}
}
</source>

=== Via [[Falagard]] looknfeel XML ===
<source lang="xml">
<WidgetLook ...>
...
<AnimationDefinition name="Testing" duration="0.3" replayMode="once">
<Affector property="Alpha" interpolator="float">
<KeyFrame position="0.0" value="1.0" />
<KeyFrame position="0.3" value="0.5" />
</Affector>
<Affector property="YRotation" interpolator="float">
<KeyFrame position="0.0" value="0" />
<KeyFrame position="0.3" value="10" />
</Affector>
</AnimationDefinition>
</WidgetLook>
</source>

Animating colours example, with [http://www.cegui.org.uk/docs/current/xml_animation.html#xml_animation_keyframe KeyFrame sourceProperty] and the colour [http://www.cegui.org.uk/docs/current/xml_animation.html#xml_animation_affector interpolator]:
<source lang="xml">
<AnimationDefinition name="NormalToHover" duration="0.2" replayMode="once">
<Affector property="CurrentColour" interpolator="colour">
<KeyFrame position="0.0" sourceProperty="NormalColour" />
<KeyFrame position="0.2" sourceProperty="HoverColour" />
</Affector>
</AnimationDefinition>
</source>

=== Via separate animation list XML (AnimationManager::loadAnimationsFromXML) ===
<source lang="xml">
<Animations>
<AnimationDefinition name="Testing" duration="0.3" replayMode="once">
<Affector property="Alpha" interpolator="float">
<KeyFrame position="0.0" value="1.0" />
<KeyFrame position="0.3" value="0.5" />
</Affector>
<Affector property="YRotation" interpolator="float">
<KeyFrame position="0.0" value="0" />
<KeyFrame position="0.3" value="10" />
</Affector>
</AnimationDefinition>
</Animations>
</source>

== Instantiating animations ==
If you created the animation in code or via separate animation definition file, you have to instantiate it (only [[Falagard]] instantiates and sets target automatically).

<source lang="cpp">
CEGUI::AnimationInstance* instance = CEGUI::AnimationManager::getSingleton().instantiateAnimation(anim);
// after we instantiate the animation, we have to set its target window
instance->setTargetWindow(targetWindow);

// at this point, you can start this instance and see the results
instance->start();
</source>

== Connecting events and animations ==
You often want your animation to start when something happens (Mouse gets over the widget, new FrameWindow is opened, etc). You have two options to achieve this.

If you already are using XML to define animations, the easiest solution is to use the auto event subscription facility. You add pairs of Event name and action that should happen with the animation ("Start", "Stop", "Pause", "Unpause", etc.) and when target window is set, these subscriptions are automatically made for your convenienve.

Both [[Falagard]] and Animations.xml approaches are the same with regards to this. This XML snippet starts the animation when mouse enters the target window's area.
<source lang="xml">
<AnimationDefinition name="Testing" duration="0.3" replayMode="once">
...
<Subscription event="MouseEntersArea" action="Start" />
</AnimationDefinition>
</source>

Doing this in code is much more powerful (you can subscribe to a window that's different than target window) but also more messy:
<source lang="cpp">
windowWithEvent->subscribeEvent(CEGUI::Window::EventMouseEntersArea, CEGUI::Event::Subscriber(&CEGUI::AnimationInstance::handleStart, instance));
</source>

You can also do this from a Lua script:
<source lang="lua">
CEGUI.WindowManager:getSingleton():getWindow("WindowName"):subscribeEvent("MouseEnter", "luafunctionname")
</source>
This code sets up the window specified in WindowName, the name of that window on creation or from the XML "Name" property, to react to the mouse entering it by calling the Lua function specified in luafunctionname. The Lua function name argument should be the name, without trailing (), to a function declared in Lua or exported to Lua from C.

== Progression ==
As I created the implementation, I noticed that linear animations look really boring and predictable. Often times accelerating or decelerating anims will look much better and lively. To make creating those easier, I introduced progression to key frames. This enum tells the system how to progress towards the key frame that holds the progression (that means progression on the first key frame is never used!). The default is linear, meaning that progress towards the keyframe is completely linear. Try the other options yourself to see the differences.
=== animations.xml example ===
Here we have edited the example animation so that the alpha value uses the quadratic deceleration progression. This will make the alpha value drop quickly in the first frames but the speed of the change will decrease quickly and give a smooth finish to the transition.
<source lang="xml">
<Animations>
<AnimationDefinition name="Testing" duration="0.3" replayMode="once">
<Affector property="Alpha" interpolator="float">
<KeyFrame position="0.0" value="1.0" />
<KeyFrame position="0.3" value="0.5" progression="quadratic decelerating" />
</Affector>
<Affector property="YRotation" interpolator="float">
<KeyFrame position="0.0" value="0" />
<KeyFrame position="0.3" value="10" />
</Affector>
</AnimationDefinition>
</Animations>
</source>
Possible values for this property, in XML, are:
* "linear": (default value) Simple linear transition. Same rate of progression for every frame.
* "discrete": Abrupt progression, goes from one value straight to the next one.
* "quadratic accelerating": Starts slow but accelerates to very fast towards the end.
* "quadratic decelerating": Starts very fast but comes smoothly to a halt in the end.

== Application methods ==
Affectors offer 3 different "application methods". One is absolute, meaning that the keyframe value is taken as absolute and is directly set to the property after interpolation. The other 2 are relative. That means that when the animation starts, the old values of properties are saved and later used when animating. AM_Relative means saved_value + interpolated_value, AM_RelativeMultiply means saved_value * interpolated_float.

=== animations.xml example: ===
In the following example we have changed the rotation affector to do relative rotation instead of absolute, which is default. This means that whatever rotation the window had when the animation started it will add the new rotation to that value. The absolute method would have reset the rotation to 0 in the first key frame and then proceeded to rotate it by 10 degrees during 0.3 seconds.
<source lang="xml">
<Animations>
<AnimationDefinition name="Testing" duration="0.3" replayMode="once">
<Affector property="Alpha" interpolator="float">
<KeyFrame position="0.0" value="1.0" />
<KeyFrame position="0.3" value="0.5" />
</Affector>
<Affector property="YRotation" interpolator="float" applicationMethod="relative">
<KeyFrame position="0.0" value="0" />
<KeyFrame position="0.3" value="10" />
</Affector>
</AnimationDefinition>
</Animations>
</source>
Possible values for this property, in XML, are:
* "absolute": (default setting) The interpolated value is set as the new property value.
* "relative": The interpolated value is added to the starting value of the property.
* "relative multiply": The interpolated value is multiplied with the starting value of the property.

[[Category:Manuals]]

User:Pav

2011-12-10T15:31:23Z

Pav: Created page with "New here, trying to improve docs while learning about CEGUI (before everything seems obvious and I forget about it)."

New here, trying to improve docs while learning about CEGUI (before everything seems obvious and I forget about it).

Talk:"Falagard" Skinning System Documentation

2011-12-10T15:27:00Z

Pav: Created page with "Delete? ~~~~"

Delete? [[User:Pav|Pav]] 15:27, 10 December 2011 (UTC)