UsingCEGUI

WIP (Jean-Philippe)

Resources

Imagesets

.imageset file

XML file defining a set of "images" to be used as textures for rendering the GUI

Each "image" of the set is defined by :

  • its name : its unique Id for references it in other XML files (like the .looknfeel file)
  • its position and size, in the "image file" specified at the top of the .imageset file

Example : 

<?xml version="1.0" ?>
<Imageset Name="SDMockupLook" Imagefile="SDMockupLook.tga" NativeHorzRes="800" NativeVertRes="600" AutoScaled="true">
    <Image Name="Background" XPos="9" YPos="9" Width="2" Height="2" />
    <Image Name="...
    ...

Notes :

  • CEGUI automatically assigns the "full_image" name to the whole image from the file,
  • You can't manually assign assign the "full_image" name to an image.

Every needed .imageset file have to be referenced in the .scheme file (se below).

Example : 

<?xml version="1.0" ?>
<GUIScheme Name="CEGUIDemo">
  <Imageset Filename="ceguidemolook.imageset" />
  <Imageset Filename="sd-logo.imageset" />
  ...

Image file

A bitmap file which serves as a board, from which rectangle "images" are to be extracted (see "image sets" above).

Ex: SDMockupLook.tga

What images can be used for

  • Widgets corners, edges and background,
  • Mouse cursor,
  • Bitmap fonts,
  • Window background,
  • ...

Fonts

Supported formats

Native support for .ttf fonts

Native support for bit map fonts, through an "image set" (not tested).

Other fonts ?

.font files

A .font file defines a "font" in the CEGUI meaning : a real font + 1 size

Example : 

<?xml version="1.0" ?>
<Font Name="MenuSmall" Filename="Jura-Regular.ttf" Type="FreeType" Size="8"
      NativeHorzRes="800" NativeVertRes="600" AutoScaled="true"/>

Once you've defined your needed .font files (for all the real fonts and sizes needed), you have to reference them in the .scheme file (and possibly overload the name in the .font)

Example : 

<?xml version="1.0" ?>
<GUIScheme Name="SDMockupLook">
   ...
   <Font Name="MenuSmall" Filename="menu-small.font" />
   <Font Name="MenuMedium" Filename="menu-medium.font" />
   ...

Look & Feel

CEGUI's Falagard core features a set of widgets and defines their actual interactive behaviour and features.

If you want to tweak an existing widget, or completely redefine it or create a brand new widget with new interactive behaviour and features, you'll need to work in this C++ core.

Now, this core features a great skinning system through XML file, which permits you to considerably change the look of the existing widgets without programming at all !

A .looknfeel file defines the visual way widgets are rendered, by :

  • defining the way each component of a widget is to be lain out inside its "window" object,
    • by defining rectangle areas inside this window (through a full-featured distance / coordinate expression system),
    • by defining alignment inside these area,
  • referencing "images" from "image sets" for rendering the multiple parts of each widget component,
  • setting values to the other visual properties of the widget components (text font, colours, ...),
  • defining multiple visual "states" of the widget (ex: hovered, disabled, normal, highlighted, ...),
  • ...

Details explained here :

Reference for each widget type here :

Scheme

A .scheme file achieves the glue between the above described resources (Image sets, fonts, look & feel), the CEGUI core widget set implementation, and the Falagard rendering system :

  • lists the fonts to load and use (defined in .font files),
  • lists the image sets to load and use (defined in .imageset files),
  • specifies the loo&feel to load and use (defined in a .looknfeel file),
  • associates custom widget types and their "implementation" :
    • the real CEGUI widget type they are based on (behaviour and features)
    • the look and feel to apply at render-time (defined in the .looknfeel file)
  • ... WIP ...

Layout

A .layout file defines the composition tree of a "screen", by assembling widgets and defining properties and layout parameters.

It's kind of a "lego" game.

Reference of properties for each widget of the standard "Taharez" look here (interesting if you use it directly, or a your own variant of it) :

Defining a look & feel

This is all about the Falagard skinning system, that is defining the "look & feel" (.looknfeel file) for your GUI.

