m (1 revision)
Revision as of 14:25, 20 June 2011
GUI9Slice is a special kind of GUI Control that simplifies construction of complex multi-controls.
Buttons and Windows are often constructed from many docked GUI controls. A typical button, that can be resized, might have eleven or so GUI controls. The new (May 2008) 9-Slice GUI Control lets you specify such constructs with a single control. It is very flexible and, since it is only one control, is far faster to create and render. It also uses a lot less memory.
GUI9Slice is a GUI panel divided by two horizontal lines and two vertical lines into a grid of nine sections. Each section knows how to tile or stretch appropriately. It can be used to create buttons and windows without the need for separate controls for each edge and corner.
GUI9Slice can also be used as a simple blank GUIPanel with margins, simplifying complex layouts.
The slices field determines the size of each edge. For instance, slices.rectBottom determines the height of the bottom edge (sections 7, 8 and 9). This affects how the control's texture is tiled or stretched.
- The corner sections (1, 3, 7, and 9) always remain a fixed size.
- The upper and lower edges (sections 2 and 8) will tile or stretch (determined by tiling.horizontal) horizontally as needed, but remain a fixed size vertically.
- The left and right edges (sections 4 and 6) will tile or stretch (determined by tiling.vertical) vertically as needed, but remain a fixed size horizontally.
- The center section (5) will tile or stretch in either direction as needed.
It is valid to set any or all of the slices subfields to 0.
For example, your source texture can include an unbroken image of a rectangular button. Set defaultstatepresentation.uv.position and defaultstatepresentation.uv.size to include the entire area of the button. Set slices to mark the edges of the button, and tiling false. Now the 9Slice control will maintain properly defined edges regardless of its size.
Without GUI9Slice, it requires at least 9 controls to create a fully resizable button or window.
The margin field determines the layout of any child controls the 9Slice might have. You'll often want to set this field to the same values as slices. You may also want to use an untextured 9Slice control rather than a panel for formatting purposes. Any child control with dockmode NONE, FILL, TOP, BOTTOM, LEFT or RIGHT will respect the margins, while MARGINLESS_NONE, MARGINLESS_FILL, MARGINLESS_TOP, MARGINLESS_BOTTOM, MARGINLESS_LEFT and MARGINLESS_RIGHT dockmodes will ignore the margin.
The resize field can enable automatic resizing features, just as if the edges were GUIResizePanels. For example, if resize.top and resize.left are true, a user can resize the 9Slice control vertically by dragging sections 2 or 3, horizontally by dragging sections 4 or 7, and both horizontally and vertically by dragging section 1. (This enables using a GUI9Slice as the root of a resizable window control, without needing to dock or anchor several GUIResizePanels.)
The allowMove field enables the GUI9Slice to be moved as if it were a GUIMovePanel with its parent field set to itself. Dragging in any section where resizing is not enabled will move the control.
This example will create a moveable, resizable panel from the "Ctrl" button image in _cleanenginegui.dds:
function ctrlButton() button as NodeRef of Class GUI9Slice = createNodeFromPrototype("nineSlice") button.defaultStatePresentation.color.r = 1 button.defaultStatePresentation.color.g = 1 button.defaultStatePresentation.color.b = 1 button.defaultStatePresentation.color.a = 1 button.defaultStatePresentation.position.x = 23 button.defaultStatePresentation.position.y = 164 button.defaultStatePresentation.size.x = 25 button.defaultStatePresentation.size.y = 25 button.texture = "\GUI\_CleanEngineGUI.dds" button.tiling.horizontal = true button.tiling.vertical = true button.build = true button.size.x = 100 button.size.y = 25 button.position.x = 200 button.position.y = 200 button.slices.rectTop = 5 button.slices.rectBottom = 5 button.slices.rectLeft = 5 button.slices.rectRight = 5 button.minimumSize.x = 25 button.minimumSize.y = 25 button.resize.bottom = true button.resize.top = true button.resize.left = true button.resize.right = true button.allowMove = true .
This sets a 25x25 rectangle starting at location 23,164 in the texture as the overall area to be rendered, including a border of 5 pixels on each side.
After resizing, by dragging the edges with the mouse:
Note how the 5 pixel borders on each side do not tile, but the central section does tile.
If we change tiling.horizontal and tiling.vertical to false:
Note how the 5 pixel borders do not stretch, but the central section stretches to fill the size of the control.