Lo Studio ti offre la possibilità di creare widget personalizzati e utilizzarli come strumenti ed estensioni. Questi widget si comportano come finestre/pannelli personalizzati nello Studio e puoi ancorarli all'interno della tua interfaccia o farli galleggiare come finestre separate.
Crea interfacce per i widget
Tutti i widget dello Studio iniziano come oggetti DockWidgetPluginGui che puoi riempire con GuiObjects, come etichette di testo e pulsanti. Per creare una GUI di widget vuota, chiama la funzione CreateDockWidgetPluginGui(), passando un ID e un oggetto DockWidgetPluginGuiInfo.
Nota che il costruttore DockWidgetPluginGuiInfo.new() si aspetta i suoi parametri in un ordine specifico come segue:
| # | Proprietà | Tipo | Descrizione |
|---|---|---|---|
| 1 | Enum.InitialDockState | Enum | Una delle enumerazioni Enum.InitialDockState. |
| 2 | InitialEnabled | Booleano | Lo stato iniziale abilitato (visibile) della GUI del widget. |
| 3 | InitialEnabledShouldOverrideRestore | Booleano | Se vero, il valore di InitialEnabled sovrascrive lo stato abilitato salvato in precedenza. |
| 4 | FloatingXSize | Intero | La larghezza iniziale della GUI quando InitialDockState è impostato su Enum.InitialDockState.Float. |
| 5 | FloatingYSize | Intero | Altezza iniziale della GUI quando InitialDockState è impostato su Enum.InitialDockState.Float. |
| 6 | MinWidth | Intero | La larghezza minima della GUI, con alcune variazioni specifiche della piattaforma. |
| 7 | MinHeight | Intero | Altezza minima della GUI, con alcune variazioni specifiche della piattaforma. |
-- Crea un nuovo oggetto "DockWidgetPluginGuiInfo"local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, -- Il widget verrà inizializzato in un pannello galleggiantetrue, -- Il widget sarà inizialmente abilitatofalse, -- Non sovrascrivere lo stato abilitato precedente200, -- Larghezza predefinita della finestra galleggiante300, -- Altezza predefinita della finestra galleggiante150, -- Larghezza minima della finestra galleggiante150 -- Altezza minima della finestra galleggiante)-- Crea una nuova GUI per il widgetlocal testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)testWidget.Title = "Widget di Test" -- Titolo opzionale del widget
Personalizza l'interfaccia del widget
Una volta creato un widget, puoi personalizzare la sua interfaccia utente con GuiObjects, come informative TextLabels o interattivi ImageButtons. Ad esempio, il seguente codice aggiunge un semplice TextButton alla finestra della GUI:
-- Crea una nuova GUI per il widgetlocal testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)testWidget.Title = "Widget di Test" -- Titolo opzionale del widgetlocal testButton = Instance.new("TextButton")testButton.BorderSizePixel = 0testButton.TextSize = 20testButton.TextColor3 = Color3.new(1,0.2,0.4)testButton.AnchorPoint = Vector2.new(0.5,0.5)testButton.Size = UDim2.new(1,0,1,0)testButton.Position = UDim2.new(0.5,0,0.5,0)testButton.SizeConstraint = Enum.SizeConstraint.RelativeYYtestButton.Text = "Cliccami"testButton.Parent = testWidget
Cambia i temi di colore dello Studio
Widget dello Studio efficaci idealmente corrispondono all'impostazione del tema dello Studio e si adattano dinamicamente quando il tema cambia. Ad esempio, se un sviluppatore sta utilizzando il tema scuro, il colore di sfondo del widget, le immagini e le etichette di testo dovrebbero apparire gradevoli in combinazione con i colori del tema nativo dello Studio.
Il seguente codice aggiuntivo utilizza una funzione syncGuiColors() che viene inizialmente chiamata insieme a un elenco di oggetti GUI da sincronizzare. All'interno della funzione, una funzione annidata setColors() scorre attraverso gli oggetti e sincronizza specifici aspetti di essi utilizzando GetColor() con le enumerazioni Enum.StudioStyleGuideColor. Questa funzione setColors() viene eseguita immediatamente per sincronizzare il tema dello Studio, poi è connessa all'evento ThemeChanged per rilevare futuri cambiamenti di tema.
testButton.Parent = testWidget
local function syncGuiColors(objects)
local function setColors()
for _, guiObject in objects do
-- Sincronizza il colore di sfondo
guiObject.BackgroundColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainBackground)
-- Sincronizza il colore del testo
guiObject.TextColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainText)
end
end
-- Esegui la funzione 'setColors()' per sincronizzare inizialmente i colori
setColors()
-- Collega l'evento 'ThemeChanged' alla funzione 'setColors()'
settings().Studio.ThemeChanged:Connect(setColors)
end
-- Esegui la funzione 'syncGuiColors()' per sincronizzare i colori degli oggetti forniti
syncGuiColors({testButton})
Personalizza i cursori del mouse
Per migliorare l'interazione attesa con gli elementi del widget, puoi impostare cursori del mouse specifici per il sistema sugli eventi GUI, come MouseEnter e MouseLeave. Il seguente codice dimostra come connettere una funzione agli eventi MouseEnter e MouseLeave del testButton per cambiare il cursore del mouse:
local function setCursor(cursorAsset)
plugin:GetMouse().Icon = cursorAsset
end
testButton.MouseEnter:Connect(function()
setCursor("rbxasset://SystemCursors/PointingHand")
end)
testButton.MouseLeave:Connect(function()
setCursor("")
end)
Fai riferimento alla seguente tabella per un elenco di cursori del mouse e dei loro potenziali casi d'uso:
| Icona del cursore del mouse | Asset | Caso d'uso |
|---|---|---|
| rbxasset://SystemCursors/Arrow | Selezione e clic predefiniti. | |
| rbxasset://SystemCursors/PointingHand | Passando sopra un link/pulsante attivo. | |
| rbxasset://SystemCursors/OpenHand | Passando sopra un elemento trascinabile. | |
| rbxasset://SystemCursors/ClosedHand | Trascinando un elemento. | |
| rbxasset://SystemCursors/IBeam | Passando sopra un campo di testo. | |
| rbxasset://SystemCursors/SizeNS | Passando sopra un'impugnatura di ridimensionamento verticale. | |
| rbxasset://SystemCursors/SizeEW | Passando sopra un'impugnatura di ridimensionamento orizzontale. | |
| rbxasset://SystemCursors/SizeNESW | Passando sopra un'impugnatura di ridimensionamento angolare. | |
| rbxasset://SystemCursors/SizeNWSE | Passando sopra un'impugnatura di ridimensionamento angolare. | |
| rbxasset://SystemCursors/SizeAll | Passando sopra un'impugnatura di ridimensionamento multidirezionale. | |
| rbxasset://SystemCursors/SplitNS | Passando sopra un'impugnatura di "divisione" verticale. | |
| rbxasset://SystemCursors/SplitEW | Passando sopra un'impugnatura di "divisione" orizzontale. | |
| rbxasset://SystemCursors/Forbidden | Passando sopra un elemento bloccato/forbidden. | |
| rbxasset://SystemCursors/Wait | Indicando che un'azione è in corso. | |
| rbxasset://SystemCursors/Busy | Indicando che il sistema è occupato. | |
| rbxasset://SystemCursors/Cross | Passando sopra un'area di selezione puntiforme. |
Raccogli input degli utenti
Elementi UI come TextBox e TextButton funzionano normalmente nei widget dello Studio e puoi costruire interfacce proprio come faresti normalmente su Roblox. Tuttavia, UserInputService non funziona poiché questi servizi si aspettano che la finestra principale dell'esperienza sia a fuoco.
Una soluzione per gli eventi di input generici è creare un Frame trasparente e sovrapporlo all'intero schermo. Il seguente campione di codice crea un frame e quando l'utente fa clic sul frame, l'evento GuiObject.InputBegan cattura l'input da tastiera sul frame fino a quando l'utente non fa clic altrove:
local frame = Instance.new("Frame")
frame.BackgroundTransparency = 1 -- Nascondi il frame
frame.Size = UDim2.new(1, 0, 1, 0) -- Copri lo schermo
frame.Position = UDim2.new(0, 0, 0, 0)
frame.Parent = testWidget
local function onInputBegan(inputObject)
-- Elabora l'oggetto di input qui, ad esempio rileva i tasti premuti
end
frame.InputBegan:Connect(onInputBegan)
Interazione di trascinamento e rilascio
Utilizzare interazioni di trascinamento e rilascio per i tuoi widget è un modo semplice per migliorare il flusso di dati. Per creare questa interazione, devi definire l'elemento da trascinare, avviare il trascinamento, creare un obiettivo di rilascio e elaborare l'azione di rilascio.
Crea sorgente di trascinamento
Puoi avviare un'azione di trascinamento chiamando Plugin:StartDrag() quando l'utente preme un pulsante del mouse su un qualche elemento UI, tipicamente un TextButton o un ImageButton all'interno di un widget. Il seguente campione di codice crea un widget a finestra singola con un pulsante di testo al suo interno.
-- Crea prima il widgetlocal widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Sorgente di Trascinamento", widgetInfo)dragSourceWidget.Title = "Sorgente di Trascinamento"-- Crea un TextButton che avvierà il trascinamentolocal dragButton = Instance.new("TextButton")dragButton.Size = UDim2.new(1, 0, 1, 0)dragButton.Text = "Trascinami!"dragButton.Parent = dragSourceWidget
Iniziare il trascinamento
Quando l'utente fa clic sul TextButton, puoi avviare il trascinamento attraverso l'evento MouseButton1Down() che si attiva non appena l'utente preme il pulsante del mouse.
All'interno della funzione connessa, determina i dati da trascinare. Il tipo dei dati dovrebbe essere riflesso nella chiave MimeType, il contenuto del trascinamento dovrebbe essere riflesso all'interno della chiave Data, e il mittente dovrebbe descrivere se stesso nella chiave Sender. Vedi la pagina Plugin:StartDrag() per ulteriori dettagli.
local function onButton1Down()
local dragInfo = {
Data = "Ciao, mondo", -- I dati da trascinare
MimeType = "text/plain", -- Descrive il tipo MIME dei dati
Sender = "SomeDragSource", -- Descrive da dove provengono i dati
MouseIcon = "", -- Contenuto dell'immagine da usare per il cursore
DragIcon = "", -- Contenuto dell'immagine da visualizzare sotto il cursore durante il trascinamento
HotSpot = Vector2.zero -- Dove centrare il cursore sull'icona di trascinamento
}
plugin:StartDrag(dragInfo)
end
dragButton.MouseButton1Down:Connect(onButton1Down)
Crea obiettivo di rilascio
L'evento PluginGui.PluginDragDropped si attiva quando l'utente rilascia il mouse su una finestra durante un trascinamento. Quando si verifica questo evento, devi definire un obiettivo di rilascio come un secondo widget con un TextLabel per rilevare i rilasci.
local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Obiettivo di Rilascio", widgetInfo)dragTargetWidget.Title = "Obiettivo di Rilascio"-- Questa TextLabel visualizzerà ciò che è stato rilasciatolocal textLabel = Instance.new("TextLabel")textLabel.Size = UDim2.new(1, 0, 1, 0)textLabel.Text = "Rilascia qui..."textLabel.Parent = dragTargetWidget
Elaborare l'azione di rilascio
Dopo aver creato un obiettivo di rilascio, collega l'evento PluginGui.PluginDragDropped al widget dell'obiettivo di rilascio:
local function onDragDrop(dragData)
print("PluginDragDropped")
if dragData.MimeType == "text/plain" then
textLabel.Text = dragData.Data
else
textLabel.Text = dragData.MimeType
end
end
dragTargetWidget.PluginDragDropped:Connect(onDragDrop)
Mentre un trascinamento è ancora in corso, questi tre eventi si attivano mentre l'utente muove il mouse sopra un widget:
- PluginDragEntered – si attiva quando l'utente passa il mouse sopra una finestra
- PluginDragMoved – si attiva ripetutamente mentre l'utente muove il mouse sopra una finestra. Questo è utile per mostrare un messaggio "Rilascia qui!".
- PluginDragLeft – si attiva quando il cursore dell'utente esce da una finestra. Questo è utile per nascondere un messaggio "Rilascia qui!".















