Detectores de arrastre de UI

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

• Coloca un UIDragDetector bajo cualquier instancia de GuiObject para hacerlo arrastrable a través de todas las entradas de 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 ejes, límites de 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.

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

Hacer que los elementos de la UI sean arrastrables

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

1. En la ventana del Explorador, pasa el mouse sobre la instancia de GuiObject y haz clic en el botón ⊕. Se mostrará un menú contextual.

2. Desde el menú, inserta un UIDragDetector.

   

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

Personalizar los detectores de arrastre de UI

Estilo de arrastre

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

Dirección del arrastre

Por defecto, el movimiento 2D y el DragStyle asociado se asignan 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 según desees, sin que el padre del detector ejecute el movimiento propuesto.

Límites de traslación y rotación

Por defecto, no hay límites al movimiento 2D más allá de las restricciones inherentes del DragStyle. Se pueden declarar límites tanto para las traslaciones como para las rotaciones mínimas y máximas con las siguientes propiedades si así lo deseas. Además, puedes definir cómo está restringido el objeto arrastrado dentro de los límites de un GuiObject específico 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 al clic y arrastre

A través de señales de eventos, cambios de propiedad, estilo de arrastre Scriptable, y funciones personalizadas, los scripts pueden responder a la manipulación de elementos de UI arrastrados para impulsar diversas configuraciones o tomar decisiones lógicas, como controles deslizantes que ajustan el volumen de la música y los 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 control deslizante 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 al ancho completo del contenedor sin scripts adicionales.

UIDragDetector - Cambio de Transparencia por Señal de Evento
-- 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  -- Configura 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 de la manija
sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale

-- Aumenta el borde de la manija 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 de la manija para indicar el fin 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 a las propiedades DragUDim2 y/o DragRotation del detector directamente.

El siguiente detector tiene su DragStyle configurado en Rotate, lo que permite a los usuarios arrastrar la manija alrededor del anillo de rotación de matiz, mientras se detectan cambios en la rotación de arrastre a través de Instance:GetPropertyChangedSignal().

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

uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.Rotate  -- Configura el estilo de arrastre en 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 según la rotación de la manija
changeHue()

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

Estilo de arrastre scriptado

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 float (rotación). El detector actualizará el objeto a la posición/rotación computada en base a los retornos, la propiedad DragSpace y la propiedad DragRelativity.

Por defecto, los UDim2 y float devueltos serán la posición/rotación final deseada en el espacio local del padre del detector. Las restricciones existentes de traslación/rotación aún se aplicarán, al igual que los límites impuestos por una instancia específica de BoundingUI.

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

UIDragDetector - Arrastre Siguiendo Onda Sinusoidal
local frame = script.Parent  -- Elemento de UI a arrastrar
local uiDragDetector = frame:FindFirstChildWhichIsA("UIDragDetector")

local initialXValue = 0
local maxHeightChange = 200
local pixelsPerRadian = 75  -- Disminuye 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 vaya "hacia arriba" en la pantalla con 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

Los UIDragDetectors no tienen reglas de movimiento incorporadas 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 limitación existente de traslación/rotación.

El siguiente ejemplo utiliza una función de restricción que limita el arrastre planar en una cuadrícula X/Y basado 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 cuadrícula.

UIDragDetector - Arrastre en una Cuadrícula, Ajustando a los Azulejos
-- La jerarquía es GridContainer ⟩ Handle ⟩ UIDragDetector ⟩ (este script)
local gridContainer = script.Parent.Parent.Parent
local handle = gridContainer:FindFirstChild("Handle")  -- Elemento de UI a arrastrar
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.ResponseStyle = Enum.UIDragDetectorResponseStyle.Scale  -- Configura 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)