NGUI es un potente complemento para Unity 3D desarrollado por Tasharen Entertainment que permite crear interfaces de usuario (UI) de forma muy eficiente y flexible. Este manual en castellano recoge todo lo que hay que saber para aprovechar toda la potencia de NGUI.

Documentación oficial en inglés:

• Índice, videotutoriales, ejemplos, componentes…
• Todos los componentes de NGUI
• Lista de clases
• Novedades de cada versión (suscribirse al hilo para recibir notificaciones)

En Unity cada componente de NGUI enlaza a su página de ayuda desde el menú contextual > Help.

Estructura basica

Un interface de NGUI está formado por un objeto UI Root conteniendo los componentes UIRoot y UIPanel. La cámara que muestra el interface va en uno de los hijos (Camera) e incluye al componente UICamera. Los demás hijos serán los componentes o widgets que forman el interface (el Sprite en la imagen).

UIRoot

Descripción | Referencia

Ajusta la escala del interface en función del tamaño de la pantalla y el modo indicado. Debe ser el componente raíz de la jerarquía del interface.

• PixelPerfect mantiene la relación 1 a 1: un pixel de interface corresponde siempre a un pixel de pantalla. PixelPerfect se aplica dentro de los límites marcados (Minimum Height, Maximum Height). Fuera de los límites los componentes reciben escalado.
• FixedSize hace que el interface siempre tenga el mismo tamaño con independencia de la resolución. Se establece un tamaño de pantalla de referencia en pixels (Manual Height) y los componentes se escalarán en la pantalla según ese tamaño. Por ejemplo, si se establece Manual Height = 1000 entonces un sprite de 500×500 ocupará la mitad del alto de la pantalla.

UIRoot establece una escala base “manejable” para mostrar los demás componentes, ya que éstos trabajan en escala 1:1 (1 pixel por unidad de longitud). No obstante, también sería posible establecer esta escala directamente y eliminar este componente.

UIPanel

Descripción | Referencia

Componente que alberga y gestiona los controles (widgets) que se le añadan como hijos en la jerarquía. UIPanel es responsable de generar la geometría y dibujar los componentes en pantalla (más o menos equivalente al Renderer de Unity).

Cada panel tiene un valor de profundidad (Depth) para ser mostrado delante o detrás de otros paneles. Las interacciones también se detectan según el Depth de panel. Es recomendable que no haya paneles compartiendo el mismo valor Depth. El valor de transparencia (Alpha) se aplica a todos los widgets en el panel. Con Clipping desactivado los componentes se pueden mostrar en cualquier parte de la pantalla. En este caso la vista Scene muestra el marco púrpura con los botones de ajuste en gris (desactivados). Las dimensiones se establecen automáticamente a la resolución del marco de pantalla actual.

Con Clipping activado se puede definir el área en el que los componentes del panel son visibles. En este caso se pueden usar los botones de ajuste en la vista Scene para establecer la posición y dimensiones del panel. También es posible definir una zona de suavizado antes de recortar los componentes que salen del panel. El cuadro interior en color más claro muestra la zona en la que los componentes son 100% visibles, antes del suavizado.

• Los paneles y los widgets heredan del componente UIRect. Este componente ofrece toda la funcionalidad de posición, dimensiones y anclajes (Anchors).
• Es posible anidar paneles en la jerarquía del interface. Los paneles anidados hijos se combinan adecuadamente según la configuración de los paneles padre (alpha, clipping). Se pueden usar para establecer prioridades delante-detrás en el dibujado de componentes.
• Con cada panel se añade un componente RigidBody estático (kinematic) porque es mucho más eficiente mover los componentes tipo Collider cuando pertenecen a un RigidBody.
• En el panel asociado a UIRoot los botones de redimensión no funcionarán correctamente por conflictos con la escala.

UICamera

Descripción | Referencia

El nombre del componente denota que va asociado a una cámara. Lo único que hace es enviar los eventos NGUI a los objetos mostrados por la cámara. No tiene que ser necesariamente un interface, sirve cualquier objeto con un Collider al que se quieran enviar eventos NGUI (OnPress, OnClick, OnDrag, etc).

