4.19 CEGUI Introduction

Written by Seth Yastrov, syastrov@users.sourceforge.net and Dan Härdfeldt, swedishcoder@users.sourceforge.net.

The CEGUI Plugin

The CEGUI plugin is a wrapper around CEGUI, an embeddable widget library, so it can be easily used from within Crystal Space applications. The plugin provides a renderer, a VFS resource provider, and an event handler for CEGUI. You will need version 0.4.1 or 0.5.0 of CEGUI.

http://www.cegui.org.uk/

Initialization

All components of the CEGUI plugin are set up when the application calls iCEGUI::Initialize(). This function will initialize CEGUI and tell it to use the CEGUI plugin renderer and event handler. It is not necessary to create a new CEGUI::System() in your application as this is performed automatically by the Crystal Space CEGUI plugin.

Renderer

To render the graphical user interface (GUI), use convenience function, iCEGUI::Render(). This function may be called from anywhere in the application to allow the ability to render to an alternate render target (like procedural textures). In applications based upon ‘csBaseEventHandler’, it is called typically in ProcessFrame(), sandwiched somewhere between BeginDraw() and ‘FinishDraw()’ calls.

Singletons

It is important that applications using CEGUI from Crystal Space do not use any of the CEGUI getSingleton() or getSingletonPtr() calls, such as CEGUI::Singleton<T>::getSingleton() or CEGUI::System::getSingleton(). The reason for this is that global and static variables (declared in methods, classes, namespaces, or globally) are not normally shared between modules. Calling getSingleton() from the Crystal Space application will not necessarily return the same instance as calling getSingleton() from the CEGUI plugin.

To remedy this, there are ‘Get*’ functions in the ‘iCEGUI’ interface that return a reference or pointer to the CEGUI singletons so that they may be used safely from a Crystal Space application. iCEGUI::GetSystem() and GetSystemPtr() are the most commonly used.

Resource Provider

The CEGUI plugin provides a VFS implementation of the CEGUI resource provider. This means that all paths passed to CEGUI functions should be VFS paths. Textures, scheme files, layout files, etc, will all be loaded through the VFS. Paths within these files should be VFS paths as well.

Event Handler

Keyboard and mouse input is automatically injected into the CEGUI event system by the CEGUI plugin event handler. The CEGUI display area is automatically resized when the Crystal Space canvas is resized.

This document was generated using texi2html 1.76.