Detectores de arrastre de UI

La instancia UIDragDetector facilita y fomenta la interacción con elementos de la interfaz de usuario 2D en un juego, como deslizadores, giradores y más. Las características clave incluyen:

• Coloca un UIDragDetector debajo de cualquier instancia de GuiObject para hacerlo arrastrable a través de todas las entradas del usuario sin una sola línea de código.

• Elige entre varias opciones de DragStyle, define cómo el objeto responde al movimiento a través de ResponseStyle, y opcionalmente aplica límites de eje, movimiento o límites de arrastre.

• Los scripts pueden responder a la manipulación de objetos arrastrados para impulsar respuestas lógicas, como ajustar configuraciones.

• UIDragDetectors funcionan en el modo de edición y juego de Studio siempre que no estés utilizando las herramientas de Seleccionar, Mover, Escalar o Rotar, ni ciertos complementos o herramientas del editor de UI de Studio.

Hacer que los elementos de UI sean arrastrables

Para hacer que cualquier instancia de GuiObject sea arrastrable, simplemente agrega un UIDragDetector como un descendiente directo.

1. En la ventana de Explorer, pasa el cursor sobre la instancia de GuiObject y haz clic en el botón ⊕. Se muestra un menú contextual.

2. Desde el menú, inserta un UIDragDetector.

   

3. Por defecto, el objeto ahora será arrastrable en la interfaz de LayerCollector.

Personalizar los detectores de arrastre de UI

Estilo de arrastre

UIDragDetectors mapean el movimiento del cursor para calcular el movimiento 2D propuesto y/o la rotación. A través de la propiedad DragStyle, puedes elegir entre diferentes mapeos para adaptarse a tus necesidades. Por ejemplo, Enum.UIDragDetectorDragStyle.TranslatePlane produce traducción en el plano 2D del LayerCollector, mientras que Enum.UIDragDetectorDragStyle.Rotate normalmente produce una rotación en lugar de traducción.

Dirección de arrastre

Por defecto, el movimiento 2D y el DragStyle asociado se mapean al espacio del ancestro LayerCollector. Sin embargo, es posible que desees cambiar el ReferenceUIInstance o el DragAxis al construir diferentes componentes de UI.

Respuesta al movimiento

La propiedad UIDragDetector.ResponseStyle especifica cómo se cambia el valor de posición de un objeto por el movimiento propuesto. Los estilos de respuesta personalizados te permiten usar los valores resultantes de UIDragDetector.DragUDim2 y UIDragDetector.DragRotation como desees, sin que el padre del detector ejecute el movimiento propuesto.

Límites de traducción y rotación

Por defecto, no hay límites para el movimiento 2D más allá de las restricciones inherentes del DragStyle. Se pueden declarar límites tanto para las traducciones mínimas como máximas y rotaciones con las siguientes propiedades si se desea. Además, puedes definir cómo se restringe el objeto arrastrado dentro de los límites de un GuiObject especificado, como un Frame.

Ajustes de velocidad

A través de SelectionModeDragSpeed y SelectionModeRotateSpeed, puedes ajustar la velocidad máxima de arrastre/rotación para un detector. Además, a través de UIDragSpeedAxisMapping, puedes ajustar las velocidades de arrastre en las dimensiones X/Y, basadas en la SelectionModeDragSpeed del detector.

Respuestas de script a clics y arrastres

A través de señales de eventos, cambios de propiedades, estilo de arrastre Scriptable, y funciones personalizadas, los scripts pueden responder a la manipulación de elementos de UI arrastrados para impulsar varias configuraciones o tomar decisiones lógicas, como deslizadores que ajustan el volumen de música y efectos de sonido por separado.

Señales de eventos

A través de las siguientes señales de eventos, puedes detectar cuándo un usuario comienza, continúa y termina de arrastrar un objeto.

El siguiente deslizador designa su contenedor como el BoundingUI para limitar su movimiento dentro del área del contenedor, permitiendo que el arrastre basado en escala TranslateLine se limite a todo el ancho del contenedor sin scripting adicional.

-- La jerarquía es SliderContainer ⟩ Handle ⟩ UIDragDetector ⟩ (este script)
local sliderContainer = script.Parent.Parent.Parent
local handle = sliderContainer:FindFirstChild("Handle")
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.ResponseStyle = Enum.UIDragDetectorResponseStyle.Scale  -- Establecer arrastre por escala
uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.TranslateLine  -- Restringe el arrastre a una línea
uiDragDetector.BoundingUI = sliderContainer

-- Inicialmente establece la transparencia del contenedor al valor de escala X del mango
sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale

-- Expande el borde del mango para indicar el inicio del agarre
uiDragDetector.DragStart:Connect(function(inputPosition)
	handle:FindFirstChildWhichIsA("UIStroke").Thickness = 6
end)

-- Cambia la transparencia según cuánto se arrastró en escala
uiDragDetector.DragContinue:Connect(function(inputPosition)
	sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale
end)

-- Revierte el borde del mango para indicar el final del agarre
uiDragDetector.DragEnd:Connect(function(inputPosition)
	handle:FindFirstChildWhichIsA("UIStroke").Thickness = 4
end)

