widgets do Studio de Construção

O Studio lhe dá o poder de criar widgets personalizados e usá-los como ferramentas e extensões do Studio .Esses widgets se comportam como janelas/painéis personalizados no Studio e você pode anexá-los dentro de sua interface ou tê-los flutuando como janelas separadas.

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 CreateDockWidgetPluginGui(), passando um ID e um ObjetoDockWidgetPluginGuiInfo.

Observe que o construtor DockWidgetPluginGuiInfo.new() espera seus parâmetros em uma ordem específica da seguinte forma:

#	Propriedade	Tipo	Descrição
1	Enum.InitialDockState	Enumeração	Uma das enumerações Enum.InitialDockState enumeradas.
2	InitialEnabled	Booleano	O estado inicial ativado (visível) da Interface gráfica do usuáriodo widget.
3	InitialEnabledShouldOverrideRestore	Booleano	Se verdadeiro, o valor de InicialEnabled substitui o estado habilitado anteriormente salvo.
4	FloatingXSize	Inteiro	A largura inicial da GUI quando InicialDockState for definido como Enum.InitialDockState.Float.
5	FloatingYSize	Inteiro	A altura inicial da GUI quando Estado de Dock Inicial é definido como Enum.InitialDockState.Float.
6	MinWidth	Inteiro	A largura mínima da Interface gráfica do usuário, com algumas variações específicas da plataforma.
7	MinHeight	Inteiro	A altura mínima da Interface gráfica do usuário, com algumas variações específicas da plataforma.


-- Criar novo Objeto"DockWidgetPluginGuiInfo"
local widgetInfo = DockWidgetPluginGuiInfo.new(
	Enum.InitialDockState.Float, -- O widget será inicializado em painel flutuante
	true,   -- O widget será inicialmente ativado
	false,  -- Não substitua o estado habilitado anterior
	200,    -- Largura padrão da janela flutuante
	300,    -- Altura padrão da janela flutuante
	150,    -- Largura 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

Você não pode usar a função CreateDockWidgetPluginGui() na barra de comandos do jogo. Você só pode chamá-la a partir da barra de comando ou de um script de plugin.

Uma vez que você crie um widget, você pode personalizar sua interface de usuário com GuiObjects , como informativa TextLabels ou interativa ImageButtons.Por exemplo, o seguinte código adiciona um básico TextButton à janela GUI:


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

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

Observe que você deve parenter o botão para o widget da mesma maneira que você deve parenter qualquer tela na experiência GuiObject para um ScreenGui.

Para ajudá-lo a construir widgets consistentes e eficazes do Studio, o Roblox fornece um repositório do GitHub que contém elementos de GUI com um visual e sensação padrão do "Studio".Estes incluem caixas de seleção, botões de rádio e campos de entrada que têm um estilo de Studio, e todos eles suportam tema escuro.

Mudar temas de cores do Studio

Os widgets do Studio eficazes idealmente correspondem à configuração do tema do Studio e ajustam dinamicamente quando o tema muda.Por instância, se um desenvolvedor estiver usando o tema escuro, a cor de fundo do widget, imagens e rótulos de texto devem parecer bonitas ao lado das cores do tema nativo do Studio.

A adição de código a seguir usa uma função syncGuiColors() que é inicialmente chamada junto com uma tabela de objetos de GUI para sincronizarDentro da função, um ciclo de função aninhado setColors() atravessa os objetos e sincroniza aspectos específicos deles usando GetColor() com Enum.StudioStyleGuideColor enums.Essa função setColors() é executada imediatamente para sincronizar o tema do Studio, então ela é conectada ao evento ThemeChanged para detectar alterações futuras no tema.


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 inicialmente as cores
	setColors()
	-- Conectar evento 'ThemeChanged' à função 'setColors()'
	settings().Studio.ThemeChanged:Connect(setColors)
end

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

Personalizar cursores de mouse

Para melhorar a interação esperada com elementos de widget, você pode definir cursores de mouse específicos do sistema para eventos de GUI, como e .O seguinte código mostra como conectar uma função aos eventos MouseEnter e MouseLeave do testButton para alterar o cursor do 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)

Referencie a tabela a seguir para uma lista de cursores de mouse e seus casos de uso potenciais:

