Detectores de arrasto de UI

A instância UIDragDetector facilita e incentiva a interação com elementos de interface do usuário 2D em um jogo, 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 eixo, movimento ou limites de arrasto.

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

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

Tornar 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 de 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 LayerCollector.

Personalizar 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 é restringido dentro dos limites de um GuiObject especificado, como um Frame.

Ajustes de velocidade

Através de SelectionModeDragSpeed e SelectionModeRotateSpeed, você pode ajustar as velocidades máximas 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

Através 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 slider 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 necessidade de script adicional.

-- 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  -- Define arrasto por escala
uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.TranslateLine  -- Restringe arrasto a linha
uiDragDetector.BoundingUI = sliderContainer

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

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

-- Muda a transparência de acordo com quanto foi arrastado em escala
uiDragDetector.DragContinue:Connect(function(inputPosition)
	sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale
end)

-- Reverte a borda da alça 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 a alça ao redor do anel rotativo de matiz, enquanto detectam mudanças na rotação de arrasto através de Instance:GetPropertyChangedSignal().

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 matiz para a rotação da alça
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 um 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 final desejada no espaço local do pai do detector. Limites de tradução/rotação existentes ainda se aplicarão, assim como limites de contorno 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 está definido como Enum.UIDragDetectorDragSpace.Relative.

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

local initialXValue = 0
local maxHeightChange = 200
local pixelsPerRadian = 75  -- Diminua 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 na tela com a mudança positiva de Y
	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 posições para incrementos específicos ou definir áreas de movimento permitidas. Note 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.

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