• Requiere que la opción “Raycasts Hit Triggers” esté activada en Edit > Project Settings > Physics.
• En cámaras 3D el plano far debe estar algunas unidades detrás del componente más lejano para asegurar que los Raycasts llegan a toda la pantalla (la distancia máxima se calcula como far – near).

Detección de objetos (Event Type, Event Mask):

• 2D / 3D: Determina si utiliza el raycast normal o el de Physics2D.
• UI: Detecta el objeto más cercano por orden de UIPanel o widget (Depth).
• World: Detecta el objeto con el collider físicamente más cercano a la cámara.
• La máscara limita la detección a los objetos de las capas indicadas.

Entradas:

• Mouse: el ratón normal. Los identificadores para los botones en UICamera.GetTouch son -1 izquierdo, -2 derecho, -3 central.
• Keyboard: el teclado. Se leen las direcciones horizontal-vertical de las flechas/WSAD y la tecla TAB. Las teclas definidas para Submit y Cancel en Axes and Keys no dependen de esta configuración, ni tampoco los controles que leen el teclado independientemente (ej. UIInput).
• Touch: los toques de dispositivos táctiles según la entrada estándard (Input.GetTouch). Los identificadores para UICamera.GetTouch son los fingerID de 0 en adelante, hasta el número de toques simultáneos que se quiera monitorizar.
• Controller: lee las direcciones horizontal-vertical de los ejes definidos en Axes and Keys. No registra toques.

Eventos:

• OnHover (isOver): el ratón pasa sobre un collider.
• OnPress (isDown): se pulsa un botón del ratón sobre el collider.
• OnSelect (selected): cuando un botón del ratón se suelta sobre el mismo objeto en que se pulsó.
• OnClick (): mismas condiciones que OnSelected, pero además el ratón no se ha movido mucho. UICamera.currentTouchID indica qué botón se ha pulsado.
• OnDoubleClick (): dos clicks repetidos en menos de un cuarto de segundo. UICamera.currentTouchID indica qué botón se ha pulsado.
• OnDragStart (): enviado al objeto “tocado” justo antes de comenzar las notificaciones OnDrag().
• OnDrag (Vector2 delta): enviado al objeto sobre el que se produce el arrastre. delta indica el desplazamiento en píxeles.
• OnDragOver (draggedObject): enviado a un objeto mientras otro está siendo arrastrado encima de su área.
• OnDragOut (draggedObject): enviado a un objeto cuando otro es arrastrado fuera de su área.
• OnDragEnd (): enviado al objeto arrastrado al finalizar el evento de arrastrar y soltar.
• OnInput (text): se envía al escribir texto (una vez se selecciona un collider pulsando en él).
• OnTooltip (show): enviado cuando el ratón se mantiene sobre un collider sin moverse durante cierto tiempo.
• OnScroll (float delta): se envía al mover la rueda del ratón.
• OnKey (KeyCode key): se envía con los eventos de teclado o controlador de entrada.

Los eventos son aplicables a cualquier script, no sólo componentes NGUI. Para recibir estos eventos en un script basta que el objeto tenga un Collider y el script implemente las funciones deseadas, por ejemplo:

void OnPress (bool isPressed)
    {
    if (isPressed) Debug.Log("Estoy pulsado!");
    else Debug.Log("Ya no estoy pulsado");
    }

UICamera expone métodos estáticos que se pueden consultar dentro del evento para obtener información detallada:

• UICamera.current: la instancia UICamera que envió el evento.
• UICamera.currentTouch: datos de la interacción que originó el evento.
• UICamera.currentTouchID: identificador de toque o botón de ratón para este evento. En ratón, -1 es botón derecho, -2 botón izquierdo y -3 botón central.
• UICamera.lastHit: último resultado RaycastHit antes de invocar el evento.
• UICamera.selectedObject: objeto seleccionado mediante OnSelect. Puede usarse para cambiar manualmente la selección entre los objetos del interface.

También expone métodos estáticos de utilidad :

