Widgets del estudio

Studio te da el poder de crear widgets personalizados y usarlos como herramientas y extensiones. Estos widgets se comportan como ventanas/paneles personalizados en Studio, y puedes acoplarlos dentro de tu interfaz o hacer que floten como ventanas separadas.

Todos los widgets de Studio comienzan como objetos DockWidgetPluginGui que puedes llenar con GuiObjects, como etiquetas de texto y botones. Para crear una GUI de widget vacía, llama a la función CreateDockWidgetPluginGui(), pasando un ID y un objeto DockWidgetPluginGuiInfo.

Ten en cuenta que el constructor DockWidgetPluginGuiInfo.new() espera sus parámetros en un orden específico como sigue:

#	Propiedad	Tipo	Descripción
1	Enum.InitialDockState	Enum	Uno de los enumerados Enum.InitialDockState.
2	InitialEnabled	Booleano	El estado inicial habilitado (visible) de la GUI del widget.
3	InitialEnabledShouldOverrideRestore	Booleano	Si es verdadero, el valor de InitialEnabled anula el estado habilitado guardado anteriormente.
4	FloatingXSize	Entero	El ancho inicial de la GUI cuando InitialDockState se establece en Enum.InitialDockState.Float.
5	FloatingYSize	Entero	La altura inicial de la GUI cuando InitialDockState se establece en Enum.InitialDockState.Float.
6	MinWidth	Entero	El ancho mínimo de la GUI, con algunas variaciones específicas de la plataforma.
7	MinHeight	Entero	La altura mínima de la GUI, con algunas variaciones específicas de la plataforma.


-- Crear nuevo objeto "DockWidgetPluginGuiInfo"
local widgetInfo = DockWidgetPluginGuiInfo.new(
	Enum.InitialDockState.Float, -- El widget se inicializará en un panel flotante
	true,   -- El widget estará habilitado inicialmente
	false,  -- No anular el estado habilitado anterior
	200,    -- Ancho predeterminado de la ventana flotante
	300,    -- Altura predeterminada de la ventana flotante
	150,    -- Ancho mínimo de la ventana flotante
	150     -- Altura mínima de la ventana flotante
)

-- Crear nueva GUI de widget
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Widget de prueba"  -- Título opcional del widget

No puedes usar la función CreateDockWidgetPluginGui() en scripts. Solo puedes llamarla desde la barra de comandos o un script de plugin.

Una vez que creas un widget, puedes personalizar su interfaz de usuario con GuiObjects como etiquetas de texto informativas TextLabels o botones de imagen interactivos ImageButtons. Por ejemplo, el siguiente código agrega un TextButton básico a la ventana GUI:


-- Crear nueva GUI de widget
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Widget de prueba"  -- Título opcional del 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 = "¡Haz clic en mí!"
testButton.Parent = testWidget

Ten en cuenta que debes anidar el botón en el widget de la misma manera que debes anidar cualquier GuiObject en pantalla dentro de un ScreenGui.

Para ayudarte a construir widgets consistentes y efectivos para Studio, Roblox proporciona un repositorio de GitHub que contiene elementos de GUI con un aspecto y sensación "Studio" estándar. Estos incluyen casillas de verificación, botones de radio y campos de entrada que tienen un estilo de Studio, y todos ellos son compatibles con el tema oscuro.

Cambiar los temas de color de Studio

Los widgets de Studio efectivos idealmente coinciden con la configuración del tema de Studio y se ajustan dinámicamente cuando el tema cambia. Por ejemplo, si un desarrollador está utilizando el tema oscuro, el color de fondo del widget, las imágenes y las etiquetas de texto deberían verse bien junto con los colores nativos del tema de Studio.