Cambios de posición y rotación

Además de señales de eventos, puedes monitorear cambios en las propiedades DragUDim2 y/o DragRotation del detector directamente.

El siguiente detector tiene su DragStyle configurado en Rotate, permitiendo a los usuarios arrastrar el mango alrededor del anillo rotador de matiz, mientras detecta cambios en la rotación de arrastre a través de Instance:GetPropertyChangedSignal().

local handle = script.Parent.Parent  -- Elemento de UI para arrastrar
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.Rotate  -- Establecer estilo de arrastre a rotar

local function changeHue()
	local currAngle = (math.fmod(handle.Rotation, 360)) / 360
	if currAngle < 0 then
		currAngle += 1
	end
	handle.BackgroundColor3 = Color3.fromHSV(currAngle, 1, 1)
end

-- Inicialmente establece el matiz a la rotación del mango
changeHue()

-- Conecta la función a GetPropertyChangedSignal() de la rotación de arrastre del detector
uiDragDetector:GetPropertyChangedSignal("DragRotation"):Connect(changeHue)

Estilo de arrastre programado

Si configuras el UIDragDetector.DragStyle de un detector en Enum.UIDragDetectorDragStyle.Scriptable, puedes proporcionar tu propia función que tome un Vector2 de la posición de entrada y devuelva un UDim2 (posición) y un flotante (rotación). El detector actualizará el objeto a la posición/rotación calculada en función de los retornos, la propiedad DragSpace, y la propiedad DragRelativity.

Por defecto, el UDim2 y el flotante devueltos serán la posición/rotación final deseada en el espacio local del padre del detector. Los límites de traducción/rotación existentes aún se aplicarán, así como los límites de frontera impuestos por una instancia de BoundingUI especificada.

El siguiente ejemplo arrastra un elemento de UI siguiendo una onda sinusoidal calculada por el cambio en la coordenada X de entrada. Ten en cuenta que el DragSpace del detector está configurado en Enum.UIDragDetectorDragSpace.Relative.

local frame = script.Parent  -- Elemento de UI para arrastrar
local uiDragDetector = frame:FindFirstChildWhichIsA("UIDragDetector")

local initialXValue = 0
local maxHeightChange = 200
local pixelsPerRadian = 75  -- Baja este valor para aumentar la frecuencia

uiDragDetector.DragStart:Connect(function(inputPosition)
	initialXValue = inputPosition.X
end)

local function computeSinWaveCoordinate(inputPosition)
	local deltaX = inputPosition.X - initialXValue
	-- Delta Y negativo para que suba en la pantalla con un cambio positivo en Y
	local deltaY = -math.sin(deltaX / pixelsPerRadian) * maxHeightChange
	return UDim2.fromOffset(deltaX, deltaY)
end

uiDragDetector:SetDragStyleFunction(computeSinWaveCoordinate)

Función de restricción personalizada

UIDragDetectors no tienen reglas de movimiento integradas sobre cuadrículas y ajuste, pero puedes registrar funciones de restricción personalizadas para editar el UIDragDetector.DragUDim2 y UIDragDetector.DragRotation del detector antes de que se apliquen. Por ejemplo, puedes mantener el movimiento en una cuadrícula redondeando posiciones a incrementos específicos, o definir áreas de movimiento permitidas. Ten en cuenta que esto se aplica antes de cualquier límite de traducción/rotación existente.

El siguiente ejemplo utiliza una función de restricción que limita el arrastre plano en una cuadrícula X/Y basada en el número de filas y columnas. Ten en cuenta que el ResponseStyle del detector está configurado en Enum.UIDragDetectorResponseStyle.Scale y su BoundingUI está configurado en el contenedor de la cuadrícula.

-- La jerarquía es GridContainer ⟩ Handle ⟩ UIDragDetector ⟩ (este script)
local gridContainer = script.Parent.Parent.Parent
local handle = gridContainer:FindFirstChild("Handle")  -- Elemento de UI para arrastrar
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.ResponseStyle = Enum.UIDragDetectorResponseStyle.Scale  -- Establecer arrastre por escala
uiDragDetector.DragRelativity = Enum.UIDragDetectorDragRelativity.Relative
uiDragDetector.BoundingUI = gridContainer

local NUM_COLUMNS = 10
local NUM_ROWS = 5

local xScaleIncrement = 1 / NUM_COLUMNS
local yScaleIncrement = 1 / NUM_ROWS
local initialParentPosition = uiDragDetector.Parent.Position

uiDragDetector.DragStart:Connect(function()
	initialParentPosition = uiDragDetector.Parent.Position
end)

local function dragToGridOnly(proposedPosition, proposedRotation)
	local griddedXScale = math.round(proposedPosition.X.Scale / xScaleIncrement) * xScaleIncrement
	local griddedYScale = math.round(proposedPosition.Y.Scale / yScaleIncrement) * yScaleIncrement

	return UDim2.fromScale(griddedXScale, griddedYScale), proposedRotation
end

uiDragDetector:AddConstraintFunction(1, dragToGridOnly)