Unified Positions and Sizes System

Written for CEGUI 0.4

---

Works with versions 0.4.x (obsolete)

Written for CEGUI 0.5

---

Works with versions 0.5.x (obsolete)

Written for CEGUI 0.6

---

Works with versions 0.6.x (obsolete)

Written for CEGUI 0.7

---

Works with versions 0.7.x (obsolete)

note: This page only applies to CEGUI >= 0.4.0

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.

Another example could be

{0.5,25}

which would make it half the width of its parent plus 25 pixels.

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

would yield a window width the same width as its parent but an absolute height of 100 pixels.

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 its parent window. There is only one property that takes a URect. UnifiedAreaRect.

The fact that we are specifying edges instead of size, can be useful. For example if we want a window to cover its entire parent, but leave a 10 pixel border a value like this could be used:

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

Y-position: 30 pixel above the bottom of the parent window

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