• UICamera.IsPressed(GameObject): comprueba si el objeto indicado está siendo presionado por cualquier entrada (toque, botón, controlador).
• UICamera.GetTouch(id): obtener datos de un toque o interacción. -1, -2, -3 son los botones del ratón. De 0 en adelante son fingerId de toques en pantalla táctil. Siempre se devuelve un objeto MouseOrTouch válido. Para leer todos los toques activos se comprueban tantos identificadores como toques simultáneos se quieran registrar. Un toque está “activo” cuando MouseOrTouch.pressed != null.

Estructura avanzada

Interface que combina componentes 2D, componentes 3D, y elementos interactivos en la propia escena. NGUI demuestra esta solución en la escena de ejemplo “Example X – Character”.

 

Elemento en raiz	Layer	Componentes	UIPanel	Camera	UICamera
2D UI	2D	UIPanel, UIRoot.	depth 2	Orthographic, Don’t Clear, Mask “2D”, depth 2	Main UICamera, Events “3D UI”, Mask “2D”
3D UI	3D	UIPanel	depth 1	Perspective, Don’t Clear, Mask “3D”, depth 1	Events “3D UI”, Mask “3D”
Scene	Default	UIPanel	depth 0	Perspective, Mask “no 2D, no 3D”, depth 0	Events “3D UI”, Mask “no 2D, no 3D”

En este ejemplo el interface 2D tiene prioridad sobre el 3D, y éste a su vez tiene prioridad sobre la escena.

Detección de elementos bajo el ratón / toque

El proceso que sigue NGUI para detectar el elemento tocado o bajo el ratón es:

1. Se recorren las cámaras por orden de Depth. Cuando se ha detectado un elemento en una, no se comprueban las demás cámaras.
2. Desde cada cámara se utiliza un Raycast para localizar los colliders en la posición del ratón/toque coincidentes con Culling Mask (Camera) y Event Mask (UICamera). El collider que recibirá los eventos se escoge según Event Type de UICamera:

• 3D UI: Los widgets se ordenan por orden de Depth combinado con el del UIPanel al que pertenecen. Los colliders aislados (sin widget) se consideran Depth 0. El collider con mayor valor depth resultante es el que recibe los eventos.
• 3D World: Se escoge el collider más cercano a la cámara.

Nota: NGUI fuerza la capa (layer) de los widgets a la misma del panel del que dependen.

Interacción en NGUI

Los componentes interactivos exponen eventos que permiten invocar código cuando se producen. Se puede configurar en mismo componente indicando la función del componente que se desea invocar. Cada evento permite invocar uno o varios métodos públicos de cualquier componente o script. Si el método admite parámetros, éstos pueden ser cualquier propiedad pública de cualquier componente o script. Del ejemplo de la imagen:

public void DoAction (bool isTrue)
    {
    Debug.Log("He sido pulsado! Valor: " + isTrue);
    }

Es necesario que el tipo de los parámetros de la función invocada concuerde con el tipo de las propiedades indicadas, o se producirá un error en ejecución. Los componentes de NGUI tienen varias funciones predefinidas que se pueden invocar, por ejemplo PlayForward en los tweens.

Eventos por componente

• UIButton: OnClick
• UIInput: OnChange, OnSubmit, onValidate*
• UIPlayAnimation: OnFinished
• UIPlayTween: OnFinished
• UIPopupList: OnChange
• UIProgressBar, UISlider, UIScrollBar: OnChange, onDragFinished*
• UIToggle: OnChange
• UITweener: OnFinished

* Accesible desde código, es un delegado normal de C# (delegate).

Se puede notificar cualquier otro evento además de los predefinidos de cada componente añadiendo un componente UIEventTrigger:

• UIEventTrigger: OnClick, OnDoubleClick, OnPress, OnRelease, OnSelect, OnDeselect, OnHoverOver, OnHoverOut, OnDragOver, OnDragOut.

Interacción desde código

Con EventDelegate se añaden notificaciones a los eventos estándar que ofrecen los componentes:

void OnButtonClicked ()
    {
    //  ... acción al pulsar botón ...
    }

EventDelegate.Add(myButton.onClick, OnButtonClicked);

Con UIEventListener cualquier objeto con un Collider puede escuchar las notificaciones de NGUI. No es necesario que el objeto tenga un UIEventListener de antemano. Si no lo tiene se agrega en tiempo de ejecución:

UIEventListener.Get(gameObject).onClick += MyClickFunction;

Cada componente estándar de NGUI tiene un campo estático current que apunta al objeto concreto que generó el evento:

• UIButton.current
• UIEventTrigger.current
• UIInput.current
• UIPlayAnimation.current
• UIPlayTween.current
• UIPopupList.current
• UIProgressBar.current, UISlider.current, UIScrollBar.current
• UIToggle.current
• UITweener.current

UICamera.current apunta al componente UICamera que envió el evento, y además el campo estático UICamera.currentTouch contiene información detallada sobre la acción precisa que lo desencadenó: posición, delta, elemento actual, elemento anterior…

Nota importante: Los eventos OnFinished se lanzan después de que una acción diferida se ha completado (transición o animación), y por tanto los campos estáticos ya no reflejarán los datos que generaron el evento. Será necesario pasar la información necesaria como parámetro del evento.

Animaciones y efectos

Transiciones (Tweens)

Descripción | Referencia UITweener

NGUI incluye varias transiciones o tweens para añadir efectos visuales a los componentes del interface. Cada transición afecta a una o varias propiedades de los componentes (ancho, alto, transparencia, color…). Las transiciones añadidas a un objeto están activadas por defecto: se lanzarán al iniciar la ejecución. Para evitarlo basta desactivar el componente en el objeto.

Todas transiciones derivan de UITweener y comparten la misma funcionalidad:

• Campos From y To representando los valores inicial y final.
• Animation Curve: determina la interpolación precisa entre From y To.
• Duration: tiempo que llevará la transición, en segundos, con Start Delay de retardo antes de comenzar.
• Tween Group: permite diferenciar varios componentes Tween en el mismo objeto y lanzarlos de forma selectiva según ID. Por defecto (valor 0) se lanzan todas las transiciones en el objeto simultáneamente.

Exponen el evento OnFinished, que se lanza una vez completada la transición.

Transiciones en NGUI y componentes que admiten

• TweenAlpha: UIRect
• TweenColor: UIWidget, Material, Light
• TweenFOV: Camera
• TweenHeight: UIWidget, con notificación a UITable
• TweenOrtoSize: Camera
• TweenPosition: UIRect, Transform
• TweenRotation: Transform
• TweenScale: Transform, con notificación a UITable
• TweenTransform: Transform
• TweenVolume: AudioSource
• TweenWidth: UIWidget, con notificación a UITable

Lanzar transiciones

• Componente UIPlayTween (Attach > Play Tween Script) en cualquier elemento interactivo o collider.
• Invocando las funciones Play(), Toggle(), PlayForward() o PlayReverse() desde el código o desde un evento (ej. desde OnFinished).
• Creando una transición sobre la marcha en código mediante la función Begin(), por ejemplo:

  TweenPosition.Begin(targetGameObject, duration, targetPosition)

Se puede combinar la creación por código con la ejecución al terminar usando EventDelegate:

void OnTween1Complete ()
    {
    // ...se invoca al finalizar la transición...
    }

void MyButtonClicked ()
    {
    TweenScale tweenScale = TweenScale.Begin(gameObject, 0.2f, Vector3.one * 1.5f);
    EventDelegate.Add(tweenScale.onFinished, OnTween1Complete);
    }

UIPlayTween

Descripción | Referencia

Lanza una transición cuando se produce un evento. Requiere un Collider. Las transiciones se invocarán en el Target. Si hay más de una se lanzan todas, salvo que se indique un grupo en Tween Group. Include Children las desencadena también en los objetos hijos de Target. Trigger condition indica el evento que lanza la transición.

Los eventos de ida y vuelta (OnHover, OnPress, OnSelect, OnActivate) lanzan la transición en un sentido al “activarse” y en el otro al “desactivarse”. Play Direction invierte el sentido de la transición.

Expone el evento OnFinished, que se lanza una vez completada la transición.

UIPlayAnimation

Descripción | Referencia

Lanza una animación cuando se produce un evento. Es prácticamente idéntico a UIPlayTween, pero lanza animaciones de Unity en lugar de transiciones de NGUI. Requiere un Collider. La forma simple de añadir una animación a un componente es abrir el editor de animaciones de Unity (Ctrl-6), añadir una curva y escoger los componentes y propiedades a animar. Grabar las animaciones con el editor, y luego referenciarlas desde UIPlayAnimation.

Para reproducir animaciones desde código se pueden usar las funciones ActiveAnimation.Play(), por ejemplo:

ActiveAnimation.Play(targetAnimation, AnimationOrTween.Direction.Forward);

UIPlaySound

Reproduce un sonido cuando se produce un evento. Requiere un collider. Referencia

Componentes visuales

UIRect

Descripción | Referencia | Video

Los paneles y componentes (widgets) heredan de UIRect. No se puede instanciar directamente, pero implementa toda la funcionalidad de posicionamiento, dimensión y anclajes (Anchors). Es muy recomendable ver el video para entender cómo funciona.

Anclajes (Anchors)

Cada elemento de NGUI tiene un área modificable cuyos límites se  pueden anclar (anchor) a otros elementos o incluso a objetos 3D (Target). Con Unified se indica un sólo elemento, mientras que Advanced permite escoger un elemento para cada cara. Para establecer un anclaje, mueve el elemento a la posición y tamaño deseados, escoge el tipo de anclaje y arrastra en Target el elemento al que quieres anclarlo. Los valores del anclaje se rellenarán automáticamente.

Para que un elemento interior se mantenga siempre “dentro” de otro, hazlo hijo de ese elemento y escoge la opción Unified. El padre se escogerá automáticamente como Target y se configurarán los valores iniciales para tu comodidad. Entonces puedes ajustarlo desde la vista Scene o modificando las opciones.

Para cada cara se especifica un anclaje relativo al Target y un desplazamiento (offset) absoluto en pixels. El valor relativo puede ser uno de los predeterminados (Left, Right, Center, Top, Bottom) o una posición Custom cualquiera en el Target. El valor Custom es 0.0 para Left/Bottom, 0.5 para Center y 1.0 para Right/Top. La posición final de la cara es:

Final position = Target’s width or height * relative + absolute

Nota: El sistema de anclajes es siempre exacto con cámaras ortográficas (2D). Las cámaras con perspectiva aplican los anclajes dependiendo de la distancia Z de la cámara al interface y el aspect ratio de la vista.

UIWidget

Descripción | Referencia

El componente visual más básico del que heredan todos los demás elementos visuales del interface. Es sólo un rectángulo que se puede posicionar, dimensionar y anclar como se quiera. Tiene área pero es completamente invisible, por lo que es útil para contener a otros componentes al organizar la estructura del interface.

• Se puede mover, escalar y rotar con los botones de ajuste azules. Matener Ctrl pulsado para desactivar el ajuste automático (snapping) a bordes y otros componentes.
• Añadirle un Box Collider para recibir los eventos de NGUI. Se mostrará una nueva opción para ajustar automáticamente el tamaño del collider al componente.
• El valor de profundidad Depth determina el orden en que se recibirán los eventos y, en los componentes visuales, el orden de dibujado. En la vista de Scene, el menú contextual “Select” del componente muestra todos los elementos bajo el ratón ordenados por Depth.
• La posición y rotación del componente (transform.position, rotation) se establecen sobre su Pivot u origen. Para los componentes hijos el origen de coordenadas (0,0) se localiza en el Pivot del padre.

UITexture

Descripción | Referencia

El elemento visible más simple. Hereda toda la funcionalidad de UIWidget pero añade un elemento visual (textura) que se ajusta a las dimensiones del componente.

• Se puede escoger una textura (Texture) o un Material. Si se especifican ambos se usa esta textura en lugar de la que traiga el material. En vez de Material se puede indicar un Shader directamente.
• La opción “Make Pixel Perfect” del menú contextual ajusta el componente a las dimensiones originales de la textura.

El interface entero se puede hacer con UITextures y después crear un Atlas con ellas (más óptimo). Para ello se selecciona el objeto raíz del interface antes de crear el atlas en el Atlas Maker. Todas las texturas se combinan en el atlas y los objetos UITexture se sustituyen por UISprite.

UISprite

Descripción | Referencia

La piedra angular de los interfaces en NGUI. Muestra un Sprite extraído de un Atlas e incorpora toda la funcionalidad de UIWidget. Para usar los sprites es necesario crear primero un Atlas con el Atlas Maker. Un Atlas es un conjunto de sprites agrupados en la misma textura.

• El botón Edit configura el sprite dentro del Atlas. Permite establecer los bordes para el tipo de sprite Sliced.
• El tipo de sprite establece cómo se utiliza éste para rellenar el área de componente (Simple, Filled, Tiled, Sliced)
• La opción “Make Pixel Perfect” del menú contextual ajusta el componente a las dimensiones del sprite.

Para cambiar el sprite por código usar la propiedad spriteName:

UISprite sprite = GetComponent<UISprite>();
sprite.spriteName = "Un Sprite";

El nombre del sprite debe existir en el Atlas. Es sensible a mayúsculas/minúsculas.

UILabel

Descripción | Referencia

Es un UIWidget que muestra texto. Este componente requiere una fuente de letra (Font). La fuente puede ser dinámica (cogiendo una fuente de Unity) o puede ser una fuente Bitmap (una fuente pre-generada dentro de un Atlas).

• El Pivot del widget define la alineación vertical del texto. Alignment define la alineación horizontal.
• El tipo de fuente Dynamic permite indicar el tamaño de fuente directamente en el componente. También permite escoger el material para mostrar la fuente.
• El texto puede recibir un efecto de sombra o borde, pero a costa de multiplicar la geometría (x2 en sombra, x5 en borde).

La propiedad Overflow define qué ocurre cuando el texto se sale del área del widget:

• Shrink Content: reduce el tamaño del texto para que encaje dentro del componente. La calidad es mejor en fuentes dinámicas con Keep crisp activado porque se reduce el tamaño de la fuente en lugar de escalar el texto.
• Clamp Content: el texto que no entra se corta sin más.
• Resize Freely: ajusta el tamaño del componente al texto que contenga. No será posible redimensionar el componente manualmente.
• Resize Height: ajusta el alto del componente al texto, pero conserva el ancho constante.

Se pueden indicar códigos de color y BBCode para añadir decoraciones al texto:

[ff9900]Texto coloreado[-] [b]Negrita[/b] [i]Cursiva[/i] [s]Tachado[/s] [url=mensaje o url]Enlace clickable[/url] [sup]^superíndice[/sup] [sub]_subíndice[/sub]

Para cambiar el texto por código usar la propiedad text:

UILabel lbl = GetComponent<UILabel>();
lbl.text = "Hola Mundo!";

Para detectar los clicks en los enlaces en el texto (BBCode url) añadir al objeto un Collider y un script implementando OnClick:

void OnClick ()
    {
    UILabel lbl = GetComponent<UILabel>();
    string url = lbl.GetUrlAtPosition(UICamera.lastHit.point);
    Debug.Log("Clicked on: " + url);
    }

Componentes interactivos

UIButton

Descripción | Referencia

Componente simple que responde a los eventos hover, pressed y click. , y puede cambiar el color de un sprite (Target) y/o el propio sprite en base a esos eventos. Cualquier objeto con un Collider puede actuar como botón, tanto en el interface como en la escena. Normalmente el Target será un widget (sprite, label, texture), pero también puede ser una luz o incluso un renderer. Es buena idea poner UIButton en el mismo objeto que tiene el sprite de fondo del botón. Se puede usar ALT+SHIFT+C para crear un collider, y entonces activar “Box Collider” para que se ajuste automáticamente.

Expone el evento OnClick.

NGUI ofrece complementos a UIButton que incorporan efectos de desplazamiento, rotación y escala (UIButtonOffset, UIButtonRotation, UIButtonScale) así como la posibilidad de activar objetos remotos (UIButtonActivate).

UIToggle

Descripción | Referencia

Componente genérico que tiene dos estados: encendido y apagado (on / off). Permite crear checkboxes, pestañas, botones de selección, etc.  El componente en sí puede mostrar y ocultar un Sprite en función de su estado. En su forma básica, un toggle se compone de dos sprites, fondo (padre) y marca (hijo). El componente UIToggle va en el fondo, con el collider, y la marca se referencia en el parámetro Sprite de UIToggle. Para comportamientos más específicos (ej. cambios de color o de escala) debe añadirse un componente UIPlayTween respondiendo a OnActivate junto con las transiciones (Tweens) correspondientes.

Expone el evento OnChange.

• Se puede convertir en un grupo de selección con un identificador de grupo (Group).
• Para hacer pestañas, los sprites de fondo y marca son el mismo pero el de fondo siendo más oscuro (o el de marca más brillante).
• Para activar y desactivar objetos o componentes se pueden usar los scripts UIToggledObjects y UIToggledComponentes.

UIProgressBar

Descripción | Referencia

Componente que implementa una barra de progreso. Su valor se establece entre 0 y 1 con la propiedad Value. No es interactivo en sí mismo, pero sus variantes UISlider y UIScrollBar sí implementan interacción. Requiere al menos un widget Foreground o Background que delimite el área de la barra. Si se indican ambos se utiliza el Foreground. Se puede indicar un “mando” o Thumb opcional.

• El widget Foreground se escala proporcionalmente al valor actual de la barra.
• El Thumb se sitúa en la posición proporcional al valor actual de la barra. Puede ser cualquier Transform.
• El fondo Background se escala al tamaño de la barra.

Expone el evento OnValueChange.

• Para mostrar el valor o el porcentaje en un texto (UILabel) se pueden invocar los métodos UILabel.SetCurrentProgress o UILabel.SetCurrentPercent desde el evento OnValueChange.

UISlider

Descripción | Referencia

Es una barra de progreso que se puede tocar y arrastrar para cambiar su valor. Requiere un Collider para recibir los eventos del usuario. Por lo demás se muestra y funciona exactamente igual que UIProgressBar.

UIScrollBar

Descripción | Referencia

Es un slider cuyo recorrido depende del tamaño de la “zona visible” (Size). El widget Foreground se escala de acuerdo a ese tamaño, de forma que el valor entre 0 y 1 (Value) se refleja por la posición del Foreground.

UIPopupList

Descripción | Referencia

Componente que implementa una lista desplegable de opciones seleccionables. Se puede aplicar a cualquier Collider, generalmente junto con un UIButton. El campo Options configura las opciones que se mostrarán. La sección Atlas configura los sprites que se usarán como fondo de la lista (Background) y como marco de la selección (Highlight). La sección Font configura el texto para mostrar la lista de opciones. La propiedad value contiene el texto de la opción seleccionada.

El índice se puede obtener con items.IndexOf(value):

int selectedIndex = UIPopupList.current.items.IndexOf(UIPopupList.current.value);

Expone el evento OnValueChange.

• Para mostrar la selección actual en un texto (UILabel) se puede invocar el método UILabel.SetCurrentSelection desde el evento OnValueChange.
• Con Localized activado se indican las claves Key de traducción, que se sustituirán automáticamente por los textos localizados.

Componentes organizativos

UIScrollView

Descripción | Referencia

Convierte un panel (UIPanel) en una vista desplazable. El recuadro naranja muestra la extensión actual del contenido del panel.

1. Seleccionar el panel y escoger “Attach > Scroll View” del menú contextual.
2. Añadir componentes UIDragScrollView a todos los colliders que se quieran usar para desplazar el panel. Seleccionar cada collider y escoger “Attach > Drag Scroll view” del menú contextual. Si hay varios colliders (ej. componentes interactivos) todos deben tener su componente UIDragScrollView para que puedan mover el panel.

Se pueden especificar barras de desplazamiento (UIScrollBar) horizontal y/o vertical. Las barras de desplazamiento deben estar fuera del panel UIScrollView (no deben ser hijos de éste): Nota: añadir elementos a la vista en tiempo de ejecución requiere llamar a UIScrollView.UpdateScrollbars para que las barras se actualicen apropiadamente. Al desplazar la vista se puede centrar automáticamente en cada elemento. Para ello se agrupan éstos bajo un padre común con el componente UICenterOnChild: Para crear paneles de desplazamiento sin fin se utiliza el componente UIWrapContent:

UIGrid

Descripción | Referencia

Organiza los widgets hijos en una cuadrícula de posiciones de tamaño fijo. Funciona en el editor (comando “Execute” del menú contextual) y en ejecución. Se le puede añadir el componente UICenterOnChild cuando se usa dentro de un scroll view para que éste se centre en cada elemento automáticamente. Para organizar en posiciones de tamaño variable usar UITable.

UITable

Descripción | Referencia

Organiza los widgets hijos en celdas de tamaño variable, similar a las celdas de una tabla HTML. Funciona en el editor (comando  “Execute” del menú contextual) y en ejecución. Una tabla siempre se extiende hacia la derecha el número de columnas (Columns) indicado, entonces empezará una nueva línea por encima o por debajo en función de Direction.

• El orden por defecto será el de la creación de los objetos hijos, salvo que se indique otro orden.
• El Pivot de los hijos establece su alineación en las celdas de la tabla.
• Las transiciones TweenScale, TweenWidth y TweenHeight en los hijos notifican a la tabla, de forma que los demás objetos se reposicionarán dinámicamente según sea necesario.

Para organizar en celdas de tamaño fijo usar UIGrid.

Componentes de entrada de texto y teclado

UIInput

Descripción | Referencia

Implementa un cuadro de entrada donde se el usuario puede escribir texto. La forma más simple para un cuadro de entrada es un sprite o widget como fondo y un UIlabel hijo, que se referencia desde el campo Label. En el sprite se añaden el Collider y el UIInput. El valor actual en la entrada se guarda en UIInput.value.

Expone los eventos OnChange, OnSubmit.

• Saved As guarda automáticamente el valor del campo en PlayerPrefs de Unity bajo la clave indicada.
• Select On Tab indica el objeto al que se pasará la selección cuando se pulse Tab. El cambio de selección también se puede forzar en el código, por ejemplo desde el evento OnSubmit:

  UICamera.selectedObject = UIInput.current.selectOnTab;

• El campo estático UIInput.selection apunta al UIInput seleccionado, si hay alguno.
• Para leer el valor desde los eventos se utiliza UIInput.current.value.
• Se puede adjuntar un script UIKeyBinding para seleccionar la entrada si se pulsa una tecla.

Configuración aplicable al UILabel:

• Max Lines = 1 limita la entrada a una sola línea
• El texto (text) será el placeholder que se muestre cuando no hay entrada (ej. “escribe nombre aquí”).
• Normalmente la propiedad Overflow se deja en Clamp Content para que el texto se desplace correctamente cuando el usuario escribe más allá del ancho de la entrada.

 

(próximamente) UIKeyBinding, UIKeyNavigation

Contenidos y enlace de datos

Localización / Multi-idioma

Descripción | Referencia UILocalize | Referencia Localization

Para configurar múltiples idiomas basta crear un fichero CSV con todos los textos, y añadir el componente UILocalize a los textos y sprites que deben ser localizados.

• La primera columna es para las claves (keys) que se usarán en el campo Key del componente UILocalize.
• Las demás columnas son una por cada idioma, y contienen los textos localizados a cada uno.
• La primera fila contiene KEY¹ en la primera celda y los nombres de los idiomas^2,3 en las demás.

El fichero debe llamarse Localization.csv y debe estar en una carpeta Resources dentro del proyecto. Para localizar cualquier texto o sprite, añadirle el componente UILocalize e indicar la clave (Key) definida en el fichero CSV. El campo Key de UILocalize tiene autocompletado, de forma que basta comenzar a escribir la clave para obtener una lista de las claves disponibles. La sección Preview muestra los valores correspondientes a la clave seleccionada.

Se puede cambiar el idioma en la aplicación añadiendo un componente LanguageSelection a una lista desplegable (UIPopupList) o bien desde código, indicando el nombre del idioma definido en la primera fila del CSV:

Localization.language = "Spanish";

También es posible utilizar el sistema de localización desde código, indicando una clave de la primera columna del CSV:

string localizedString = Localization.Get("key");

 

(próximamente) Data Binding, UISavedOption