Ícone do Cursor do Mouse	Recurso	Usar Caso
	rbxasset://SystemCursors/Arrow	Clique e seleção 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	Arrastar um item.
	rbxasset://SystemCursors/IBeam	Passe o mouse em um campo de texto.
	rbxasset://SystemCursors/SizeNS	Passe o Manipulador / alçasobre um botão de redimensionamento vertical.
	rbxasset://SystemCursors/SizeEW	Passe o Manipulador / alçasobre um botão de redimensionamento horizontal.
	rbxasset://SystemCursors/SizeNESW	Passe o mouse sobre um botão de redimensionamento de Manipulador / alça.
	rbxasset://SystemCursors/SizeNWSE	Passe o mouse sobre um botão de redimensionamento de Manipulador / alça.
	rbxasset://SystemCursors/SizeAll	Passe o Manipulador / alçasobre um cabo de redimensionamento multidirecional.
	rbxasset://SystemCursors/SplitNS	Passe o Manipulador / alçasobre um cabo vertical "divisor".
	rbxasset://SystemCursors/SplitEW	Passe o mouse sobre um Manipulador / alçahorizontal "divisor".
	rbxasset://SystemCursors/Forbidden	Passe o mouse sobre um item bloqueado/proibido.
	rbxasset://SystemCursors/Wait	Indicando que uma ação está em andamento.
	rbxasset://SystemCursors/Busy	Indicando que o sistema está ocupado.
	rbxasset://SystemCursors/Cross	Passe o mouse sobre uma área de seleção precisa.

Observe que esses olhos de cursor são apenas uma aproximação - os cursores reais correspondem aos cursores do sistema operacional padrão.

Reunir a entrada do usuário

Elementos de UI como TextBox e TextButton funcionam normalmente em widgets do Studio e você pode construir interfaces como faria normalmente no Roblox.No entanto, UserInputService e ContextActionService não funcionam desde que esses serviços esperam que a janela principal do jogo esteja em foco.

Uma solução alternativa para eventos de entrada genéricos é criar um transparente Frame e sobrepor sobre toda a tela.O seguinte exemplo de código cria um quadro e, quando o usuário clica no quadro, o evento GuiObject.InputBegan captura a entrada do teclado no quadro até que o usuário clique para longe:


local frame = Instance.new("Frame")
frame.BackgroundTransparency = 1  -- Esconder o quadro
frame.Size = UDim2.new(1, 0, 1, 0)  -- Cobrir 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 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 arrastamento, criar um alvo de solta e processar a ação de solta.

Criar originalde arrastamento

Você pode iniciar uma ação de arrastamento chamando Plugin:StartDrag() quando o usuário pressiona um botão do mouse em algum elemento de UI, geralmente um TextButton ou ImageButton dentro de um widget.O seguinte exemplo de código 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

Inicie o arrastamento

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

Dentro da função conectada, determine os dados para arrastar.O tipo de dados deve ser refletido na chave , o conteúdo da arrastada deve ser refletido dentro da chave e o remetente deve se descrever na chave .Veja a página Plugin:StartDrag() para mais detalhes.


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 se originaram
		MouseIcon = "",             -- Conteúdo de imagem para usar para o cursor
		DragIcon = "",              -- Conteúdo de imagem para renderizar sob o cursor durante o arrastamento
		HotSpot = Vector2.zero      -- Onde no DragIcon para centrar o cursor
	}
	plugin:StartDrag(dragInfo)
end

dragButton.MouseButton1Down:Connect(onButton1Down)

Criar alvo de descartar

O evento PluginGui.PluginDragDropped ocorre quando o usuário solta o mouse em uma janela durante um arrastamento.Quando isso ocorre, você precisa definir um alvo de descartar como um segundo widget com um TextLabel para detectar quedas.


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

-- Esta etiqueta de texto exibirá o que foi descartado
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.Text = "Drop here..."
textLabel.Parent = dragTargetWidget

Processar a ação de solta

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


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 acionados quando o usuário move o mouse sobre um widget:

PluginDragEntered – dispara quando o usuário passa o mouse sobre uma janela
PluginDragMoved – dispara repetidamente quando o usuário move o mouse sobre uma janela. Isso é útil para mostrar uma mensagem de "Solte aqui!"
PluginDragLeft – dispara quando o cursor do usuário deixa uma janela. Isso é útil para ocultar uma mensagem de "Solte aqui!"

Criar interfaces de widget

Personalizar a interface do widget