Basically, every "widget type" in the "look & feel" has to be defined through a "WidgetLook?" element ; it features the following child elements :

  • Property definitions : New properties, to be used in the widget look, with a default value to be overwritten if needed when defining a layout (code or XML),
  • Properties : Default values of base widget properties (from the C++ core),
  • Named areas : Definition of rectangle areas to be used later in the widget look (some areas are required by the C++ core),
  • Child components : Layout of component child widgets in associated area,
  • Imagery sections : Layout of text and textures in associated areas, for compositing possible visual states of the widget type ; 3 possible child sections : "Imagery component", "frame component" and "text component" (see below),
  • State imageries : Association of imagery sections defining 1 of the visual states of the widget type (some states are required by the C++ core), with support for multiple and ordered rendering layers,
  • Animation definitions : Definition of a widget-specific animation (schedule, dynamics, affected properties, bound events, ...).

See reference for all details.

Some hints though :

Frame component

A frame component is rendered on screen through 0 to 9 textures ; they are specified through the <Image> or <ImageProperty> items of the <FrameComponent> item (inside an <ImagerySection> item) :

  • LeftEdge, RightEdge
  • TopEdge, BottomEdge
  • TopLeftCorner, TopRightCorner, BottomLeftCorner, BottomRightCorner
  • Background

Rendering scheme :

  • "Corner images are always drawn at their natural size, edges are stretched between the corner pieces for a particular edge, the background image will cover the inner rectangle formed by the edge images and can be stretched or tiled in either dimension." (from CEGUIFalFrameComponent.h 0.7.7)
  • The "natural size" mentioned above is meant as the actual width or height of the source bitmap (got from an image set, and read from an image file), taken in the virtual pixel rectangle space of the rendering window.
    As an example,
    • a 10x12 pixel top left corner image
    • will occupy a 20x18 real pixels rectangle
    • on a real 1600x1200 screen
    • if the CEGUI root window (virtual) coordinate space is set to 800x600
    • and if this window is maximized to full screen.
      On the contrary, in the same situation, the background image will occupy a real 1560x1164 pixel rectangle if the other corners also have a 10x12 size (through stretching or tiling, depending on the way it is specified in the look & feel).

Warning : There's also another texture "layer" being possibly rendered : see below the Imagery component.

Useful tips :

An imagery component is rendered as a single texture with standard size and alignment rendering features.

It is specified through the <Image> or <ImageProperty> item of the <ImageryComponent> item.

Note that this can probably be used along with the Frame component, in order to get 2 different areas textured independently !

Text component

TODO.

Widget features and limitations

Common to all widgets

But beware of Listbox(Text)Items (see List-box below) ...

Can:

  • not a flat model : widgets can be layered inside a real parent-child tree,
  • rich and flexible positioning / sizing system (with absolute and/or relative coordinates / sizes inside the parent widget),
  • customize through XML : font, text alignment, size, colours, 3D orientation, background textures and internal layout of most internal components,
  • customize look (how it is rendered) through the .scheme and .looknfeel files (define a new type of control, based on a real CEGUI one, in the .scheme file, and define how it must be rendered through a new section in the .looknfeel file).
  • animations on every available property, with custom dynamics (ex: colours, alpha, any 3D rotation, ...).
  • always show scrollbars, for widgets that use it (through properties).
  • always hide scrollbars, even if would be normally needed, for widgets that use it (but: only through code, after each item insertion).

Cannot:

  • use vector-defined shapes to render widgets : everything about the look has to be designed though textures.

Static text (label)

Can:

  • customize alignment, and word-wrapping for long sentences,
  • use layered-style colours for each letter (you define the colour for each of the 4 corners of the rendering rectangle)

Cannot :

  • use layered-style colours for a whole string (colour for each of the 4 corners of the rendering rectangle of the string)

Static image

Can:

  • Centre, tile or stretch / expand in the rendering rectangle.
  • keep aspect ratio of the original image (the SD way, see below cannot) : after loading the image file (in a new image set), we can well define an image (in that image set) that is a sub-rectangle of the "full_image" one by using the SD code to compute the coordinates of this sub-rectangle ... and use this image as the one to finally render.

Cannot :

  • built-in conservation of aspect ratio of the original image through clipping it top/bottom or left/right in the rendering rectangle (that is : using SD way of displaying menu background images and car preview images)

Text button

Can:

  • To be tried (nearly sure it is supported) :

  • display an icon for some states (ex: hovered) aside the button text (through the Imagery component, within a specific area).

