GUI9Slice

From HEWIKI
Jump to: navigation, search

Contents


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.

Usage

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.


9slice.png

Fields

Slices

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.

It is valid to set any or all of the slices subfields to 0.

GUI9Slice supports standard textures, but does not currently support mask textures, nor minimap or virtual stage textures.

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.

Margin

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.

Resize

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

allowMove

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.

Example

This example will create a moveable, resizable panel from the "Ctrl" button image in _cleanenginegui.dds:

Cleanenginegui.png

  function ctrlButton()
    button as NodeRef of Class GUI9Slice = createNodeFromPrototype("_panel9Slice")
    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.

The result:

Ctrl1.png


After resizing, by dragging the edges with the mouse:

Ctrl2.png

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:

Ctrl3.png

Note how the 5 pixel borders do not stretch, but the central section stretches to fill the size of the control.

See also

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox