Construindo widgets do Studio

O Studio dá a você o poder de criar widgets personalizados e usá-los como ferramentas e extensões do Studio. Esses widgets se comportam como janelas/painéis personalizadas no Studio e você pode ancorá-las dentro de sua interface ou fazer com que flutuem como janelas separadas.

Criando UIs de widget

Todos os widgets do Studio começam como objetos DockWidgetPluginGui, que você pode preencher com GuiObjects, como rótulos de texto e botões. Para criar uma Interface gráfica do usuáriode widget vazia, chame a função Class.Plugin:CreateDockWidgetPluginGui()|CreateDockWidgetPluginGui() , passando um ID e um Objeto<

Observe que o DockWidgetPluginGuiInfo.new() constructor espera seus parâmetros em uma ordem específica como a seguinte:

-- Criar um novo Objeto"DockWidgetPluginGuiInfo"
local widgetInfo = DockWidgetPluginGuiInfo.new(
	Enum.InitialDockState.Float,  -- O widget será inicializado no painel flutuante
	true,   -- O widget será inicialmente ativado
	false,  -- Não sobrescreva o estado ativado anterior
	200,    -- Largeza padrão da janela flutuante
	300,    -- Altura padrão da janela flutuante
	150,    -- Largeza mínima da janela flutuante
	150     -- Altura mínima da janela flutuante
)

-- Criar nova Interface gráfica do usuáriode widget
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Test Widget"  -- Optional widget title

Personalizando a IU do widget

Uma vez que você cria um widget, você pode personalizar sua interface do usuário com GuiObjects , como TextLabels ou ImageButtons . Por exemplo, o seguinte código adiciona um básico 1> Class.TextButton1> à janela GUI:

-- Criar nova Interface gráfica do usuáriode widget
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Test Widget"  -- Título de widget opcional

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

Mudando Tema de Cores do Studio

Os widgets do Studio normalmente correspondem à configuração e ao ajuste dinâmico do tema Studio. Por instância, se um desenvolvedor estiver usando o tema escuro, a cor de fundo do widget, as imagens e as etiquetas de texto devem ficar boas ao lado das cores do tema nativo do Studio.

O seguinte código de adição usa uma função syncGuiColors() que inicialmente é chamada juntamente com uma tabela de objetos GUI para sincronizar. No interior da função,

testButton.Parent = testWidget

local function syncGuiColors(objects)
	local function setColors()
		for _, guiObject in objects do
			-- Sincronizar cor de fundo
			guiObject.BackgroundColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainBackground)
			-- Sincronizar cor de texto
			guiObject.TextColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainText)
		end
	end
	-- Execute a função 'setColors()' para sincronizar cores inicialmente
	setColors()
	-- Conecte o evento 'ThemeChanged' à função 'setColors()'
	settings().Studio.ThemeChanged:Connect(setColors)
end

-- Execute a função 'syncGuiColors()' para sincronizar as cores dos objetos fornecidos
syncGuiColors({testButton})

Personalizando Cursors do Mouse

Para melhorar a interação esperada com os elementos do widget, você pode configurar mouse cursors específicos do sistema para eventos GUI, como MouseEnter e Class.GuiObject.MouseLeave

local function setCursor(cursorAsset)
	plugin:GetMouse().Icon = cursorAsset
end

testButton.MouseEnter:Connect(function()
	setCursor("rbxasset://SystemCursors/PointingHand")
end)
testButton.MouseLeave:Connect(function()
	setCursor("")
end)

Referência na tabela a seguir para uma lista de cursos de mouse e seus casos de uso potenciais:

Ícone do Cursor do Mouse	Recurso	Usar Caixa
	rbxasset://SystemCursors/Arrow	Clique e selecione padrão.
	rbxasset://SystemCursors/PointingHand	Passe o mouse sobre um link/botão ativo.
	rbxasset://SystemCursors/OpenHand	Passe o mouse sobre um item arrastável.
	rbxasset://SystemCursors/ClosedHand	Arrastando um item.
	rbxasset://SystemCursors/IBeam	Passe o mouse em um campo de texto.
	rbxasset://SystemCursors/SizeNS	Passe o mouse sobre um Manipulador / alçade resize vertical.
	rbxasset://SystemCursors/SizeEW	Passe o mouse sobre um Manipulador / alçade resize horizontal.
	rbxasset://SystemCursors/SizeNESW	Passe o mouse sobre um cabo de resize de Manipulador / alça.
	rbxasset://SystemCursors/SizeNWSE	Passe o mouse sobre um cabo de resize de Manipulador / alça.
	rbxasset://SystemCursors/SizeAll	Passe o mouse sobre um Manipulador / alçade resize multidirecional.
	rbxasset://SystemCursors/SplitNS	Passe o mouse sobre um Manipulador / alçade "divisão" vertical.
	rbxasset://SystemCursors/SplitEW	Passe o mouse sobre um Manipulador / alça"divisório" horizontal.
	rbxasset://SystemCursors/Forbidden	Passe o mouse sobre um item bloqueado/proibido.
	rbxasset://SystemCursors/Wait	Indicando uma ação em andamento.
	rbxasset://SystemCursors/Busy	Indicando que o sistema está ocupado.
	rbxasset://SystemCursors/Cross	Passe o mouse sobre uma área de seleção de ponto.

