3.4.2 Standard OverlayElements

Although OGRE's OverlayElement and OverlayContainer classes are designed to be extended by applications developers, there are a few elements which come as standard with Ogre. These include:

• Panel
• BorderPanel
• TextArea
• TextBox

Panel (container)

This is the most bog-standard container you can use. It is a rectangular area which can contain other elements (or containers) and may or may not have a background, which can be tiled however you like. The background material is determined by the material attribute, but is only displayed if transparency is off.

Attributes:

transparent <true | false>

If set to 'true' the panel is transparent and is not rendered itself, it is just used as a grouping level for it's children.

tiling <layer> <x_tile> <y_tile>

Sets the number of times the texture(s) of the material are tiled across the panel in the x and y direction. <layer> is the texture layer, from 0 to the number of texture layers in the material minus one. By setting tiling per layer you can create some nice multitextured backdrops for your panels, this works especially well when you animate one of the layers.

uv_coords <topleft_u> <topleft_v> <bottomright_u> <bottomright_v>

Sets the texture coordinates to use for this panel.

BorderPanel (container)

This is a slightly more advanced version of Panel, where instead of just a single flat panel, the panel has a separate border which resizes with the panel. It does this by taking an approach very similar to the use of HTML tables for bordered content: the panel is rendered as 9 square areas, with the center area being rendered with the main material (as with Panel) and the outer 8 areas (the 4 corners and the 4 edges) rendered with a separate border material. The advantage of rendering the corners separately from the edges is that the edge textures can be designed so that they can be stretched without distorting them, meaning the single texture can serve any size panel.

Attributes:

border_size <left> <right> <top> <bottom>

The size of the border at each edge, as a proportion of the size of the screen. This lets you have different size borders at each edge if you like, or you can use the same value 4 times to create a constant size border.

border_material <name>

The name of the material to use for the border. This is normally a different material to the one used for the center area, because the center area is often tiled which means you can't put border areas in there. You must put all the images you need for all the corners and the sides into a single texture.

border_topleft_uv <u1> <v1> <u2> <v2>

[also border_topright_uv, border_bottomleft_uv, border_bottomright_uv]; The texture coordinates to be used for the corner areas of the border. 4 coordinates are required, 2 for the top-left corner of the square, 2 for the bottom-right of the square.

border_left_uv <u1> <v1> <u2> <v2>

[also border_right_uv, border_top_uv, border_bottom_uv]; The texture coordinates to be used for the edge areas of the border. 4 coordinates are required, 2 for the top-left corner, 2 for the bottom-right. Note that you should design the texture so that the left & right edges can be stretched / squashed vertically and the top and bottom edges can be stretched / squashed horizontally without detrimental effects.

TextArea (element)

This is a generic element that you can use to render text. It uses fonts which can be defined in code using the FontManager and Font classes, or which have been predefined in .fontdef files. See the font definitions section for more information.

Attributes:

font_name <name>

The name of the font to use. This font must be defined in a .fontdef file to ensure it is available at scripting time.

char_height <height>

The height of the letters as a proportion of the screen height. Character widths may vary because OGRE supports proportional fonts, but will be based on this constant height.

colour <red> <green> <blue>

A solid colour to render the text in. Often fonts are defined in monochrome, so this allows you to colour them in nicely and use the same texture for multiple different coloured text areas. The colour elements should all be expressed as values between 0 and 1. If you use predrawn fonts which are already full colour then you don't need this.

colour_bottom <red> <green> <blue> / colour_top <red> <green> <blue>

As an alternative to a solid colour, you can colour the text differently at the top and bottom to create a gradient colour effect which can be very effective.

TextBox (element)

This element is a box that allows text input. It is composed of 2 elements, a TextArea, which defines the size, colour etc of the text to be used when typed, and a back panel which is the box-element on which the text is written.

Attributes:

text_area <template name> [<caption>]

The name of the TextArea template to be used as the basis for the TextBox font. The optional caption is the text the textbox is initialised with.

back_panel <template name>

The name of the back panel template (e.g. a BorderPanel) to be used as the basis for the back panel on which the text is written. This needs to be a container.