Widgets de Studio

Studio vous donne le pouvoir de créer des widgets personnalisés et de les utiliser comme outils et extensions. Ces widgets se comportent comme des fenêtres/panneaux personnalisés dans Studio, et vous pouvez les ancrer à l'intérieur de votre interface ou les laisser flotter en tant que fenêtres séparées.

Créer des interfaces de widget

Tous les widgets de Studio commencent comme des objets DockWidgetPluginGui que vous pouvez remplir avec des GuiObjects, tels que des étiquettes de texte et des boutons. Pour créer une interface de widget vide, appelez la fonction CreateDockWidgetPluginGui(), en passant un ID et un objet DockWidgetPluginGuiInfo.

Notez que le constructeur DockWidgetPluginGuiInfo.new() attend ses paramètres dans un ordre spécifique comme suit :

-- Créer un nouvel objet "DockWidgetPluginGuiInfo"
local widgetInfo = DockWidgetPluginGuiInfo.new(
	Enum.InitialDockState.Float, -- Le widget sera initialisé dans un panneau flottant
	true,   -- Le widget sera initialement activé
	false,  -- Ne pas remplacer l'état activé précédent
	200,    -- Largeur par défaut de la fenêtre flottante
	300,    -- Hauteur par défaut de la fenêtre flottante
	150,    -- Largeur minimale de la fenêtre flottante
	150     -- Hauteur minimale de la fenêtre flottante
)

-- Créer une nouvelle interface de widget
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Widget de Test"  -- Titre de widget optionnel

Personnaliser l'interface du widget

Une fois que vous avez créé un widget, vous pouvez personnaliser son interface utilisateur avec des GuiObjects tels que des TextLabels informatifs ou des ImageButtons interactifs. Par exemple, le code suivant ajoute un TextButton de base à la fenêtre de l'interface :

-- Créer une nouvelle interface de widget
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Widget de Test"  -- Titre de widget optionnel

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 = "Cliquez Moi"
testButton.Parent = testWidget

Changer les thèmes de couleur de Studio

Des widgets Studio efficaces doivent idéalement correspondre au paramètre de thème de Studio et s'ajuster dynamiquement lorsque le thème change. Par exemple, si un développeur utilise le thème sombre, la couleur de fond du widget, les images et les étiquettes de texte devraient bien s'accorder avec les couleurs de thème natif de Studio.

L'ajout de code suivant utilise une fonction syncGuiColors() qui est initialement appelée avec un tableau d'objets GUI à synchroniser. À l'intérieur de la fonction, une fonction imbriquée setColors() parcourt les objets et synchronise des aspects spécifiques d'eux en utilisant GetColor() avec des énumérations Enum.StudioStyleGuideColor. Cette fonction setColors() est immédiatement exécutée pour synchroniser le thème de Studio, puis elle est connectée à l'événement ThemeChanged pour détecter les futurs changements de thème.

testButton.Parent = testWidget

local function syncGuiColors(objects)
	local function setColors()
		for _, guiObject in objects do
			-- Synchroniser la couleur de fond
			guiObject.BackgroundColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainBackground)
			-- Synchroniser la couleur du texte
			guiObject.TextColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainText)
		end
	end
	-- Exécuter la fonction 'setColors()' pour synchroniser initialement les couleurs
	setColors()
	-- Connecter l'événement 'ThemeChanged' à la fonction 'setColors()'
	settings().Studio.ThemeChanged:Connect(setColors)
end

-- Exécuter la fonction 'syncGuiColors()' pour synchroniser les couleurs des objets fournis
syncGuiColors({testButton})

Personnaliser les curseurs de souris

Pour améliorer l'interaction attendue avec les éléments du widget, vous pouvez définir des curseurs de souris spécifiques au système pour les événements GUI, tels que MouseEnter et MouseLeave. Le code suivant montre comment connecter une fonction aux événements MouseEnter et MouseLeave de testButton pour changer le curseur de la souris :

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

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

Référez-vous au tableau suivant pour une liste des curseurs de souris et de leurs cas d'utilisation potentiels :

Icône de curseur de souris	Actif	Cas d'utilisation
	rbxasset://SystemCursors/Arrow	Clique et sélection par défaut.
	rbxasset://SystemCursors/PointingHand	Survol d'un lien/bouton actif.
	rbxasset://SystemCursors/OpenHand	Survol d'un élément déplaçable.
	rbxasset://SystemCursors/ClosedHand	Déplacement d'un élément.
	rbxasset://SystemCursors/IBeam	Survol dans un champ de texte.
	rbxasset://SystemCursors/SizeNS	Survol d'une poignée de redimensionnement verticale.
	rbxasset://SystemCursors/SizeEW	Survol d'une poignée de redimensionnement horizontale.
	rbxasset://SystemCursors/SizeNESW	Survol d'une poignée de redimensionnement de coin.
	rbxasset://SystemCursors/SizeNWSE	Survol d'une poignée de redimensionnement de coin.
	rbxasset://SystemCursors/SizeAll	Survol d'une poignée de redimensionnement multidirectionnelle.
	rbxasset://SystemCursors/SplitNS	Survol d'une poignée de "split" verticale.
	rbxasset://SystemCursors/SplitEW	Survol d'une poignée de "split" horizontale.
	rbxasset://SystemCursors/Forbidden	Survol d'un élément verrouillé/interdit.
	rbxasset://SystemCursors/Wait	Indiquer qu'une action est en cours.
	rbxasset://SystemCursors/Busy	Indiquer que le système est occupé.
	rbxasset://SystemCursors/Cross	Survol d'une zone de sélection précise.

