Difference between revisions of "FAQ"

Revision as of 06:45, 5 August 2006

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.

What is the situation with the Falagard components and the Creative Commons license?

There is no situation! The Creative Commons license only applies to the documentation where that notice appears; the source code, libraries, and all other materials relating to the Falagard skinning system are licensed under LGPL or MIT (depending upon the version; see above).

Why is the Falagard documentation licensed seperately? Why is it not LGPL/MIT like the rest of the library?

Originally that documentation was only to be available as a PDF file intended for self-printing into a mini-book, and the "this work" portion of the license notification applies to the text of that book; the documentation is considered a seperate work from the code / library itself, and so it licensed seperately.

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:

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

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://ceguisharp.sourceforge.net/ This is a C# port of the library which will support Managed Direct 3D, OpenGL, as well as higher-level engines such as 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));
    }
    
    bool MyButtonHandler::ButtonClicked(const EventArgs&)
    {
        //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 (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.