Various components are layered on top of one another to produce the visual display for every Control.
The BackgroundComponent provides a rectangular fill for its Control. This fill may be a simple color, an image/texture, or a 3D construct. Typically, a background consumes no inherent space other than the size of its margins.
The IconComponent provides a special decoration layered on top of the background. Whereas a background typically consumes no space expect for its margins, an icon will consume enough space to match its associated image.
The InsetsComponent defines positioning and resizing for its Control. It supports two aspects: a static, fixed gutter around the outer edge, and dynamic positioning. The fixed gutter is defined independently for all four sides. For any non-zero gutter, the corresponding width/height is incremented during the preferred size calculation, and the starting position is kicked left and down accordingly. The Insets has no visual aspect, so the parent control shines through the gutters.
The dynamic positioning only applies when the actual available size exceeds the preferred size. In this case, the excess is divvied up and applied to the starting position. The dynamic positioning is represented by a percentage applied to all four edges. The most common example is 50% applied left and right, with 50% applied top and bottom. This results in the Viewable being centered within the excess space.
NOTE that if your static gutter definitions are all <= 1.0, then they are treated as a dynamic setting.
The TextComponent defines a run of text characters in a given font/size/color. An instance of a TextComponent is rarely explicitly constructed, since most text presentation is embedded within text oriented controls, such as Label or TextString. But a TextComponent is just like any other component and can be explicitly used as such.
Fill is used to provide the pixels that populate a background or icon. Most fill is based on a flat Quad providing pixels in two dimensions. But there also exists a FillGeometry, based on an arbitrary Mesh, which in only flattened into 2D by the Camera associated with the GUI Viewport.
The simplest fill is based on a 2D rectangular Quad populated by a single texture.
A MutltiQuad is a 2D rectangular Quad populated by a compound image that contains a repeating set of equally sized images. One such image is selected to act as the fill. The image set can be vertically oriented (index selects a row), horizontally oriented (index selects a column), or tabular (indexes select row and column).
The scaled fill is based on a 2D rectangular Quad populated by a single image, with possibly scaling applied to the texture. A ScaledQuad can also be set to 'tile' an area larger than the image, rather than stretching the image.
The TbtQuad is based on a 2D rectangular Quad treated as a three-by-three grid. When stretching the Quad to fill a space larger than the inherent image, NW, NE, SW, and SE cells are not stretched at all. West/East are stretched only vertically, and North/South are stretched only horizontally. The Center is stretched both ways. This gives you image that stretches nicely without being distorted. The TbtQuad is inherently a MultiQuad so that multiple 3by3 images can be included in a single file.
+-----+--------------+-------+
| | <-----> | |
y2 +-----+--------------+-------+
| | | |
| ^ | ^ | ^ |
| | | | | | |
| | | <-----> | | |
| | | | | | |
| v | v | v |
| | | |
y1 +-----+--------------+-------+
| | <-----> | |
+-----+--------------+-------+
x1 x2
FillGeometry is not based on a Quad, but rather renders any arbitrary mesh. It extends com.jme3.scene.Geometry and uses the standard XML import process to load the geometry mesh. You can also provide a texture to use with the Geometry.
A DisplayStateAdapter alters its associated component based on the active display state of the associated Viewable. While every adapter can support a comprehensive set of different display states, providing a different action for every state permutation, in most cases only a few special states are identified, and these actions cover a rather wide range of individual states. For example, a single action defined for the Inactive state will apply to FocusInactive, HoverInactive, etc.
The various state adapters apply different adjustments based on the kind of adapter:
<colorStateAdapter>
<states>
<Inactive><color r='0' g='0' b='0' a='1' /></Inactive>
<Active><color r='1' g='1' b='1' a='1' /></Active>
</states>
</colorStateAdapter>
<alphaStateAdapter applyTo='Self/Parent/ParentTree/ParentChildren'>
<states>
<Disabled value='0.3'/>
<Inactive value='-1' />
</states>
</alphaStateAdapter>
<materialStateAdapter>
<states>
<Inactive><color r='0' g='0' b='0' a='1' /></Inactive>
<Active><com.jme3.texture.Texture attrsThatDefineTheTexture /></Active>
<FocusActive><com.jme3.asset.TextureKey name='pathToATexture' /></FocusActive>
<HoverInactive value='pathToAnImage' />
</states>
</materialStateAdapter>
<textureStateAdapter>
<states>
<Active><com.jme3.texture.Texture attrsThatDefineTheTexture /></Active>
<FocusActive><com.jme3.asset.TextureKey name='pathToATexture' /></FocusActive>
<HoverInactive value='pathToAnImage' />
</states>
</textureStateAdapter>
<mutliTextureStateAdapter>
<states>
<Inactive value='indexValue'/>
<Active value='colIndex,rowIndex' />
</states>
</multiTextureStateAdapter>
<overlayStateAdapter>
<states>
<Active><com.jme3.texture.Texture attrsThatDefineTheTexture /></Active>
<FocusActive><com.jme3.asset.TextureKey name='pathToATexture' /></FocusActive>
<HoverInactive value='pathToAnImage' />
<Pressed><fillQuad completeSpecificationOfTheQuad /></Pressed>
</states>
</overlayStateAdapter>
<textStateAdapter>
<states>
<Active><textStateSpec color='#f00f' style='italic' alpha='0.5 /></Active>
<FocusActive><textStateSpec text='Display This' styleID='0' pattern='XXX' >
<color r='0.5' g='0.5 b='0.5' a='1.0'/>
</FocusActive>
</states>
</textStateAdapter>
For any single component, you can define one or more different adapters. You end up with something like this:
<stateAdapters>
<colorStateAdapter>
...
</colorStateAdapter>
<textStateAdapter>
....
</textStateAdapter>
</stateAdapters>