Rassembler les entrées utilisateur

Les éléments d'interface utilisateur tels que TextBox et TextButton fonctionnent normalement dans les widgets Studio, et vous pouvez construire des interfaces comme vous le feriez normalement sur Roblox. Cependant, UserInputService ne fonctionne pas car ces services s'attendent à ce que la fenêtre principale du jeu soit au premier plan.

Une solution de contournement pour les événements d'entrée génériques consiste à créer un Frame transparent et à le superposer sur tout l'écran. L'exemple de code suivant crée un cadre, et lorsque l'utilisateur clique sur le cadre, l'événement GuiObject.InputBegan capture l'entrée clavier sur le cadre jusqu'à ce que l'utilisateur clique ailleurs :

local frame = Instance.new("Frame")
frame.BackgroundTransparency = 1  -- Masquer le cadre
frame.Size = UDim2.new(1, 0, 1, 0)  -- Couvrir l'écran
frame.Position = UDim2.new(0, 0, 0, 0)
frame.Parent = testWidget

local function onInputBegan(inputObject)
	-- Traiter l'objet d'entrée ici, par exemple détecter les pressions de touches
end
frame.InputBegan:Connect(onInputBegan)

Interaction par glisser-déposer

Utiliser des interactions par glisser-déposer pour vos widgets est un moyen simple d'améliorer le flux de données. Pour créer cette interaction, vous devez définir l'élément à faire glisser, initier le glissement, créer une cible de dépôt et traiter l'action de dépôt.

Créer une source de glissement

Vous pouvez commencer une action de glissement en appelant Plugin:StartDrag() lorsque l'utilisateur appuie sur un bouton de la souris sur un élément d'interface utilisateur, typiquement un TextButton ou un ImageButton dans un widget. L'exemple de code suivant crée un widget de fenêtre unique avec un bouton de texte à l'intérieur.

-- Créer d'abord le widget
local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Source de Glissement", widgetInfo)
dragSourceWidget.Title = "Source de Glissement"

-- Créer un TextButton qui initiera le glissement
local dragButton = Instance.new("TextButton")
dragButton.Size = UDim2.new(1, 0, 1, 0)
dragButton.Text = "Faites-moi glisser !"
dragButton.Parent = dragSourceWidget

Initier le glissement

Lorsque l'utilisateur clique sur le TextButton, vous pouvez initier le glissement via l'événement MouseButton1Down() qui se déclenche dès que l'utilisateur appuie sur le bouton de la souris.

Dans la fonction connectée, déterminez les données à glisser. Le type des données doit être reflété dans la clé MimeType, le contenu du glissement doit être reflété dans la clé Data, et l'expéditeur doit se décrire dans la clé Sender. Consultez la page Plugin:StartDrag() pour plus de détails.

local function onButton1Down()
	local dragInfo = {
		Data = "Bonjour, le monde",      -- Les données étant glissées
		MimeType = "text/plain",         -- Décrit le type MIME des données
		Sender = "SomeDragSource",       -- Décrit d'où proviennent les données
		MouseIcon = "",                  -- Contenu d'image à utiliser pour le curseur
		DragIcon = "",                   -- Contenu d'image à rendre sous le curseur pendant le glissement
		HotSpot = Vector2.zero           -- Où centrer le curseur sur le DragIcon
	}
	plugin:StartDrag(dragInfo)
end

dragButton.MouseButton1Down:Connect(onButton1Down)

Créer une cible de dépôt

L'événement PluginGui.PluginDragDropped se déclenche lorsque l'utilisateur relâche sa souris sur une fenêtre pendant un glissement. Lorsque cela se produit, vous devez définir une cible de dépôt telle qu'un second widget avec un TextLabel pour détecter les dépôts.

local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Cible de Dépôt", widgetInfo)
dragTargetWidget.Title = "Cible de Dépôt"

-- Cette TextLabel affichera ce qui a été déposé
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.Text = "Déposez ici..."
textLabel.Parent = dragTargetWidget

Traiter l'action de dépôt

Après avoir créé une cible de dépôt, connectez l'événement PluginGui.PluginDragDropped sur le widget cible de dépôt :

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)

Alors qu'un glissement est encore en cours, ces trois événements se déclenchent lorsque l'utilisateur déplace sa souris sur un widget :

• PluginDragEntered – se déclenche lorsque l'utilisateur survole la souris au-dessus d'une fenêtre
• PluginDragMoved – se déclenche de manière répétée lorsque l'utilisateur déplace sa souris au-dessus d'une fenêtre. Cela est utile pour afficher un message "Déposez ici !".
• PluginDragLeft – se déclenche lorsque le curseur de l'utilisateur quitte une fenêtre. Cela est utile pour cacher un message "Déposez ici !".