Difference between revisions of "FAQ"

Revision as of 17:27, 20 May 2006

General Questions

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.

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.

Starting from the 0.5 release CEGUI will be licensed under the MIT license

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. Since CEGUI 0.4 is licensed under LGPL, this means that can't I use the library, right?

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.

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

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?

Use the 0.5 release as the MIT license allows static linking.

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.

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.

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.

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.

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.

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.

Build Questions

(A work in Progress)

Building CEGUI

1. General Requirements
2. 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

For full details, please refer to this seperate wiki page: http://www.cegui.org.uk/wiki/index.php/The_%22official%22_layout_editor

1. Dependency installs (for versions > 0.4.0)

Install wxWidgets

1. Building

Usage Questions

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.

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

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.