La siguiente adición de código utiliza una función syncGuiColors() que se llama inicialmente junto con una tabla de objetos GUI para sincronizar. Dentro de la función, una función anidada setColors() recorre los objetos y sincroniza aspectos específicos de ellos utilizando GetColor() con enumeraciones de Enum.StudioStyleGuideColor. Esta función setColors() se ejecuta inmediatamente para sincronizar el tema de Studio, luego se conecta al evento ThemeChanged para detectar cambios futuros en el tema.


testButton.Parent = testWidget

local function syncGuiColors(objects)
	local function setColors()
		for _, guiObject in objects do
			-- Sincronizar el color de fondo
			guiObject.BackgroundColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainBackground)
			-- Sincronizar el color del texto
			guiObject.TextColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainText)
		end
	end
	-- Ejecutar la función 'setColors()' para sincronizar colores inicialmente
	setColors()
	-- Conectar el evento 'ThemeChanged' a la función 'setColors()'
	settings().Studio.ThemeChanged:Connect(setColors)
end

-- Ejecutar la función 'syncGuiColors()' para sincronizar los colores de los objetos proporcionados
syncGuiColors({testButton})

Personalizar los cursores del ratón

Para mejorar la interacción esperada con los elementos del widget, puedes establecer cursores del ratón específicos del sistema para eventos de GUI, como MouseEnter y MouseLeave. El siguiente código demuestra cómo conectar una función a los eventos MouseEnter y MouseLeave de testButton para cambiar el cursor del ratón:


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

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

Consulta la siguiente tabla para una lista de cursores del ratón y sus posibles casos de uso:

Ícono del cursor del ratón	Activo	Caso de uso
	rbxasset://SystemCursors/Arrow	Clic y selección por defecto.
	rbxasset://SystemCursors/PointingHand	Al pasar el cursor sobre un enlace/botón activo.
	rbxasset://SystemCursors/OpenHand	Al pasar el cursor sobre un elemento arrastrable.
	rbxasset://SystemCursors/ClosedHand	Arrastrando un elemento.
	rbxasset://SystemCursors/IBeam	Al pasar sobre un campo de texto.
	rbxasset://SystemCursors/SizeNS	Al pasar sobre un controlador de cambio de tamaño vertical.
	rbxasset://SystemCursors/SizeEW	Al pasar sobre un controlador de cambio de tamaño horizontal.
	rbxasset://SystemCursors/SizeNESW	Al pasar sobre un controlador de cambio de tamaño en esquina.
	rbxasset://SystemCursors/SizeNWSE	Al pasar sobre un controlador de cambio de tamaño en esquina.
	rbxasset://SystemCursors/SizeAll	Al pasar sobre un controlador de cambio de tamaño multidireccional.
	rbxasset://SystemCursors/SplitNS	Al pasar sobre un controlador "dividido" vertical.
	rbxasset://SystemCursors/SplitEW	Al pasar sobre un controlador "dividido" horizontal.
	rbxasset://SystemCursors/Forbidden	Al pasar sobre un elemento bloqueado/prohibido.
	rbxasset://SystemCursors/Wait	Indicando que una acción está en progreso.
	rbxasset://SystemCursors/Busy	Indicando que el sistema está ocupado.
	rbxasset://SystemCursors/Cross	Al pasar sobre un área de selección precisa.

Ten en cuenta que estas apariencias de cursores son solo una aproximación; los cursores reales coinciden con los cursores predeterminados de tu sistema operativo.

Recopilar entrada del usuario

Los elementos de UI como TextBox y TextButton funcionan normalmente en widgets de Studio, y puedes construir interfaces tal como lo harías normalmente en Roblox. Sin embargo, UserInputService no funciona, ya que estos servicios esperan que la ventana principal de la experiencia esté en foco.

Una solución alternativa para eventos de entrada genéricos es crear un Frame transparente y superponerse sobre toda la pantalla. El siguiente ejemplo de código crea un marco y, cuando el usuario hace clic en el marco, el evento GuiObject.InputBegan captura la entrada del teclado en el marco hasta que el usuario haga clic en otro lado:


