Difference between revisions of "FAQ"

From CEGUI Wiki - Crazy Eddie's GUI System (Open Source)
Jump to: navigation, search
(Re-organized / updated this page.)
Line 1: Line 1:
 
== General Questions ==
 
== General Questions ==
 
=== What is CEGUI? ===
 
=== What is CEGUI? ===
CEGUI is ''Crazy Eddie's Gui System''; a cross platform Gui/widget library for use in games and other multi-media projects where use of standard operating system Gui libraries is either not possible, or is very difficult.
+
CEGUI stands for ''Crazy Eddie's Gui System''; a free library providing windowing and widgets for graphics APIs / engines where such functionality is not natively available, or severely lacking. The library is object orientated, written in C++, and targeted at games developers who should be spending their time creating great games, not building GUI sub-systems!
 +
 
 +
CEGUI is used as the GUI of choice in the [http://www.ogre3d.org Ogre3D project] but supports Microsoft® DirectX® 8.1 and 9, OpenGL, and the Irrlicht engine natively.
 +
 
 +
CEGUI was started by Paul Turner ("[[User:CrazyEddie|CrazyEddie]]") about two years ago and is currently in it's second major revision, "Mk2". The project supports windows, linux and MacOS.
  
 
=== How is CEGUI licensed? ===
 
=== How is CEGUI licensed? ===
CEGUI is licensed under the LGPL (Lesser/Library General Public License). For details of this license, please visit the following web-site: http://www.gnu.org/copyleft/lesser.html.
+
Up and until version 0.4.1, CEGUI '''is''' licenced under [http://www.gnu.org/licenses/lgpl.html LGPL], which basically means you can dynamically link to it (ie. use it as a library) in a non-GPL project, as long as you fulfil the other requirements of the LGPL.
  
Starting from the 0.5 release CEGUI will be licensed under the [http://www.opensource.org/licenses/mit-license.php MIT license]
+
However, as from 0.5 (not officially released yet), the library will be released under the [http://www.opensource.org/licenses/mit-license.php MIT] licence, which is less restrictive then LGPL. You may for example statically link to libraries. The main reason for this switch is the fact that the Ogre3D project has started to provide dual licensing to allow console development. And in order to keep CEGUI as their preferred GUI system, we have switched as well.
  
 
=== How much does CEGUI cost? ===
 
=== How much does CEGUI cost? ===
 
Nothing. The use of CEGUI is totally free within the bounds of the license as described above.
 
Nothing. The use of CEGUI is totally free within the bounds of the license as described above.
  
=== I am developing a commercial, closed-source product. Since CEGUI 0.4 is licensed under LGPL, this means that can't I use the library, right? ===
+
=== I am developing a commercial, closed-source product. Should i use the 0.4 or 0.5 version of the library? ===
No, that's not right. So long as you link dynamically to CEGUI and associated libraries, then you do not have to release any of your own source or .o/.obj files, though do carefully check the LGPL, and the licenses for the third party libraries for full details of what is and is not permissible.
+
When you are creating a product for PC, where it is possible for users to update any of your used third-party DLL's (a requirement for LGPL), you can choose both versions. However if you are shipping a product on a read-only device, such as a console DVD, you must use 0.5 or higher, because the MIT license does not require that users can update anything.
  
=== I am not happy with the LGPL / MIT license, do you offer alternative licensing? ===
+
However before deciding, do always carefully check the mentioned licenses to make sure that your project doesn't do something uncommon.
No. Alternative licensing is not available, nor is it planned.
+
  
=== And what if I need to develop to a plataform wich doesn´t support dynamic linking? ===
+
=== I am not happy with the LGPL / MIT license, do you offer alternative licensing? ===
Use the 0.5 release as the MIT license allows static linking.
+
No. Alternative licensing is not available, nor is it planned. But you won't find anything much less restrictive then the MIT license.
  
 
=== Does CEGUI rely upon any third party libraries? If so what are they? ===
 
=== Does CEGUI rely upon any third party libraries? If so what are they? ===
Line 34: Line 37:
  
 
=== Do I have to compile the third part libraries myself? ===
 
=== Do I have to compile the third part libraries myself? ===
It depends. Under Linux and similar systems, you will need to perform your own compilation. For Microsoft® Windows® users, we have supplied packages containing binary versions of the libraries for a selection of popular compiler configurations.
+
It depends. Under Linux and similar systems, you will need to perform your own compilation. For Microsoft® Windows® users, we have supplied packages containing binary versions of the libraries for a selection of popular compiler configurations. See the "Current Releases" on the home page.
  
 
=== You mentioned something about "supported rendering systems", what's that all about and which systems are supported? ===
 
=== You mentioned something about "supported rendering systems", what's that all about and which systems are supported? ===
Line 66: Line 69:
  
 
=== I am having major troubles integrating CEGUI with my project, will you do it for me? ===
 
=== I am having major troubles integrating CEGUI with my project, will you do it for me? ===
No. The CEGUI developers have enough to do without writing users projects for them.
+
No. The CEGUI developers have enough to do without writing users projects for them. Follow the Howto's and Tutorials from the home page.
  
 
=== I have (or think I have) found a bug. How should I proceed? ===
 
=== I have (or think I have) found a bug. How should I proceed? ===
If you are certain that it's a bug and not, for example, a misunderstanding of what is happening, then the bug should be reported via the project bug tracking system. However, before submitting a bug to the tracker, it is asked that you first do a quick search to see if the bug has already been reported. If you are unsure whether something is a bug or not, then it may be discussed on the web site forums prior to submitting a bug report to the project bug tracker.
+
If you are certain that it's a bug and not, for example, a misunderstanding of what is happening, then the bug should be reported via the [http://www.cegui.org.uk/mantis/index.php | Mantis Tracker] However, before submitting a bug to the tracker, it is asked that you first do a quick search to see if the bug has already been reported. If you are unsure whether something is a bug or not, then it may be discussed on the web site forums prior to submitting a bug report to the project bug tracker.
  
 
=== I notice that feature/widget 'X' is missing. Will this be added to CEGUI? ===
 
=== I notice that feature/widget 'X' is missing. Will this be added to CEGUI? ===
Requests for new features and/or widgets are welcomed. You can discuss such things on the web site forums and then submit a feature request to the project feature request tracking system. Although it is asked that you first search to ensure that the feature has not already been requested; if the feature has already been requested feel free to add a note to the tracker item stating your support for the feature request. Note that no promises are made with regards to which features will and will not be added, or how long such things will take, but all requests will be seriously considered.
+
Requests for new features and/or widgets are welcomed in this forum: http://www.cegui.org.uk/phpBB2/viewforum.php?f=3&sid=587eedf3463c00490686f8cddc61a257
 +
This is the best way because most people will read it, including the team. This helps others to give input as well, which migth result in clearly defined requests.
 +
 
 +
Note that no promises are made with regards to which features will and will not be added, or how long such things will take, but all requests will be seriously considered.
  
 
=== How can I get involved with CEGUI development? ===
 
=== How can I get involved with CEGUI development? ===
The best way to become involved is to visit the web site forums, state what your intentions are (to help in avoiding duplicated effort), and then start submitting some patches to the project patch tracking system.
+
Each new member gets added by invitation by the current team. Most probably because that person has contributed some valuable patches, or is of great help in the forums. It will of course depend on the current state of the project to know which positions are required.
 +
 
 +
So the best way to become involved is to show your face at the web site forums, the irc channel, and state what your intentions are (to help in avoiding duplicated effort), thereby becoming a constructive individual for CEGUI and its community. And some patches are a huge pro!
  
 
=== Is there managed code / Microsoft .Net support for the CEGUI library? ===
 
=== Is there managed code / Microsoft .Net support for the CEGUI library? ===
Line 83: Line 91:
 
Feel free to post your question on the web site forums, somebody will gladly answer your question and/or offer further advice.
 
Feel free to post your question on the web site forums, somebody will gladly answer your question and/or offer further advice.
  
== Build Questions ==
+
== Building CEGUI ==
 
+
(A work in Progress)
+
 
+
=== Building CEGUI ===
+
# General Requirements
+
# Dependency installs
+
 
+
=== Building from CVS ===
+
''(The following instructions are for unix systems)''
+
 
+
==== Configuring CEGUI ====
+
First, we need to generate the configure script, as well as a few other files.
+
In the cegui_mk2 directory, run:
+
    $ sh ./bootstrap
+
Now, it's time to actually run configure:
+
    $ ./configure
+
 
+
==== Building CEGUI ====
+
With all this one, we can now build CEGUI.
+
Type:
+
    $ make
+
Once that's finished, we can install it!
+
Type:
+
    $ make install
+
 
+
Tada!
+
  
=== CEGUI Layout Editor Build ===
+
This section has moved to [http://www.cegui.org.uk/wiki/index.php/HOWTO:_Obtain_the_library_source_from_subversion New location]
For full details, please refer to this seperate wiki page: http://www.cegui.org.uk/wiki/index.php/The_%22official%22_layout_editor
+
# Dependency installs (for versions > 0.4.0)
+
Install wxWidgets
+
# Building
+
  
 
== Usage Questions ==
 
== Usage Questions ==
 +
''(This whole section should be moved to a Tutorial or a Howto).''
 
=== What is the correct way to subscribe for an event? ===
 
=== What is the correct way to subscribe for an event? ===
 
Event notification is a vital aspect of GUI programming. CEGUI handles those using subscribers.
 
Event notification is a vital aspect of GUI programming. CEGUI handles those using subscribers.
Line 186: Line 165:
 
  myStaticImage->setImage("BackdropImageset", "Backdrop");
 
  myStaticImage->setImage("BackdropImageset", "Backdrop");
 
Notice that the names we specify here are the ones that were originally specified in the imageset XML file.<br>
 
Notice that the names we specify here are the ones that were originally specified in the imageset XML file.<br>
 +
 +
=== I can't see the items I've added to my Combobox, how do I get the list to show when I press the button? ===
 +
The height you specify for the combobox widget includes the height of the drop down list; it's not just for the 'Editbox' portion of the widget (the height of which  is usually automatically determined based upon the font).  Ensure that when specifying the height for your combobox, you have provided sufficient space for the list to appear.
  
 
=== What properties are available for use in XML layouts, and what format do I use for the value strings? ===
 
=== What properties are available for use in XML layouts, and what format do I use for the value strings? ===
Each widget has its properties placed within an appropriately named C++ namespace, so all you need to do is look up the appropriate namespace within the [http://www.cegui.org.uk/api_reference/namespaces.html namespaces section of the API reference].
+
If you start at the documentation for the base Property class (http://www.cegui.org.uk/api_reference/classCEGUI_1_1Property.html Property base), you will get an inheritance diagram showing all properties in the system. When you click one, you'll get its page. Each page has a description of the format in which you should provide its value.
  
Also, remember that properties are inherited.  So for example, when looking up properties for a PushButton, also check the properties for ButtonBase and Window too - since these properties are also available to you.
+
Besides, as an overview, each widget has its properties placed within an appropriately named C++ namespace within the [http://www.cegui.org.uk/api_reference/namespaces.html namespaces section of the API reference].
  
=== I can't see the items I've added to my Combobox, how do I get the list to show when I press the button? ===
+
Also, remember that properties are inheritedSo for example, when looking up properties for a PushButton, also check the properties for ButtonBase and Window too - since these properties are also available to you.
 
+
The height you specify for the combobox widget includes the height of the drop down list; it's not just for the 'Editbox' portion of the widget (the height of which  is usually automatically determined based upon the font)Ensure that when specifying the height for your combobox, you have provided sufficient space for the list to appear.
+

Revision as of 11:30, 25 May 2006

Contents

General Questions

What is CEGUI?

CEGUI stands for Crazy Eddie's Gui System; a free library providing windowing and widgets for graphics APIs / engines where such functionality is not natively available, or severely lacking. The library is object orientated, written in C++, and targeted at games developers who should be spending their time creating great games, not building GUI sub-systems!

CEGUI is used as the GUI of choice in the Ogre3D project but supports Microsoft® DirectX® 8.1 and 9, OpenGL, and the Irrlicht engine natively.

CEGUI was started by Paul Turner ("CrazyEddie") about two years ago and is currently in it's second major revision, "Mk2". The project supports windows, linux and MacOS.

How is CEGUI licensed?

Up and until version 0.4.1, CEGUI is licenced under LGPL, which basically means you can dynamically link to it (ie. use it as a library) in a non-GPL project, as long as you fulfil the other requirements of the LGPL.

However, as from 0.5 (not officially released yet), the library will be released under the MIT licence, which is less restrictive then LGPL. You may for example statically link to libraries. The main reason for this switch is the fact that the Ogre3D project has started to provide dual licensing to allow console development. And in order to keep CEGUI as their preferred GUI system, we have switched as well.

How much does CEGUI cost?

Nothing. The use of CEGUI is totally free within the bounds of the license as described above.

I am developing a commercial, closed-source product. Should i use the 0.4 or 0.5 version of the library?

When you are creating a product for PC, where it is possible for users to update any of your used third-party DLL's (a requirement for LGPL), you can choose both versions. However if you are shipping a product on a read-only device, such as a console DVD, you must use 0.5 or higher, because the MIT license does not require that users can update anything.

However before deciding, do always carefully check the mentioned licenses to make sure that your project doesn't do something uncommon.

I am not happy with the LGPL / MIT license, do you offer alternative licensing?

No. Alternative licensing is not available, nor is it planned. But you won't find anything much less restrictive then the MIT license.

Does CEGUI rely upon any third party libraries? If so what are they?

CEGUI currently depends upon the following external libraries:

   * FreeType2
   * Xerces-C++ (optional, built-in TinyXML parser is provided)

You will also require a supported rendering system, and some form of input library.

Where can I get these third party libraries?

   * FreeType2: http://www.freetype.org/
   * Xerces-C++: http://xml.apache.org/xerces-c/

Do I have to compile the third part libraries myself?

It depends. Under Linux and similar systems, you will need to perform your own compilation. For Microsoft® Windows® users, we have supplied packages containing binary versions of the libraries for a selection of popular compiler configurations. See the "Current Releases" on the home page.

You mentioned something about "supported rendering systems", what's that all about and which systems are supported?

CEGUI can be used with various rendering systems. There are currently CEGUI renderer modules for Microsoft® DirectX® 8.1 and 9, OpenGL, the Ogre engine, and the Irrlicht engine.

There is no renderer module for my rendering engine or API of choice, will other rendering system be supported?

It is likely that, over time, CEGUI will add support for other APIs and engines. Having said this, it is fairly simple to write your own renderer module for CEGUI, so you might consider taking that option if you do not want to wait.

And what about input libraries?

CEGUI requires you to inject inputs into it, these inputs can come from any source that you choose. All you need to do is pass mouse movements, mouse button up and down events, and keyboard inputs to CEGUI.

Why doesn't CEGUI collect its own inputs? Why do I need to inject the inputs myself?

CEGUI does not collect its own input so that the system can remain as flexible as possible. We didn't want to tie people down to one system or input library.

I have seen mention of a Lua scripting module, how can I get this?

The Lua scripting module is provided with CEGUI and resides in the same source repository. Downloading CEGUI binary/source/svn will get you everything you need.

I can't find many of the things you talk about in my crayzedsgui code, what's wrong?

You probably have one of the older Mk-1 alpha releases. Get the newer Mk-2 releases instead, the archive files for these generally have names with cegui_mk2 in them.

Why are there two versions of the system?

The Mk-1 version was a Windows®/DirectX® only library and was really a dry run for what became the Mk-2 system. There was only ever 'alpha' versions of the Mk-1 code, so it was never anywhere near finished.

Are the Mk-1 and Mk-2 systems interface compatible?

No. The interfaces of the two systems are totally different, although many of the general concepts have remained the same.

The Mk-1 system is so much more lightweight than the Mk-2 system. Can I still use the Mk-1 code? Is the Mk-1 code still being developed and supported?

Short Answer: Not really.

Long Answer: There were too many weak areas within the Mk-1 system and development on this version has ceased completely. There is no longer any support for the Mk-1 version; in general it would be better for everyone if they migrated to the Mk-2 version of the system.

I am having major troubles integrating CEGUI with my project, will you do it for me?

No. The CEGUI developers have enough to do without writing users projects for them. Follow the Howto's and Tutorials from the home page.

I have (or think I have) found a bug. How should I proceed?

If you are certain that it's a bug and not, for example, a misunderstanding of what is happening, then the bug should be reported via the | Mantis Tracker However, before submitting a bug to the tracker, it is asked that you first do a quick search to see if the bug has already been reported. If you are unsure whether something is a bug or not, then it may be discussed on the web site forums prior to submitting a bug report to the project bug tracker.

I notice that feature/widget 'X' is missing. Will this be added to CEGUI?

Requests for new features and/or widgets are welcomed in this forum: http://www.cegui.org.uk/phpBB2/viewforum.php?f=3&sid=587eedf3463c00490686f8cddc61a257 This is the best way because most people will read it, including the team. This helps others to give input as well, which migth result in clearly defined requests.

Note that no promises are made with regards to which features will and will not be added, or how long such things will take, but all requests will be seriously considered.

How can I get involved with CEGUI development?

Each new member gets added by invitation by the current team. Most probably because that person has contributed some valuable patches, or is of great help in the forums. It will of course depend on the current state of the project to know which positions are required.

So the best way to become involved is to show your face at the web site forums, the irc channel, and state what your intentions are (to help in avoiding duplicated effort), thereby becoming a constructive individual for CEGUI and its community. And some patches are a huge pro!

Is there managed code / Microsoft .Net support for the CEGUI library?

Yes, there is ceguisharp at http://realmforgewiki.castlegobs.nl/index.php/CEGUI This is a C# port of the library which uses the excellent Axiom rendering engine.

This FAQ doesn't answer my question, what should I do now?

Feel free to post your question on the web site forums, somebody will gladly answer your question and/or offer further advice.

Building CEGUI

This section has moved to New location

Usage Questions

(This whole section should be moved to a Tutorial or a Howto).

What is the correct way to subscribe for an event?

Event notification is a vital aspect of GUI programming. CEGUI handles those using subscribers. In order to subscribe a window for an event, you have to call the method 'Window::subscribeEvent', passing the function to be called when the specified event occurs, and the instance on which the method is called.

class MyButtonHandler
{
private:
    PushButton* mButton;

public:
    MyButtonHandler::MyButtonHandler(PushButton* btn) : mButton(btn)
    {
        btn->subscribeEvent(PushButton::EventClicked, Event::Subscriber(MyButtonHandler::ButtonClicked,this));
    }
    
    MyButtonHandler::ButtonClicked()
    {
        //This function gets called when the button is clicked
        std::cout << "Button clicked" << std::endl;
    }

The 'subscribeEvent' method returns an Event::Connection, which can be used later to unsubscribe for a registered event with the 'disconnect' method.

Event::Connection myCon = btn->subscribeEvent(...);

...

myCon->disconnect();

In order to totally remove the event itself, you have to call the 'removeEvent' function: all the connections to the specified event will be disconnected. There's also an Event::ScopedConnection, which can be used to auto-unsubscribe when the event goes out of scope.

Similar way for the scripted events, which can be subscribed with the 'subscribeScriptedEvent' method. In addition, you can do it in XML, using this syntax:

<Event Name="Clicked" Function="luabtn_clicked" />

How can I make the ListBox highlight the selected item?

In order to highlight selected items you need to set selection brush image and the selection colours of that item. The selection image is modulated by the colours you set. Note, that the alpha component needs to be smaller than 1.0, for the content of the selected item to be seen.

// set selection highlight to a half transparent blue to red gradient.
colour blue(0.0, 0.0, 1.0, 0.5);
colour red(1.0, 0.0, 0.0, 0.5);
myListBoxItem->setSelectionColours(blue, blue, red, red);
// this default image is a simple white rectangle
myListBoxItem->setSelectionBrushImage("TaharezLook", "ListboxSelectionBrush");

How can I remove the border of a StaticImage?

Either put the following property into the window definition:

<Property Name="FrameEnabled" Value="false" />

Or set it by code:

myStaticImage->setFrameEnabled(false);

How can I set the background of a StaticImage?

The first thing you need in order to do this is an Imageset that defines the Image that you wish to use. When wanting to use an image file for this as you suggest, you basically have an imageset defined like this:

<?xml version="1.0" ?>
<Imageset Name="BackdropImageset" Imagefile="backdrop.tga" NativeHorzRes="1024" NativeVertRes="768" AutoScaled="true">
	<Image Name="Backdrop" XPos="0" YPos="0" Width="1024" Height="768" />
</Imageset>

What this does is define an Imageset using the backdrop.tga. A single image "Backdrop" is defined that starts at location (0,0) and is 1024 x 768 in size. You should be careful in that the source image file should have dimensions that are powers of two - this is because the image is loaded as a texture, and may be stretched if the powers-of-two requirement is not observed.
Once you have your imageset defined, you can load it either by adding a reference to it in whichever scheme you are loading, or manually using the ImagesetManager:

CEGUI::ImagesetManager::getSingleton().createImageset("myImageset.imagset");

Once the thing is loaded, you set the image into the StaticImage like so:

myStaticImage->setImage("BackdropImageset", "Backdrop");

Notice that the names we specify here are the ones that were originally specified in the imageset XML file.

I can't see the items I've added to my Combobox, how do I get the list to show when I press the button?

The height you specify for the combobox widget includes the height of the drop down list; it's not just for the 'Editbox' portion of the widget (the height of which is usually automatically determined based upon the font). Ensure that when specifying the height for your combobox, you have provided sufficient space for the list to appear.

What properties are available for use in XML layouts, and what format do I use for the value strings?

If you start at the documentation for the base Property class (http://www.cegui.org.uk/api_reference/classCEGUI_1_1Property.html Property base), you will get an inheritance diagram showing all properties in the system. When you click one, you'll get its page. Each page has a description of the format in which you should provide its value.

Besides, as an overview, each widget has its properties placed within an appropriately named C++ namespace within the namespaces section of the API reference.

Also, remember that properties are inherited. So for example, when looking up properties for a PushButton, also check the properties for ButtonBase and Window too - since these properties are also available to you.