Each PPM image consists of the following:

1. A "magic number" for identifying the file type. A ppm image's magic number is the two characters "P6".
2. Whitespace (blanks, TABs, CRs, LFs).
3. A width, formatted as ASCII characters in decimal.
4. Whitespace.
5. A height, again in ASCII decimal.
6. Whitespace.
7. The maximum color value (Maxval), again in ASCII decimal. Must be less than 65536 and more than zero.
8. A single whitespace character (usually a newline).
9. A raster of Height rows, in order from top to bottom. Each row consists of Width pixels, in order from left to right. Each pixel is a triplet of red, green, and blue samples, in that order. Each sample is represented in pure binary by either 1 or 2 bytes. If the Maxval is less than 256, it is 1 byte. Otherwise, it is 2 bytes. The most significant byte is first.

   A row of an image is horizontal. A column is vertical. The pixels in the image are square and contiguous.

10. In the raster, the sample values are "nonlinear." They are proportional to the intensity of the ITU-R Recommendation BT.709 red, green, and blue in the pixel, adjusted by the BT.709 gamma transfer function. (That transfer function specifies a gamma number of 2.2 and has a linear section for small intensities). A value of Maxval for all three samples represents CIE D65 white and the most intense color in the color universe of which the image is part (the color universe is all the colors in all images to which this image might be compared).

    ITU-R Recommendation BT.709 is a renaming of the former CCIR Recommendation 709. When CCIR was absorbed into its parent organization, the ITU, ca. 2000, the standard was renamed. This document once referred to the standard as CIE Rec. 709, but it isn't clear now that CIE ever sponsored such a standard.

    Note that another popular color space is the newer sRGB. A common variation on PPM is to subsitute this color space for the one specified.

11. Note that a common variation on the PPM format is to have the sample values be "linear," i.e. as specified above except without the gamma adjustment. pnmgamma takes such a PPM variant as input and produces a true PPM as output.
12. Strings starting with "#" may be comments, the same as with PBM.

The unified metrics system in CEGUI 0.4.0 and up, allows you to have both a relative and absolute component of a coordinate / dimension. This gives you alot more flexibility in how you layout your windows. For example you can use relative metrics for the height and absolute metrics for the width. Or simply mix and match.

There are three different forms in unified metrics:

• UDim - a single dimension.
• UVector2 - a two dimensional UDim vector
• URect - four UDims describing a rectangle by its left, top, right and bottom edges.

The property system in CEGUI uses a special syntax for unified dimensions.

UDim

The UDim is the simplest.

{''scale'',''offset''}   fx:   {1,0}

The scale component relative to the parent window, after it has been translated to pixels the offset is added. So if we used the example above as value for the UnifiedWidth property we would get a window exactly the width of its parent.

{0.5,25}

The properties that take a single UDim like the ones used above are:

• UnifiedXPosition
• UnifiedYPosition
• UnifiedWidth
• UnifiedHeight

UVector2

The UVector2 is used for position and size if you want avoid specifying each single dimension seperately (x,y,w,h).

{{''x-scale'',''x-offset''},{''y-scale'',''y-offset''}}   fx:   {{1,0},{1,0}}

Besides the extra {..} around its two UDims it's very similar. Let's say we use the example above as value for the UnifiedSize property of a window, we would get a window that had exactly the same size as its parent.

{{1,0},{0,100}}

The properties that take UVector2 values are:

• UnifiedPosition
• UnifiedSize
• UnifiedMinSize
• UnifiedMaxSize

URect

The last type is URect. It's a little special in that it specifies the left, top, right and bottom edges instead of position and size. As there is alot of parameters I'll write ls instead of left-scale, to instead of top-offset etc.

{{ls,lo},{ts,to},{rs,ro},{bs,bo}}   fx:   {{0,0},{0,0},{1,0},{1,0}}

The example above is the default rectangle for a DefaultWindow type window. It will cover the entire area of it's parent window. There is only one property that takes a URect. UnifiedAreaRect.

{{0,10},{0,10},{1,-10},{1,-10}}

The x and y position are simple absolute-only dims with a value of 10 pixels. The right and bottom edges are 100% relative components with a offset of -10 which will make it "move back" 10 pixels relative to the parent's right and bottom edges.

