Rilevatori di trascinamento UI

L'istanza UIDragDetector facilita e incoraggia l'interazione con gli elementi dell'interfaccia utente 2D in un gioco, come cursori, spinner e altro. Le caratteristiche principali includono:

• Posizionare un UIDragDetector sotto qualsiasi istanza di GuiObject per renderlo trascinabile tramite tutti gli input dell'utente senza una singola riga di codice.

• Scegliere tra diverse opzioni di DragStyle, definire come l'oggetto risponde al movimento tramite ResponseStyle, e applicare facoltativamente assi, limiti di movimento o confini di trascinamento.

• Gli script possono rispondere alla manipolazione degli oggetti trascinati per guidare risposte logiche, come l'aggiustamento delle impostazioni.

• I UIDragDetectors funzionano in modalità modifica e riproduzione di Studio finché non si utilizza gli strumenti Seleziona, Sposta, Scala o Ruota, né determinati plugin o strumenti dell'editor UI di Studio.

Rendere gli elementi UI trascinabili

Per rendere qualsiasi istanza di GuiObject trascinabile, basta aggiungere un UIDragDetector come discendente diretto.

1. Nella finestra Explorer, passa il mouse sopra l'istanza di GuiObject e fai clic sul pulsante ⊕. Viene visualizzato un menu contestuale.

2. Dal menu, inserisci un UIDragDetector.

   

3. Per impostazione predefinita, l'oggetto sarà ora trascinabile nell'interfaccia di LayerCollector.

Personalizzare i rilevatori di trascinamento UI

Stile di trascinamento

I UIDragDetectors mappano il movimento del cursore per calcolare il movimento 2D proposto e/o la rotazione. Tramite la proprietà DragStyle, puoi scegliere tra diverse mappature per soddisfare le tue esigenze. Ad esempio, Enum.UIDragDetectorDragStyle.TranslatePlane produce una traduzione nel piano 2D del LayerCollector, mentre Enum.UIDragDetectorDragStyle.Rotate produce normalmente una rotazione invece di una traduzione.

Direzione di trascinamento

Per impostazione predefinita, il movimento 2D e il relativo DragStyle si mappano nello spazio dell'antenato LayerCollector. Tuttavia, potresti voler cambiare il ReferenceUIInstance o il DragAxis quando costruisci diversi componenti UI.

Risposta al movimento

La proprietà UIDragDetector.ResponseStyle specifica come il valore di posizione di un oggetto viene modificato dal movimento proposto. Gli stili di risposta personalizzati ti consentono di utilizzare i valori risultanti di UIDragDetector.DragUDim2 e UIDragDetector.DragRotation come desideri, senza che il genitore del rilevatore esegua il movimento proposto.

Limiti di traduzione e rotazione

Per impostazione predefinita, non ci sono limiti al movimento 2D oltre le restrizioni intrinseche dello DragStyle. I limiti per le traduzioni e le rotazioni minime e massime possono essere dichiarati con le seguenti proprietà se desiderato. Inoltre, puoi definire come l'oggetto trascinato è vincolato all'interno dei confini di un GuiObject specificato come un Frame.

Regolazioni della velocità

Attraverso SelectionModeDragSpeed e SelectionModeRotateSpeed, puoi affinare le velocità massime di trascinamento/rotazione per un rilevatore. Inoltre, tramite UIDragSpeedAxisMapping, puoi affinare le velocità di trascinamento nelle dimensioni X/Y, basate sulla SelectionModeDragSpeed del rilevatore.

Risposte degli script ai clic e al trascinamento

Attraverso segnali di eventi, modifiche di proprietà, stile di trascinamento Scriptable, e funzioni personalizzate, gli script possono rispondere alla manipolazione degli elementi UI trascinati per guidare varie impostazioni o prendere decisioni logiche, come cursori che regolano separatamente il volume della musica e degli effetti sonori.

Segnali di eventi

Attraverso i seguenti segnali di eventi, puoi rilevare quando un utente inizia, continua e termina di trascinare un oggetto.

Il seguente cursore designa il suo contenitore come BoundingUI per limitare il suo movimento all'interno dell'area del contenitore, consentendo al trascinamento basato sulla scala TranslateLine di essere limitato all'intera larghezza del contenitore senza scripting aggiuntivo.

-- Gerarchia è SliderContainer ⟩ Handle ⟩ UIDragDetector ⟩ (questo script)
local sliderContainer = script.Parent.Parent.Parent
local handle = sliderContainer:FindFirstChild("Handle")
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.ResponseStyle = Enum.UIDragDetectorResponseStyle.Scale  -- Imposta il trascinamento per scala
uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.TranslateLine  -- Limita il trascinamento a una linea
uiDragDetector.BoundingUI = sliderContainer

-- Imposta inizialmente la trasparenza del contenitore al valore di scala X della maniglia
sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale

-- Espandi il bordo della maniglia per indicare l'inizio della presa
uiDragDetector.DragStart:Connect(function(inputPosition)
	handle:FindFirstChildWhichIsA("UIStroke").Thickness = 6
end)

-- Cambia la trasparenza in base a quanto è stato trascinato in scala
uiDragDetector.DragContinue:Connect(function(inputPosition)
	sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale
end)

-- Ripristina il bordo della maniglia per indicare la fine della presa
uiDragDetector.DragEnd:Connect(function(inputPosition)
	handle:FindFirstChildWhichIsA("UIStroke").Thickness = 4
end)

Cambiamenti di posizione e rotazione

In aggiunta ai segnali di eventi, puoi monitorare i cambiamenti alle proprietà DragUDim2 e/o DragRotation del rilevatore direttamente.

Il seguente rilevatore ha il suo DragStyle impostato su Rotate, consentendo agli utenti di trascinare la maniglia attorno all'anello rotante dell'hue, tutto mentre si rilevano i cambiamenti alla rotazione di trascinamento tramite Instance:GetPropertyChangedSignal().

local handle = script.Parent.Parent  -- Elemento UI da trascinare
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.Rotate  -- Imposta lo stile di trascinamento su ruotare

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

-- Imposta inizialmente il colore dell'hue alla rotazione della maniglia
changeHue()

-- Collega la funzione a GetPropertyChangedSignal() della rotazione di trascinamento del rilevatore
uiDragDetector:GetPropertyChangedSignal("DragRotation"):Connect(changeHue)

Stile di trascinamento scriptato

Se imposti lo UIDragDetector.DragStyle di un rilevatore su Enum.UIDragDetectorDragStyle.Scriptable, puoi fornire la tua funzione che accetta un Vector2 della posizione di input e restituisce un UDim2 (posizione) e un float (rotazione). Il rilevatore aggiornerà l'oggetto alla posizione/rotazione calcolata in base ai ritorni, alla proprietà DragSpace, e alla proprietà DragRelativity.

Per impostazione predefinita, il UDim2 e il float restituiti saranno la posizione/rotazione finale desiderata nello spazio locale del genitore del rilevatore. I limiti di traduzione/rotazione esistenti si applicheranno ancora, così come i limiti di confine imposti da un'istanza specificata di BoundingUI.

Il seguente esempio trascina un elemento UI seguendo un'onda sinusoidale calcolata dal cambiamento nella coordinata X di input. Nota che lo DragSpace del rilevatore è impostato su Enum.UIDragDetectorDragSpace.Relative.

local frame = script.Parent  -- Elemento UI da trascinare
local uiDragDetector = frame:FindFirstChildWhichIsA("UIDragDetector")

local initialXValue = 0
local maxHeightChange = 200
local pixelsPerRadian = 75  -- Abbassa questo valore per aumentare la frequenza

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

local function computeSinWaveCoordinate(inputPosition)
	local deltaX = inputPosition.X - initialXValue
	-- Delta Y negativo in modo che vada "su" sullo schermo con un cambiamento positivo di Y
	local deltaY = -math.sin(deltaX / pixelsPerRadian) * maxHeightChange
	return UDim2.fromOffset(deltaX, deltaY)
end

uiDragDetector:SetDragStyleFunction(computeSinWaveCoordinate)

Funzione di vincolo personalizzata

I UIDragDetectors non hanno regole di movimento integrate riguardo a griglie e scatti, ma puoi registrare funzioni di vincolo personalizzate per modificare il UIDragDetector.DragUDim2 e il UIDragDetector.DragRotation del rilevatore prima che vengano applicati. Ad esempio, puoi mantenere il movimento su una griglia arrotondando le posizioni a incrementi specifici, o definire aree di movimento consentite. Nota che questo viene applicato prima di eventuali limiti di traduzione/rotazione esistenti.

Il seguente esempio utilizza una funzione di vincolo che limita il trascinamento planare in una griglia X/Y basata sul numero di righe e colonne. Nota che lo ResponseStyle del rilevatore è impostato su Enum.UIDragDetectorResponseStyle.Scale e il suo BoundingUI è impostato sul contenitore della griglia.

-- Gerarchia è GridContainer ⟩ Handle ⟩ UIDragDetector ⟩ (questo script)
local gridContainer = script.Parent.Parent.Parent
local handle = gridContainer:FindFirstChild("Handle")  -- Elemento UI da trascinare
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.ResponseStyle = Enum.UIDragDetectorResponseStyle.Scale  -- Imposta il trascinamento per scala
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)