Realizzare widget su Studio

Studio ti offre la possibilità di creare widget personalizzati e di utilizzarli come strumenti ed estensioni di Studio. Questi widget si comportano come finestre/pannelli personalizzati all'interno di Studio e possono essere collegati all'interno della tua interfaccia o farli fluttuare come finestre separate.

Tutti gli widget di Studio iniziano come oggetti DockWidgetPluginGui che possono essere completati con GuiObjects, come etichette di testo e pulsanti. Per creare un GUI di widget vuoto, chiamare la funzione CreateDockWidgetPluginGui(), passando all'interno un ID e un oggetto DockWidgetPluginGuiInfo.

Da notare che il DockWidgetPluginGuiInfo.new()costruttore si aspetta i propri 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 (visibile) della GUI del widget.
3	InitialEnabledShouldOverrideRestore	Booleano	Se vero, il valore InitialEnabled* sovrascrive lo stato abilitato precedentemente salvato.
4	FloatingXSize	Numero intero	L'ampiezza iniziale del GUI quando InitialDockState è impostato su Enum.InitialDockState.Float.
5	FloatingYSize	Numero intero	L'altezza iniziale del GUI quando InitialDockState è impostato su Enum.InitialDockState.Float.
6	MinWidth	Numero intero	L'ampiezza minima del GUI, con alcune variazioni specifiche alla piattaforma.
7	MinHeight	Numero intero	L'altezza minima del GUI, con alcune variazioni specifiche alla piattaforma.


-- Create new "DockWidgetPluginGuiInfo" object
local widgetInfo = DockWidgetPluginGuiInfo.new(
    Enum.InitialDockState.Float,  -- Widget will be initialized in floating panel
    true,   -- Widget will be initially enabled
    false,  -- Don't override the previous enabled state
    200,    -- Default width of the floating window
    300,    -- Default height of the floating window
    150,    -- Minimum width of the floating window
    150     -- Minimum height of the floating window
)
-- Create new widget GUI
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Test Widget"  -- Optional widget title

Non è possibile utilizzare la funzione CreateDockWidgetPluginGui() negli script di gioco. Puoi chiamarlo unicamente dalla barra dei comandi o da uno script plugin.

Una volta creato un widget, è possibile personalizzare la sua interfaccia utente conGuiObjects come TextLabels informativo o ImageButtonsinterattivo. Ad esempio, il seguente codice aggiunge un TextButton base alla finestra GUI:


-- Create new widget GUI
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Test Widget"  -- Optional widget title
local testButton = Instance.new("TextButton")
testButton.BorderSizePixel = 0
testButton.TextSize = 20
testButton.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.RelativeYY
testButton.Text = "Click Me"
testButton.Parent = testWidget

Nota che è necessario accoppiare il pulsante al widget nello stesso modo in cui devi accoppiare qualsiasi schermata all'interno dell'esperienza GuiObject a un ScreenGui.

Per aiutarti a realizzare widget Studio consistenti ed efficaci, Roblox fornisce un repo GitHub che contiene elementi GUI che appaiono e sembrano standard di "Studio". Questi includono caselle di controllo, pulsanti di opzione e campi di input che hanno uno stile Studio e tutti supportano il tema scuro.

Modifica dei temi cromatici di Studio

I widget Studio efficaci si adattano perfettamente all'impostazione del tema Studio e si regolano dinamicamente quando esso cambia. Ad esempio, se uno sviluppatore sta utilizzando il tema scuro, il widget di colore di sfondo, immagini e le etichette di testo dovrebbero adattarsi perfettamente accanto ai colori del tema originario di Studio.

L'aggiunta del seguente codice utilizza una funzione syncGuiColors() che viene inizialmente chiamata insieme a una tabella di oggetti GUI da sincronizzare. All'interno della funzione, una funzione setColors() innestata passa attraverso gli oggetti e ne sincronizza gli aspetti specifici utilizzando GetColor() con enum Enum.StudioStyleGuideColor. Questa funzione setColors() viene eseguita immediatamente per sincronizzare il tema di Studio, quindi viene collegata all'evento ThemeChanged per rilevare le future modifiche del tema.


testButton.Parent = testWidget
local function syncGuiColors(objects)
    local function setColors()
        for _, guiObject in pairs(objects) do
            -- Sync background color
            guiObject.BackgroundColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainBackground)
            -- Sync text color
            guiObject.TextColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainText)
        end
    end
    -- Run 'setColors()' function to initially sync colors
    setColors()
    -- Connect 'ThemeChanged' event to the 'setColors()' function
    settings().Studio.ThemeChanged:Connect(setColors)
end
-- Run 'syncGuiColors()' function to sync colors of provided objects
syncGuiColors({testButton})

Personalizzazione dei cursori del mouse

Per migliorare l'interazione prevista con gli elementi widget, è possibile impostare i cursori del mouse specifici del sistema per eventi GUI, come MouseEnter e MouseLeave. Il seguente codice mostra come collegare una funzione agli eventi testButtone MouseEnterdi MouseLeaveper 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)

Fare riferimento alla seguente tabella per un elenco di cursori del mouse e dei loro potenziali casi d'uso:

Icona cursore del mouse	Risorsa/Asset	Caso d'uso
	rbxasset://SystemCursors/Arrow	Clic e selezione predefinita.
	rbxasset://SystemCursors/PointingHand	Passare il mouse su un link/pulsante attivo.
	rbxasset://SystemCursors/OpenHand	Passare il mouse su un oggetto trascinabile.
	rbxasset://SystemCursors/ClosedHand	Trascinare un elemento.
	rbxasset://SystemCursors/IBeam	Passare il mouse in un campo di testo.
	rbxasset://SystemCursors/SizeNS	Passare il mouse su un quadratino di ridimensionamento verticale.
	rbxasset://SystemCursors/SizeEW	Passare sopra un quadratino di ridimensionamento orizzontale.
	rbxasset://SystemCursors/SizeNESW	Passare sopra un quadratino di ridimensionamento angolare.
	rbxasset://SystemCursors/SizeNWSE	Passare sopra un quadratino di ridimensionamento angolare.
	rbxasset://SystemCursors/SizeAll	Passare sopra un quadratino di ridimensionamento multidirezionale.
	rbxasset://SystemCursors/SplitNS	Passare sopra un quadratino di suddivisione verticale.
	rbxasset://SystemCursors/SplitEW	Passare sopra un quadratino di suddivisione orizzontale.
	rbxasset://SystemCursors/Forbidden	Passare sopra una voce bloccata/vietata.
	rbxasset://SystemCursors/Wait	Indicare che è in corso un'azione.
	rbxasset://SystemCursors/Busy	Indicare che il sistema è occupato.
	rbxasset://SystemCursors/Cross	Passare sopra un'area di selezione localizzata.

Notare che le sembianze di questo cursore sono solo approssimative; i cursori effettivi corrispondono ai cursori del sistema operativo predefinito.

Raccolta degli input utente

Gli elementi GUI come TextBox e TextButton funzionano normalmente nei widget di Studio ed è possibile realizzare interfacce proprio come faresti su Roblox. Tuttavia, UserInputService e ContextActionService non funzionano poiché questi servizi si aspettano che la finestra di gioco principale sia a fuoco.

Una soluzione per gli eventi di input generici è creare un Frame trasparente e sovrapporlo su tutto lo schermo. Il seguente esempio di codice crea un frame e quando l'utente fa clic su di esso, l'GuiObject.InputBegan evento cattura l'input della tastiera sul frame fino a quando l'utente non fa clic:


local frame = Instance.new("Frame")
frame.BackgroundTransparency = 1  -- Hide the frame
frame.Size = UDim2.new(1, 0, 1, 0)  -- Cover the screen
frame.Position = UDim2.new(0, 0, 0, 0)
frame.Parent = testWidget
local function onInputBegan(inputObject)
    -- Process the input object here, for example detect key presses
end
frame.InputBegan:Connect(onInputBegan)

Interazione trascina e rilascia

Utilizzando le interazioni trascina e rilascia per i widget si può migliorare facilmente il flusso dei dati. Per creare questa interazione, è necessario definire l'elemento da trascinare, avviare il trascinamento, creare un target di rilascio ed elaborare l'azione di rilascio.

Creare una fonte di trascinamento

Puoi avviare un'azione di trascinamento chiamando Plugin:StartDrag()quando l'utente preme un pulsante del mouse su un elemento dell'interfaccia utente, di solito un TextButton o ImageButtonall'interno di un widget. Il seguente esempio di codice crea un widget a finestra singola con un pulsante di testo all'interno.


-- Create the widget first
local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Drag Source", widgetInfo)
dragSourceWidget.Title = "Drag Source"
-- Create a TextButton that will initiate the drag
local dragButton = Instance.new("TextButton")
dragButton.Size = UDim2.new(1, 0, 1, 0)
dragButton.Text = "Drag me!" dragButton.Parent = dragSourceWidget

Avviare il trascinamento

Quando l'utente fa clic su TextButton, è possibile avviare il trascinamento attraverso l'evento MouseButton1Down() che si attiva non appena l'utente preme il pulsante del mouse.er presses the mouse button.

All'interno della funzione collegata, determina i dati da trascinare. Il tipo di dati dovrebbe riflettersi nella chiave MimeType, il contenuto del trascinamento dovrebbe riflettersi nella chiave Data e il mittente dovrebbe descriversi nella chiave Sender . Vedi la pagina Plugin:StartDrag() per maggiori dettagli.


local function onButton1Down()
    local dragInfo = {
        Data = "Hello, world",      -- The data being dragged
        MimeType = "text/plain",    -- Describes the MIME type of the data
        Sender = "SomeDragSource",  -- Describes from where the data originated
        MouseIcon = "",             -- Image content to use for the cursor
        DragIcon = "",              -- Image content to render under the cursor during drag
        HotSpot = Vector2.new(0, 0) -- Where on the DragIcon to center the cursor
    }
    plugin:StartDrag(dragInfo)
end
dragButton.MouseButton1Down:Connect(onButton1Down)

Creare un target di rilascio

L'evento PluginGui.PluginDragDropped si attiva quando l'utente rilascia con il proprio mouse su una finestra durante un trascinamento. Quando ciò accade, è necessario definire un target di rilascio come un secondo widget con un TextLabelper rilevare i rilasci.


local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Drop Target", widgetInfo)
dragTargetWidget.Title = "Drop Target"
-- This TextLabel will display what was dropped
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.Text = "Drop here..." textLabel.Parent = dragTargetWidget

Processare l'azione di rilascio

Dopo aver creato un target di rilascio, connettiti all'evento PluginGui.PluginDragDropped sul widget del target 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 avviano quando l'utente sposta il mouse su un widget:

PluginDragEntered – si avvia quando l'utente passa il mouse su una finestra
PluginDragMoved – si avvia ripetutamente quando l'utente sposta il mouse su una finestra. Ciò è utile per mostrare un messaggio "Trascina qui!" .
PluginDragLeft – si avvia quando il cursore dell'utente abbandona una finestra. Ciò è utile per nascondere un messaggio "Trascina qui!" .

Creare interfacce utenti di Widget

Personalizzazione dell'interfaccia utente del widget