XML examples

<Property Name="UnifiedPosition" Value="{{0.1,10},{1.0,-30}}" />

X-position: 10% of the width of the parent window + 10 pixel 父窗体1/10+ 10个像素

Y-position: 30 pixel above the bottom of the parent window 父窗体高度差30个像数

<Property Name="UnifiedSize" Value="{{0.6,5},{0.3,20}}" />

Width: 60% of the width of the parent window + 5 pixel

Height: 30% of the height of the parent window + 20 pixel

<Property Name="UnifiedXPosition" Value="{0.25,-5}" />

X-position: 25% of the width of the parent window minus 5 pixel

<Property Name="UnifiedAreaRect" Value="{{0.1,0},{0.1,0},{0.9,0},{0.9,0}}" />

X-position: 10% of the width of the parent window.

Y-position: 10% of the height of the parent window.

Width: 80% of the width of the parent window.

Height: 80% of the height of the parent window.

Introduction to window and widget concepts

Before we get the the meat of this tutorial there are some essential ideas that you must first consider.

Every widget is a window

This is the most central concept that must be grasped when working with CEGUI. Every widget within the system is derived from the same Window base class; so for the purposes of this tutorial, whenever I mention a window, the same ideas could just as easily be applied to a push button or scrollbar widget.

Many settings are inherited

Many of the settings and properties available for windows in CEGUI are passed down the window hierarchy. For example, if you set the alpha transparency on a particular window to 0.5, then by default, all window and widgets attached to that window will also be affected by the change applied at the higher level; although note also that the actual setting on the child window remains unchanged - the final values and/or settings used are usually some combination of the setting values from all windows in the hierarchy down to the current window. This also applies to things such as window destruction; by default, a window will destroy attached child windows and widgets when it is destroyed. The main advantages of this arrangement are that you can easily affect a the whole GUI by making changes to the root window settings for things like alpha, visibility, enabled / disabled state, and can easily 'clean up' an entire GUI layout by simply destroying the root window. The default 'inherited' behaviours can be overridden on a per window basis where more fine grained control is needed, or where certain advanced management techniques are to be used.

Creating the windows

Enough of the waffle! Lets create a window.

There are two ways of doing this, via C++ code and XML layout files. Each approach is discussed below.

GUI Creation via C++ code

All windows in CEGUI are created by the WindowManager singleton object. You can get access to this object via the usual getSingleton method as follows:

using namespace CEGUI;
WindowManager& wmgr = WindowManager::getSingleton();