local frame = Instance.new("Frame")
frame.BackgroundTransparency = 1  -- Ocultar el marco
frame.Size = UDim2.new(1, 0, 1, 0)  -- Cubrir la pantalla
frame.Position = UDim2.new(0, 0, 0, 0)
frame.Parent = testWidget

local function onInputBegan(inputObject)
	-- Procesar el objeto de entrada aquí, por ejemplo detectar pulsaciones de teclas
end
frame.InputBegan:Connect(onInputBegan)

Interacción de arrastrar y soltar

Usar interacciones de arrastrar y soltar para tus widgets es una forma simple de mejorar el flujo de datos. Para crear esta interacción, debes definir el elemento a arrastrar, iniciar el arrastre, crear un objetivo de soltar y procesar la acción de soltar.

Crear fuente de arrastre

Puedes iniciar una acción de arrastre llamando a Plugin:StartDrag() cuando el usuario presiona un botón del ratón en algún elemento de UI, típicamente un TextButton o ImageButton dentro de un widget. El siguiente ejemplo de código crea un widget de ventana única con un botón de texto dentro de él.


-- Crear primero el widget
local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Fuente de arrastre", widgetInfo)
dragSourceWidget.Title = "Fuente de arrastre"

-- Crear un TextButton que iniciará el arrastre
local dragButton = Instance.new("TextButton")
dragButton.Size = UDim2.new(1, 0, 1, 0)
dragButton.Text = "¡Arrástrame!"
dragButton.Parent = dragSourceWidget

Iniciar el arrastre

Cuando el usuario hace clic en el TextButton, puedes iniciar el arrastre a través del evento MouseButton1Down() que se activa tan pronto como el usuario presiona el botón del ratón.

Dentro de la función conectada, determina los datos que se arrastrarán. El tipo de los datos debe reflejarse en la clave MimeType, el contenido del arrastre debe reflejarse dentro de la clave Data, y el remitente debe describirse en la clave Sender. Consulta la página de Plugin:StartDrag() para más detalles.


local function onButton1Down()
	local dragInfo = {
		Data = "Hola, mundo",      -- Los datos que se arrastran
		MimeType = "text/plain",    -- Describe el tipo MIME de los datos
		Sender = "SomeDragSource",  -- Describe de dónde provienen los datos
		MouseIcon = "",             -- Contenido de imagen para usar en el cursor
		DragIcon = "",              -- Contenido de imagen para renderizar bajo el cursor durante el arrastre
		HotSpot = Vector2.zero      -- Donde centrar el cursor en el DragIcon
	}
	plugin:StartDrag(dragInfo)
end

dragButton.MouseButton1Down:Connect(onButton1Down)

Crear objetivo de soltar

El evento PluginGui.PluginDragDropped se activa cuando el usuario suelta su ratón sobre una ventana durante un arrastre. Cuando esto ocurre, necesitas definir un objetivo de soltar como un segundo widget con un TextLabel para detectar las caídas.


local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Objetivo de soltar", widgetInfo)
dragTargetWidget.Title = "Objetivo de soltar"

-- Esta TextLabel mostrará lo que se soltó
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.Text = "Suelta aquí..."
textLabel.Parent = dragTargetWidget

Procesar la acción de soltar

Después de crear un objetivo de soltar, conecta el evento PluginGui.PluginDragDropped en el widget de objetivo de soltar:


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)

Mientras un arrastre aún está en progreso, estos tres eventos se activan a medida que el usuario mueve su ratón sobre un widget:

PluginDragEntered – se activa cuando el usuario pasa el ratón sobre una ventana
PluginDragMoved – se activa repetidamente a medida que el usuario mueve su cursor sobre una ventana. Esto es útil para mostrar un mensaje de "¡Suelta aquí!".
PluginDragLeft – se activa cuando el cursor del usuario sale de una ventana. Esto es útil para ocultar un mensaje de "¡Suelta aquí!".

Crear interfaces de widget

Personalizar la interfaz de widget