GUI Components
GUI Elements are constructed from a stack of GUI Components that implement the GuiComponent interface. The stacks are composed in a way where each layer acts as a kind of 'decorator' for the next layer (from bottom up).
For example, a Button is built from several different possible layers and the application can change any of these layers.
Therefore, to understand how to tweak a GUI element to get a specific look, it is necessary to understand the GUI components that Lemur provides. Or to know how to write your own.
This component renders a simple colored or textured 2D quad that shrinks/expands with the GUI element. (The texture is stretched directly without any special processing. For a texture that stretches only part and leaves the borders a common scale, see: TbtQuadBackgroundComponent)
The quad is currently always rendered in the x/y plane.
QuadBackgroundComponent can create either a lit or an unlit quad depending on the options specified when created. There is currently no way to change this option once the component has been created. Being 'lit' means that the quad will use Lighting.j3md and have proper normals.
Properties:
- color: the color of the quad. If there is a texture then this will be combined with the texture.
- alpha: the overall alpha of the quad. This is multiplied by whatever alpha is in the color value.
- texture: an optional texture for the quad.
- margin: a margin that controls how much size the next component in the stack gets. For example, a GUI element that is size 100x100 and has a QuadBackgroundComponent for its 'border' layer and a 5,5 margin would render the 'background' layer at 90x90 with a 5,5 x/y offset.
- zOffset: the z-size of the quad. Useful when layering to create slight stand-offs for subsequent layers.
This is similar to QuadBackgroundComponent except that it always has a texture and it implements 9-patch style stretching.
The reason it's called a 'nine patch'.
Lemur calls it a TBT Quad which is short for 'Three-By-Three' Quad and is shorter to type than 'NinePatchQuadBackgroundComponent' and more unique than NpQuadBackgroundComponent would be. A rose by any other name...
Nine patches are useful for UI Element backgrounds because they provide smarter stretching at the borders.
They can be somewhat tricky to setup but Lemur tries to make it easier. It's at least easier than manually calculating texture coordinates versus image size versus target size would be.
When creating a TBT Quad, Lemur has reduced the parameters down to imageScale and two corner coordinate values:
- imageScale: defines the scale between visual units and image units. For example, if the image is 128x128 then a scale of 1 means that on-screen the border widths will be scaled 1:1 to the pixels. So if the border is 16 image pixels then it will be 16 screen pixels. If the imageScale is 2 then those same borders would end up as 32 on-screen pixels.
- x1, y1: defines the lower left corner of the center full-stretch area in image pixels.
- x2, y2: defines the upper right corner of the center full-stretch area in image pixels.
The texture image used in the nine-patch example above is the 'com/simsilica/lemur/icons/bevel-quad.png' included in Lemur by default. It is a 128x128 image and the borders are 8 image pixels wide. Thus we could create a TBT quad component with the following parameters: imageScale=1, x1=8, y1=8, x2=119, y2=119
If that component is drawn on screen as 100x50 in size then the borders would still be 8 pixels wide but the stretched area would be 84x34 pixels. If the imageScale is changed to 2 then the borders would be 16 pixels wide and the stretched area would be 52x2.
As with QuadBackgroundComponent, the TbtQuadBackgroundComponent can create either a lit or an unlit quad depending on the options specified when created. There is currently no way to change this option once the component has been created. Being 'lit' means that the quad will use Lighting.j3md and have proper normals.