Coletando a entrada do usuário

Os elementos da interface, como TextBox e TextButton funcionam normalmente em widgets do Studio, e você pode construir interfaces como você normalmente faria no Roblox. No entanto, UserInputService e 1> Class.ContextActionService1> não funcionam, pois esses serviços esperam que a janela principal do jogo esteja em foco.

Um workaround para eventos genéricos de entrada é criar um Frame transparente e sobreposi-lo sobre toda a tela. O seguinte código de exemplo cria um frame, e quando o usuário clica no frame, o evento GuiObject.InputBegan captura a entrada do teclado na tela até que o usuário clique para fora:

local frame = Instance.new("Frame")
frame.BackgroundTransparency = 1  -- Ocultar a janela
frame.Size = UDim2.new(1, 0, 1, 0)  -- Cubra a tela
frame.Position = UDim2.new(0, 0, 0, 0)
frame.Parent = testWidget

local function onInputBegan(inputObject)
	-- Processar o objeto de entrada aqui, por exemplo, detectar pressões de tecla
end
frame.InputBegan:Connect(onInputBegan)

Interação de Arrastar e Soltar

Usar interações de arrastar e soltar para seus widgets é uma maneira simples de melhorar o fluxo de dados. Para criar essa interação, você deve definir o elemento para arrastar, iniciar o arrastar, criar um alvo de drop e processar a ação de drop.

Criando uma Fonte de Arrastamento

Você pode iniciar uma ação de arrastamento chamando Plugin:StartDrag() quando o usuário pressiona um botão de mouse em algum elemento da interface do usuário, geralmente um TextButton ou ImageButton dentro de um widget. O seguinte código de exemplo cria um único widget de janela com um botão de texto dentro dele.

-- Crie o widget primeiro
local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Drag Source", widgetInfo)
dragSourceWidget.Title = "Drag Source"

-- Crie um Botão de Texto que iniciará o arrastamento
local dragButton = Instance.new("TextButton")
dragButton.Size = UDim2.new(1, 0, 1, 0)
dragButton.Text = "Drag me!"
dragButton.Parent = dragSourceWidget

Iniciando o Drag

Quando o usuário clica no TextButton, você pode iniciar o arrastamento através do evento MouseButton1Down() que é executado assim que o usuário pressiona o botão do mouse.

Dentro da função conectada, determine os dados para arrastar. O tipo de dado tipo deve ser refletido na chave MimeType, o conteúdo conteúdo da arrastagem deve ser refletido dentro da chave 2>Data2> e o remetente

local function onButton1Down()
	local dragInfo = {
		Data = "Hello, world",      -- Os dados sendo arrastados
		MimeType = "text/plain",    -- Descreve o tipo MIME dos dados
		Sender = "SomeDragSource",  -- Descreve de onde os dados vêm
		MouseIcon = "",             -- Conteúdo de imagem para usar para o cursor
		DragIcon = "",              -- Conteúdo da imagem para renderizar sob o cursor durante o arrastamento
		HotSpot = Vector2.zero -- Onde no DragIcon para centralizar o cursor
	}
	plugin:StartDrag(dragInfo)
end

dragButton.MouseButton1Down:Connect(onButton1Down)

Criando um Alvo de Drop

O evento PluginGui.PluginDragDropped é acionado quando o usuário libera seu mouse em uma janela durante uma拖. Quando isso ocorre, você precisa definir um drop target como um segundo widget com um TextLabel para detectar drops.

local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Drop Target", widgetInfo)
dragTargetWidget.Title = "Drop Target"

-- Este TextLabel exibirá o que foi derrubado
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.Text = "Drop here..."
textLabel.Parent = dragTargetWidget

Processando a Ação de Drop

Depois de criar um alvo de queda, conecte o evento PluginGui.PluginDragDropped no widget de alvo de queda:

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)

Enquanto um arrastamento ainda está em andamento, esses três eventos são disparados à medida que o usuário move o mouse sobre um widget:

• PluginDragEntered – ativado quando o usuário passa o mouse sobre uma janela
• PluginDragMoved – dispara várias vezes à medida que o usuário move o mouse sobre uma janela. Isso é útil para mostrar uma mensagem “Drop here!”
• PluginDragLeft – dispara quando o cursor do usuário sai de uma janela. Isso é útil para ocultar uma mensagem “Drop here!”