Image button

Can:

  • To be tried :

  • X&Y-stretched image keeping aspect ratio

Check-box

Cannot:

  • To be tried :

  • X&Y-stretched image keeping aspect ratio

Radio-button

Cannot:

  • To be tried (nearly sure it is supported) :

  • X&Y-stretched image keeping aspect ratio (through area specs operators)

Edit-box

Can:

  • Be read-only,
  • Check entered "text" against some regular expression, and ignore unauthorized chars.

Cannot:

  • Multi-line edit-box

Can:

  • Be read-only
  • Check entered "text" against some regular expression, and ignore unauthorized chars.

Cannot:

  • Spinner

Can:

  • Cannot:

  • Slider

Can:

  • Horizontal or vertical variants,

  • Cannot:

  • Built-in display value as text (but: more tries needed) ?

Progress-bar

Can:

  • use 1 single image, or else as many ones as desired (1 for each "section" of the progress area, you define your own sections : see AltProgressBar? in the .looknfeel), to render the progress (by clipping the image(s) accordingly to the actual progress).

Cannot:

  • customize the progress range : has to be [0, 1] ; but this is really minor.

List-box

Warning : The Listbox widget class is deprecated and obsolete. Use ItemListBox as a far more powerful replacement.

ItemListBox :

Can :

  • natively use ItemEntry-derived widgets as items,
  • which means that, apart for ItemEntry itself, you have to write the (short) C++ code for the new class, and set up the relevant look&feel for it,
  • which means that this feature is not available through pure Python code,
  • see full example here,
  • but for base ItemEntry (derived from Window, with text display), you can then customize any text property (text font, colours (selected state or not) and selection brush (a texture), and also horizontal and vertical alignment / formatting / wrapping, ...), thus breaking the limitations of the obsolete ListboxTextItem?.

Cannot :

Listbox (deprecated, don't use)

Can :

  • customize text font, colours (selected state or not) and selection brush (a texture).

Cannot :

  • customize text item properties through XML (.layout or .looknfeel) :
    • because list items are instances of CEGUI::ListboxTextItems?,
    • because they are not like other widgets you can tweak through .layout or .looknfeel files,
    • because you have to instantiate and add them to the list. through code,
  • customize text alignment in list,
  • natively use any (composite) widget as items ; but there are workarounds (not sure if usable in Python though) :

Combo-box

See the obsolete version of the List-box above about item limitations.

Note: Crazy Eddy has plans to improve this, but no clear schedule.

Multi-column list

See the obsolete version of the List-box above about item limitations.

Note: Crazy Eddy has plans to improve this, but no clear schedule.

Can:

  • interactively sort according to 1 selected column (both directions),
  • move a column (drag & drop),
  • resize columns (same),
  • customise font and text colour by cell

Cannot :

  • customizing font in header cells : can't make it work ...

Scrollable pane

Can :

  • insert child widgets inside, of any size, at any (absolute) position (but rendering only the clipped area),
  • automatic scrollbars if more to be displayed than widget size (but can be force-hidden if needed),

  • Tab-control

Can:

  • Cannot:

  • Menu and pop-up menu

Can:

  • Cannot:

  • Tree

See the obsolete version of the List-box above about item limitations, even if we use TreeItems? here, not ListboxItems? (they share the same caveats).

Note: Crazy Eddy has plans to improve this, but no clear schedule.

Cannot:

  • customize the frame colour through the "FrameColours?" property in a layout file (doesn't work),
  • customize the margin through the "Margin" property in a layout file (doesn't work),
  • get correct rendering of the item text : it is always clipped by some pixels at the top of the item,
  • ...

PyCEGUI : the CEGUI Python binding

Whereas it works great, it shows some few limitations, when compared to the pure C++ API (more details here) ; this is not a real issue as we don't plan to use it, but it forced us to adopt workaround when (Python) coding the CEGUI demo :

  • you can't attach user data to list-box, combo-box and tree items :
    • the setUserData doesn't work, and raises an exception (expecting a void* as the user data, but not accepting any Python object),
    • you can well add a dedicated attribute to the Python item object, but don't expect to get it back when the item comes back from the CEGUI C++ layers.

Related

Wiki: GUICodeTo3rdParty
Wiki: Index