In general, you will be using what is known as a DefaultWindow (or to use it's old name, DefaultGUISheet) as the 'root' window in your GUI. This is not required, but is the accepted pattern of usage for CEGUI and, once you start adding more top-level windows, helps simplify laying things out.

So, to get the ball rolling, we'll create a DefaultWindow as set it as the root 'GUI Sheet' for the GUI:

Window* myRoot = wmgr.createWindow( "DefaultWindow", "root" );
System::getSingleton().setGUISheet( myRoot );

The createWindow method of the WindowManager takes two strings as its parameters. The first one, "DefaultWindow" in this example, tells the system the type or class of the window you wish to create. Generally, the windows you have available are those which were registered when you loaded your scheme file, although some, like DefaultWindow, are global types and are always available. The second parameter, "root" in this example, is a unique name which will be assigned to the window; this name can be used to retrieve a pointer to the window from the WindowManager at a later time. Note that naming your root window "root" is not required, but is a common convention.

The setGUISheet method in the System singleton object is used to specify a given window as the root of the GUI. This will replace any current sheet / root window, although do note that the previous window hierarchy is not actually destroyed; it is just unlinked from the display - you can easily switch between GUI 'pages' by simply flipping between them using the setGUISheet method.

Now you have created your first window and attached it to the GUI system, and the system will use this window as the root of the GUI when it draws the GUI. But, if you were to compile a simple program using this code, you still can't see anything; what gives? There's nothing wrong with your application, the DefaultWindow which we created above is just totally invisible! This is what makes the DeafultWindow ideally suited as a root window; it serves as a blank canvas onto which other window and widgets can be attached. So, lets do that now...

Here we will create a frame window; this is a window that functions in a similar manner to the windows on your desktop UI, it has a title bar and can be moved and re-sized.

FrameWindow* fWnd = (FrameWindow*)wmgr.createWindow( "TaharezLook/FrameWindow", "testWindow" );

here we are creating a "TaharezLook/FrameWindow" window. This name uses a convention seen throughout the system, whereby a window type is prefixed by the name of the widget set (if you were to load the WindowsLook scheme, you could create a "WindowsLook/FrameWindow" object instead). We have given our new window the simple test name of "testWindow". One final thing to note is the use of the cast, this is required since the createWindow method always returns a base Window type; in this, and many other cases a basic Window pointer will suffice, but there are times when you'll want to access methods introduced in the window and widget sub-classes, so the use of the cast as shown is common when using CEGUI.

In order for the system to be able to do something useful with our new window, we must perform a few additional steps.

First, we must attach the window to the root window we established above:

myRoot->addChildWindow( fWnd );

Now, we can set an initial position and size for our window. CEGUI uses a 'unified' co-ordinate system enabling the use of relative (scale) and absolute (offset) components at the same time - this is why each co-ordinate you will see has two parts. For a slightly extended introduction of this concept see Introduction and overview of core "Falagard" support systems. Back to the example:

// position a quarter of the way in from the top-left of parent.
fWnd->setPosition( UVector2( UDim( 0.25f, 0 ), UDim( 0.25f, 0 ) ) );

// set size to be half the size of the parent
fWnd->setSize( UVector2( UDim( 0.5f, 0 ), UDim( 0.5f, 0 ) ) );

Finally, we set a caption for the frame window's title bar:

fWnd->setText( "Hello World!" );

And that's it! When compiled into an application, you will now see a simple frame window in the middle of the display.

XML layouts

All of the above is very nice, but there is one major drawback; any time you wish to adjust the GUI layout, you need to edit your code and recompile. This will get old pretty quick, so what you really want is to be able to specify your GUI layout externally, and have your code load the layout via a file. This is the purpose of the CEGUI layout XML files.

The system supports XML layout files, which can be loaded via the WindowManager using the loadWindowLayout method. This method creates all the windows for you and returns a pointer to the root window of the loaded hierarchy; which is ideal for assigning as the root of the GUI!

So, first of all we need a layout file. The following XML saved as a text file, is a layout file equivalent to the code we discussed above:

<?xml version="1.0" ?>
<GUILayout>
    <Window Type="DefaultWindow" Name="root">
        <Window Type="TaharezLook/FrameWindow" Name="testWindow">
            <Property Name="UnifiedPosition" Value="{{0.25,0},{0.25,0}}" />
            <Property Name="UnifiedSize" Value="{{0.5,0},{0.5,0}}" />
            <Property Name="Text" Value="Hello World!" />
        </Window>
    </Window>
</GUILayout>

The Window elements show an obvious mapping to the createWindow method from the WindowManager object; they take a type and a name which directly correspond to the parameters discussed previously.

Nesting of the Window elements is used to attach certain windows to others. Note that you may only have one 'root' level window in a layout file, which is another reason you'll usually see the DefaultWindow used as a canvas on which other windows and widgets are placed.

The Property elements are used to set properties on the Window being defined. There are many properties available for each window/widget class, and each class also inherits all properties from it's parent class. See the <element>Properties namespaces in the API reference for documentation on the available hard-coded properties and their 'value string' formats. Since 'Falagard' skins can create their own properties, it is likely that the windows you are using contain many more properties than listed in the previous link - for these 'soft' properties, you need to consult whichever documentation is provided with the skin you are using (for the sample skins see TaharezLook and WindowsLook).

If saved as a file called "test.layout", you could load this layout and set it as the GUI root as follows:

using namespace CEGUI;
Window* myRoot = WindowManager::getSingleton().loadWindowLayout( "test.layout" );
System::getSingleton().setGUISheet( myRoot );

The end result is exactly the same as what was done in C++ code earlier, except that now you can modify and enhance the GUI layout without the need for constant editing and recompilation of the application code.

理解以上教程很是简单，提供了两种创建widget的方法