Detectores de arrasto de UI

A instância UIDragDetector facilita e incentiva a interação com elementos de interface de usuário 2D em uma experiência, como deslizadores, giradores e mais. As principais características incluem:

• Coloque um UIDragDetector sob qualquer instância de GuiObject para torná-lo arrastável via todas as entradas do usuário sem uma única linha de código.

• Escolha entre várias opções de DragStyle, defina como o objeto responde ao movimento via ResponseStyle, e aplique opcionalmente limites de eixos, movimento ou limites de arrasto.

• Scripts podem reagir à manipulação de objetos arrastados para acionar respostas lógicas, como ajustar configurações.

• UIDragDetectors funcionam no modo de edição e jogo do Studio, desde que você não esteja usando as ferramentas Selecionar, Mover, Escalar ou Rotacionar, nem certos plugins ou ferramentas do editor UI do Studio.

Torne elementos de UI arrastáveis

Para tornar qualquer instância de GuiObject arrastável, basta adicionar um UIDragDetector como um descendente direto.

1. Na janela Explorer, passe o mouse sobre a instância GuiObject e clique no botão ⊕. Um menu contextual será exibido.

2. No menu, insira um UIDragDetector.

   

3. Por padrão, o objeto agora será arrastável na interface do LayerCollector.

Personalize os detectores de arrasto de UI

Estilo de arrasto

UIDragDetectors mapeiam o movimento do cursor para calcular o movimento 2D proposto e/ou rotação. Através da propriedade DragStyle, você pode escolher entre diferentes mapeamentos para atender às suas necessidades. Por exemplo, Enum.UIDragDetectorDragStyle.TranslatePlane produz tradução no plano 2D do LayerCollector, enquanto Enum.UIDragDetectorDragStyle.Rotate normalmente produz uma rotação em vez de tradução.

Direção do arrasto

Por padrão, o movimento 2D e o DragStyle associado mapeiam para o espaço do ancestral LayerCollector. No entanto, você pode querer mudar o ReferenceUIInstance ou o DragAxis ao construir diferentes componentes de UI.

Resposta ao movimento

A propriedade UIDragDetector.ResponseStyle especifica como o valor da posição de um objeto é alterado pelo movimento proposto. Os estilos de resposta personalizados permitem que você use os valores resultantes de UIDragDetector.DragUDim2 e UIDragDetector.DragRotation conforme desejado, sem que o pai do detector execute o movimento proposto.

Limites de tradução e rotação

Por padrão, não há limites para o movimento 2D além das restrições inerentes do DragStyle. Limites para traduções e rotações mínimas e máximas podem ser declarados com as seguintes propriedades, se desejado. Além disso, você pode definir como o objeto arrastado é restrito dentro dos limites de um GuiObject específico, como um Frame.

Ajustes de velocidade

Por meio de SelectionModeDragSpeed e SelectionModeRotateSpeed, você pode ajustar a velocidade máxima de arrasto/rotação para um detector. Além disso, através de UIDragSpeedAxisMapping, você pode ajustar as velocidades de arrasto nas dimensões X/Y, com base na SelectionModeDragSpeed do detector.

Respostas de script ao clicar e arrastar

Por meio de sinais de eventos, mudanças de propriedades, estilo de arrasto Scriptable, e funções personalizadas, scripts podem responder à manipulação de elementos de UI arrastados para acionar várias configurações ou tomar decisões lógicas, como deslizadores que ajustam o volume de música e efeitos sonoros separadamente.

Sinais de eventos

Através dos seguintes sinais de eventos, você pode detectar quando um usuário começa, continua e termina de arrastar um objeto.

O seguinte deslizador designa seu contêiner como o BoundingUI para limitar seu movimento dentro da área do contêiner, permitindo que o arrasto baseado em escala TranslateLine seja limitado à largura total do contêiner sem script adicional.

UIDragDetector - Mudança de Sinal de Evento de Transparência
-- A hierarquia é 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  -- Definir arrasto por escala
uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.TranslateLine  -- Restringe o arrasto a uma linha
uiDragDetector.BoundingUI = sliderContainer

-- Inicialmente define a transparência do contêiner para o valor de escala X do manipulador
sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale

-- Expande a borda do manipulador para indicar o início do arrasto
uiDragDetector.DragStart:Connect(function(inputPosition)
	handle:FindFirstChildWhichIsA("UIStroke").Thickness = 6
end)

-- Muda a transparência pela quantidade que foi arrastada em escala
uiDragDetector.DragContinue:Connect(function(inputPosition)
	sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale
end)

-- Reverte a borda do manipulador para indicar o fim do arrasto
uiDragDetector.DragEnd:Connect(function(inputPosition)
	handle:FindFirstChildWhichIsA("UIStroke").Thickness = 4
end)

Mudanças de posição e rotação

Além dos sinais de eventos, você pode monitorar mudanças nas propriedades DragUDim2 e/ou DragRotation do detector diretamente.

O seguinte detector tem seu DragStyle definido como Rotate, permitindo que os usuários arrastem o manipulador ao redor do anel de rotator de matiz, tudo enquanto detecta mudanças na rotação de arrasto através de Instance:GetPropertyChangedSignal().

UIDragDetector - Mudança de DragRotation
local handle = script.Parent.Parent  -- Elemento de UI a ser arrastado
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.Rotate  -- Define o estilo de arrasto para rotacionar

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 define a cor do matiz para a rotação do manipulador
changeHue()

-- Conecta a função ao GetPropertyChangedSignal() da rotação de arrasto do detector
uiDragDetector:GetPropertyChangedSignal("DragRotation"):Connect(changeHue)

Estilo de arrasto scriptado

Se você definir o UIDragDetector.DragStyle de um detector como Enum.UIDragDetectorDragStyle.Scriptable, você pode fornecer sua própria função que recebe uma Vector2 da posição de entrada e retorna um UDim2 (posição) e um float (rotação). O detector atualizará o objeto para a posição/rotação computada com base nos retornos, na propriedade DragSpace e na propriedade DragRelativity.

Por padrão, o UDim2 e o float retornados serão a posição/rotação desejada final no espaço local do pai do detector. Limites de tradução/rotação existentes ainda se aplicarão, assim como limites de valor impostos por uma instância de BoundingUI especificada.

O seguinte exemplo arrasta um elemento de UI seguindo uma onda senoidal computada pela mudança na coordenada X de entrada. Note que o DragSpace do detector é definido como Enum.UIDragDetectorDragSpace.Relative.

UIDragDetector - Arrasto Seguindo Onda Senoidal
local frame = script.Parent  -- Elemento de UI a ser arrastado
local uiDragDetector = frame:FindFirstChildWhichIsA("UIDragDetector")

local initialXValue = 0
local maxHeightChange = 200
local pixelsPerRadian = 75  -- Reduza este valor para aumentar a frequência

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

local function computeSinWaveCoordinate(inputPosition)
	local deltaX = inputPosition.X - initialXValue
	-- Delta Y negativo para que suba "para cima" na tela com uma mudança Y positiva
	local deltaY = -math.sin(deltaX / pixelsPerRadian) * maxHeightChange
	return UDim2.fromOffset(deltaX, deltaY)
end

uiDragDetector:SetDragStyleFunction(computeSinWaveCoordinate)

Função de restrição personalizada

UIDragDetectors não têm regras de movimento integradas sobre grades e encaixes, mas você pode registrar funções de restrição personalizadas para editar o UIDragDetector.DragUDim2 e UIDragDetector.DragRotation do detector antes que sejam aplicadas. Por exemplo, você pode manter o movimento em uma grade arredondando as posições para incrementos específicos, ou definir áreas de movimento permitidas. Observe que isso é aplicado antes de quaisquer limites de tradução/rotação existentes.

O seguinte exemplo utiliza uma função de restrição que limita o arrasto planar em uma grade X/Y com base no número de linhas e colunas. Note que o ResponseStyle do detector está definido como Enum.UIDragDetectorResponseStyle.Scale e seu BoundingUI está definido como o contêiner da grade.

UIDragDetector - Arrastando em Grade, Encaixando em Ladrilhos
-- A hierarquia é GridContainer ⟩ Handle ⟩ UIDragDetector ⟩ (este script)
local gridContainer = script.Parent.Parent.Parent
local handle = gridContainer:FindFirstChild("Handle")  -- Elemento de UI a ser arrastado
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

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