GuiObject

Afficher les obsolètes

*Ce contenu est traduit en utilisant l'IA (Beta) et peut contenir des erreurs. Pour consulter cette page en anglais, clique ici.

Création impossible
Non navigable

GuiObject est une classe abstraite (comme BasePart ) pour un objet d'interface utilisateur 2D.Il définit toutes les propriétés relatives à l'affichage d'un objet d'interface utilisateur graphique (IU) tel que Size et Position .Il a également quelques propriétés utiles en lecture seule comme AbsolutePosition , AbsoluteSize , et AbsoluteRotation .

Pour manipuler la disposition des objets GUI d'une manière spéciale, vous pouvez utiliser une structure de mise en page telle que liste/flexibilité ou grille , et vous pouvez les styliser au-delà de leurs propriétés de base grâce à modifieurs d'apparence .

Bien que il soit possible de détecter les événements de bouton de souris sur n'importe quel objet GUI en utilisant InputBegan et InputEnded, seuls ImageButton et TextButton ont des événements pratiques dédiés tels que Activated pour détecter le clic/la pression.

Résumé

Propriétés

Propriétés hérités de GuiBase2d

Méthodes

Évènements

Évènements hérités de GuiBase2d

Propriétés

Active

Lecture parallèle

Cette propriété détermine si la va couler l'entrée dans l'espace 3D, comme les modèles sous-jacents avec une classe comme >.

Pour GuiButton les objets ( ImageButton et TextButton ), cette propriété détermine si les Activated incendies se produisent ( AutoButtonColor fonctionnera toujours pour ceux-là aussi).Les événements InputBegan, InputChanged et InputEnded fonctionnent normalement, peu importe la valeur de cette propriété.

Échantillons de code

This code sample demonstrates the usage of the Active property as a debounce for the Activated event.

TextButton Active Debounce

-- Place this LocalScript within a TextButton (or ImageButton)
local textButton = script.Parent
textButton.Text = "Click me"
textButton.Active = true
local function onActivated()
-- This acts like a debounce
textButton.Active = false
-- Count backwards from 5
for i = 5, 1, -1 do
textButton.Text = "Time: " .. i
task.wait(1)
end
textButton.Text = "Click me"
textButton.Active = true
end
textButton.Activated:Connect(onActivated)

AnchorPoint

Lecture parallèle

Cette propriété détermine le point d'origine d'un GuiObject , par rapport à sa taille absolue.Le point d'origine détermine d'où l'élément est positionné (via GuiObject.Position ) et à partir duquel il s'étend rendu GuiObject.Size.

Voir ici pour les diagrammes et les détails illustrés.

Échantillons de code

This code sample moves a UI element to different sides of the parent element. It starts at the top-left and ends at the bottom-right. Paste into a LocalScript in a Frame, within a ScreenGui.

AnchorPoint Demo

local guiObject = script.Parent
while true do
-- Top-left
guiObject.AnchorPoint = Vector2.new(0, 0)
guiObject.Position = UDim2.new(0, 0, 0, 0)
task.wait(1)
-- Top
guiObject.AnchorPoint = Vector2.new(0.5, 0)
guiObject.Position = UDim2.new(0.5, 0, 0, 0)
task.wait(1)
-- Top-right
guiObject.AnchorPoint = Vector2.new(1, 0)
guiObject.Position = UDim2.new(1, 0, 0, 0)
task.wait(1)
-- Left
guiObject.AnchorPoint = Vector2.new(0, 0.5)
guiObject.Position = UDim2.new(0, 0, 0.5, 0)
task.wait(1)
-- Dead center
guiObject.AnchorPoint = Vector2.new(0.5, 0.5)
guiObject.Position = UDim2.new(0.5, 0, 0.5, 0)
task.wait(1)
-- Right
guiObject.AnchorPoint = Vector2.new(1, 0.5)
guiObject.Position = UDim2.new(1, 0, 0.5, 0)
task.wait(1)
-- Bottom-left
guiObject.AnchorPoint = Vector2.new(0, 1)
guiObject.Position = UDim2.new(0, 0, 1, 0)
task.wait(1)
-- Bottom
guiObject.AnchorPoint = Vector2.new(0.5, 1)
guiObject.Position = UDim2.new(0.5, 0, 1, 0)
task.wait(1)
-- Bottom-right
guiObject.AnchorPoint = Vector2.new(1, 1)
guiObject.Position = UDim2.new(1, 0, 1, 0)
task.wait(1)
end

AutomaticSize

Lecture parallèle

Cette propriété est utilisée pour dimensionner automatiquement les objets d'interface utilisateur parents en fonction de la taille de leurs descendants.Vous pouvez utiliser cette propriété pour ajouter dynamiquement du texte et d'autres contenus à un objet d'interface utilisateur au moment de l'édition ou du lancement, et la taille s'ajustera pour s'adapter à ce contenu.

Lorsque AutomaticSize est défini sur une valeur Enum.AutomaticSize à tout autre que None, cet objet d'interface utilisateur peut redimensionner en fonction de son contenu enfant.

Pour plus d'informations sur la façon d'utiliser cette propriété et sur la façon dont elle fonctionne, veuillez voir ici.

Échantillons de code

The following script creates an automatically-sized parent frame with aUIListLayout, then it inserts several automatically-sized TextLabel objects. Note how the parent UIListLayout automatically resizes to fit its child content and the labels automatically resize to fit their text content. This script can be parented to a ScreenGui.

LocalScript in a ScreenGui

-- Array of text labels/fonts/sizes to output
local labelArray = {
{ text = "Lorem", font = Enum.Font.Creepster, size = 50 },
{ text = "ipsum", font = Enum.Font.IndieFlower, size = 35 },
{ text = "dolor", font = Enum.Font.Antique, size = 55 },
{ text = "sit", font = Enum.Font.SpecialElite, size = 65 },
{ text = "amet", font = Enum.Font.FredokaOne, size = 40 },
}
-- Create an automatically-sized parent frame
local parentFrame = Instance.new("Frame")
parentFrame.AutomaticSize = Enum.AutomaticSize.XY
parentFrame.BackgroundColor3 = Color3.fromRGB(90, 90, 90)
parentFrame.Size = UDim2.fromOffset(25, 100)
parentFrame.Position = UDim2.fromScale(0.1, 0.1)
parentFrame.Parent = script.Parent
-- Add a list layout
local listLayout = Instance.new("UIListLayout")
listLayout.Padding = UDim.new(0, 5)
listLayout.Parent = parentFrame
-- Set rounded corners and padding for visual aesthetics
local roundedCornerParent = Instance.new("UICorner")
roundedCornerParent.Parent = parentFrame
local uiPaddingParent = Instance.new("UIPadding")
uiPaddingParent.PaddingTop = UDim.new(0, 5)
uiPaddingParent.PaddingLeft = UDim.new(0, 5)
uiPaddingParent.PaddingRight = UDim.new(0, 5)
uiPaddingParent.PaddingBottom = UDim.new(0, 5)
uiPaddingParent.Parent = parentFrame
for i = 1, #labelArray do
-- Create an automatically-sized text label from array
local childLabel = Instance.new("TextLabel")
childLabel.AutomaticSize = Enum.AutomaticSize.XY
childLabel.Size = UDim2.fromOffset(75, 15)
childLabel.Text = labelArray[i]["text"]
childLabel.Font = labelArray[i]["font"]
childLabel.TextSize = labelArray[i]["size"]
childLabel.TextColor3 = Color3.new(1, 1, 1)
childLabel.Parent = parentFrame
-- Visual aesthetics
local roundedCorner = Instance.new("UICorner")
roundedCorner.Parent = childLabel
local uiPadding = Instance.new("UIPadding")
uiPadding.PaddingTop = UDim.new(0, 5)
uiPadding.PaddingLeft = UDim.new(0, 5)
uiPadding.PaddingRight = UDim.new(0, 5)
uiPadding.PaddingBottom = UDim.new(0, 5)
uiPadding.Parent = childLabel
task.wait(2)
end

BackgroundColor3

Lecture parallèle

Cette propriété détermine la couleur d'un arrière-plan GuiObject (la couleur de remplissage).Si votre élément contient du texte, comme un TextBox, TextButton, ou TextLabel, assurez-vous que la couleur de votre arrière-plan contraste avec la couleur du texte.

Une autre propriété qui détermine les propriétés visuelles du fond est GuiObject.BackgroundTransparency ; si elle est définie sur 1, ni le fond ni la bordure ne seront rendus.

Voir aussi BorderColor3 .

Échantillons de code

This code sample causes a parent Frame to loop through all colors of the rainbow using Color3.fromHSV.

Rainbow Frame

-- Put this code in a LocalScript in a Frame
local frame = script.Parent
while true do
for hue = 0, 255, 4 do
-- HSV = hue, saturation, value
-- If we loop from 0 to 1 repeatedly, we get a rainbow!
frame.BorderColor3 = Color3.fromHSV(hue / 256, 1, 1)
frame.BackgroundColor3 = Color3.fromHSV(hue / 256, 0.5, 0.8)
task.wait()
end
end

BackgroundTransparency

Lecture parallèle

Cette propriété détermine la transparence du fond et des bords GuiObject.Cependant, il ne détermine pas la transparence du texte si la GUI est un TextBox , TextButton ou TextLabel ; la transparence du texte est déterminée TextBox.TextTransparency , TextButton.TextTransparency et TextLabel.TextTransparency respectivement.

Si cette propriété est définie à 1, ni le fond ni la bordure ne seront rendus et l'arrière-plan de l'interface utilisateur sera complètement transparent.

BorderColor3

Lecture parallèle

Détermine la couleur de la bordure rectangulaire GuiObject (également appelée couleur du trait).Cela est séparé de la partie GuiObject.BackgroundColor3 de l'objet.Vous ne pourrez pas voir la bordure de l'objet si sa propriété GuiObject.BorderSizePixel est définie sur 0 .

Notez que le composant UIStroke permet des effets de bord plus avancés.

Échantillons de code

This code sample causes the border of a parent GuiObject to highlight when the user hovers their mouse over the element.

Button Highlight

-- Put me inside some GuiObject, preferrably an ImageButton/TextButton
local button = script.Parent
local function onEnter()
button.BorderSizePixel = 2
button.BorderColor3 = Color3.new(1, 1, 0) -- Yellow
end
local function onLeave()
button.BorderSizePixel = 1
button.BorderColor3 = Color3.new(0, 0, 0) -- Black
end
-- Connect events
button.MouseEnter:Connect(onEnter)
button.MouseLeave:Connect(onLeave)
-- Our default state is "not hovered"
onLeave()

BorderMode

Lecture parallèle

Cette propriété détermine de quelle manière la bordure GuiObject est disposée par rapport à ses dimensions en utilisant l'Enum du même nom, Enum.BorderMode .

Notez que UIStroke peut annuler cette propriété et permettre des effets de bord plus avancés.

BorderSizePixel

Lecture parallèle

Cette propriété détermine à quel point la bordure GuiObject est large, en pixels. Le réglage à 0 désactive complètement la bordure.

Notez que UIStroke peut annuler cette propriété et permettre des effets de bord plus avancés.

Échantillons de code

This code sample causes the border of a parent GuiObject to highlight when the user hovers their mouse over the element.

Button Highlight

-- Put me inside some GuiObject, preferrably an ImageButton/TextButton
local button = script.Parent
local function onEnter()
button.BorderSizePixel = 2
button.BorderColor3 = Color3.new(1, 1, 0) -- Yellow
end
local function onLeave()
button.BorderSizePixel = 1
button.BorderColor3 = Color3.new(0, 0, 0) -- Black
end
-- Connect events
button.MouseEnter:Connect(onEnter)
button.MouseLeave:Connect(onLeave)
-- Our default state is "not hovered"
onLeave()

ClipsDescendants

Lecture parallèle

Cette propriété détermine si la GuiObject va couper (rendre invisible) toute partie des éléments de la GUI descendante qui autrement rendrait en dehors des limites du rectangle.

Notez que Rotation n'est pas pris en charge par cette propriété.Si cette ou n'importe quelle interface utilisateur ancestrale a un non zéro , cette propriété est ignorée et les éléments de l'interface utilisateur descendante seront rendus indépendamment de la valeur de cette propriété.

Lecture uniquement
Non répliqué
Lecture parallèle

Lorsque le doigt du joueur est tapé et maintenu sur le GuiObject, le GuiState du GuiObject sera réglé sur Press .De même, lorsque le doigt du joueur est libéré de la GuiObject , le GuiState du GuiObject sera réglé sur Idle , et lorsque Interactable est désactivé sur le GuiObject , le Class.GuiState du GuiObject sera réglé sur NonInteractable .

Interactable

Lecture parallèle

Détermine si la GuiButton peut être interagie ou non, ou si la GuiState du GuiObject change ou non.

Sur un GuiButton :

Sur un GuiObject :

LayoutOrder

Lecture parallèle

Cette propriété contrôle l'ordre de tri de la GuiObject lors de l'utilisation d'un UIGridStyleLayout (comme UIListLayout ou UIPageLayout ) avec SortOrder défini sur Enum.SortOrder.LayoutOrder .Il n'a pas de fonctionnalité si l'objet n'a pas de structure de mise en page d'interface utilisateur frère.

GuiObjects sont triés dans l'ordre ascendant où les valeurs inférieures prennent la priorité sur les valeurs plus élevées.Les objets ayant la même valeur retournent à l'ordre dans lequel ils ont été ajoutés.

Si vous n'êtes pas sûr de devoir ajouter un élément entre deux éléments existants à l'avenir, il est une bonne pratique d'utiliser des multiples de 100 (0 , 100 , 200 , etc.).Cela garantit un large écart de valeurs d'ordre de mise en page que vous pouvez utiliser pour les éléments commandés entre d'autres éléments.

Voir aussi qui détermine l'ordre de rendu de l'objet au lieu de trier l'ordre.

NextSelectionDown

Lecture parallèle

Cette propriété définit la GuiObject sélectionnée lorsque l'utilisateur déplace le sélecteur du gamepad vers le bas.Si cette propriété est vide, déplacer le gamepad vers le bas ne changera pas l'interface utilisateur graphiquesélectionnée.

Déplacer le sélecteur de manette de jeu vers le bas définit le GuiService.SelectedObject à cet objet à moins que la GUI ne soit pas Selectable .Notez que cette propriété peut être définie sur un élément GUI même si ce n'est pas Selectable, vous devez donc vous assurer que la valeur d'une propriété sélectionnable de interface utilisateur graphiquecorrespond à votre comportement attendu.

Voir aussi NextSelectionUp , NextSelectionLeft , et NextSelectionRight .

Échantillons de code

This example demonstrates how to enable Gamepad navigation through a grid of GuiObject|GUI elements without manually having to connect the GuiObject.NextSelectionUp, GuiObject.NextSelectionDown, and GuiObject|NextSelectionRight, and GuiObject.NextSelectionLeft properties for every element in the grid.

Note that this code sample assumes your UIGridLayout is sorted by name, where elements are named in successive numerical order.

The code relies on this to set the NextSelection properties for all GuiObjects in the same level as the UIGridLayout. In our example, the UIGridLayoutObject and GUI elements within the grid are all children of a Frame named "Container". The code gets the children of "Container" and loops through each child. Children that are not GuiObjects are ignored. For each GUI element, the code attempts to assigned the NextSelection properties using the following logic:

  1. Starting with 1, the name of all GUI elements match their position in the grid
  2. Left: The item to the left will always be numbered 1 less than the current element
  3. Right: The item to the left will always be numbered 1 more than the current element
  4. Up: The item above (up) will always be number of GUIs in a row 1 less than the current element
  5. Down: The item below (down) will always be the number of GUIs in a row more than the current element This logic also allows for the GUI elements at the begging and end of rows (excluding the first and last element) to wrap around to the next and previous rows. If an element doesn't exist to the left, right, up, or down, the NextSelection will remain nil and moving the Gamepad selector in the direction will not change the selected GUI.

This example also contains code to test the grid using the arrow keys (Up, Down, Left, Right) of your keyboard instead of a gamepad, just in case you don't have a gamepad to test with. This portion of code initially selects the element named "1" by assigning it to the GuiService.SelectedObject property.

Creating a Gamepad Selection Grid

-- Setup the Gamepad selection grid using the code below
local container = script.Parent:FindFirstChild("Container")
local grid = container:GetChildren()
local rowSize = container:FindFirstChild("UIGridLayout").FillDirectionMaxCells
for _, gui in pairs(grid) do
if gui:IsA("GuiObject") then
local pos = gui.Name
-- Left edge
gui.NextSelectionLeft = container:FindFirstChild(pos - 1)
-- Right edge
gui.NextSelectionRight = container:FindFirstChild(pos + 1)
-- Above
gui.NextSelectionUp = container:FindFirstChild(pos - rowSize)
-- Below
gui.NextSelectionDown = container:FindFirstChild(pos + rowSize)
end
end
-- Test the Gamepad selection grid using the code below
local GuiService = game:GetService("GuiService")
local UserInputService = game:GetService("UserInputService")
GuiService.SelectedObject = container:FindFirstChild("1")
function updateSelection(input)
if input.UserInputType == Enum.UserInputType.Keyboard then
local key = input.KeyCode
local selectedObject = GuiService.SelectedObject
if not selectedObject then
return
end
if key == Enum.KeyCode.Up then
if not selectedObject.NextSelectionUp then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Down then
if not selectedObject.NextSelectionDown then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Left then
if not selectedObject.NextSelectionLeft then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Right then
if not selectedObject.NextSelectionRight then
GuiService.SelectedObject = selectedObject
end
end
end
end
UserInputService.InputBegan:Connect(updateSelection)

NextSelectionLeft

Lecture parallèle

Cette propriété définit la sélectionnée lorsque l'utilisateur déplace le sélecteur de la manette de jeu à gauche.Si cette propriété est vide, déplacer la manette de jeu à gauche ne changera pas l'interface utilisateur graphiquesélectionnée.

Déplacer le sélecteur de manette de jeu à gauche définit le GuiService.SelectedObject à cet objet à moins que la GUI ne soit pas Selectable .Notez que cette propriété peut être définie sur un élément GUI même si ce n'est pas Selectable, vous devez donc vous assurer que la valeur d'une propriété sélectionnable de interface utilisateur graphiquecorrespond à votre comportement attendu.

Voir aussi NextSelectionUp , NextSelectionDown , et NextSelectionRight .

Échantillons de code

This example demonstrates how to enable Gamepad navigation through a grid of GuiObject|GUI elements without manually having to connect the GuiObject.NextSelectionUp, GuiObject.NextSelectionDown, and GuiObject|NextSelectionRight, and GuiObject.NextSelectionLeft properties for every element in the grid.

Note that this code sample assumes your UIGridLayout is sorted by name, where elements are named in successive numerical order.

The code relies on this to set the NextSelection properties for all GuiObjects in the same level as the UIGridLayout. In our example, the UIGridLayoutObject and GUI elements within the grid are all children of a Frame named "Container". The code gets the children of "Container" and loops through each child. Children that are not GuiObjects are ignored. For each GUI element, the code attempts to assigned the NextSelection properties using the following logic:

  1. Starting with 1, the name of all GUI elements match their position in the grid
  2. Left: The item to the left will always be numbered 1 less than the current element
  3. Right: The item to the left will always be numbered 1 more than the current element
  4. Up: The item above (up) will always be number of GUIs in a row 1 less than the current element
  5. Down: The item below (down) will always be the number of GUIs in a row more than the current element This logic also allows for the GUI elements at the begging and end of rows (excluding the first and last element) to wrap around to the next and previous rows. If an element doesn't exist to the left, right, up, or down, the NextSelection will remain nil and moving the Gamepad selector in the direction will not change the selected GUI.

This example also contains code to test the grid using the arrow keys (Up, Down, Left, Right) of your keyboard instead of a gamepad, just in case you don't have a gamepad to test with. This portion of code initially selects the element named "1" by assigning it to the GuiService.SelectedObject property.

Creating a Gamepad Selection Grid

-- Setup the Gamepad selection grid using the code below
local container = script.Parent:FindFirstChild("Container")
local grid = container:GetChildren()
local rowSize = container:FindFirstChild("UIGridLayout").FillDirectionMaxCells
for _, gui in pairs(grid) do
if gui:IsA("GuiObject") then
local pos = gui.Name
-- Left edge
gui.NextSelectionLeft = container:FindFirstChild(pos - 1)
-- Right edge
gui.NextSelectionRight = container:FindFirstChild(pos + 1)
-- Above
gui.NextSelectionUp = container:FindFirstChild(pos - rowSize)
-- Below
gui.NextSelectionDown = container:FindFirstChild(pos + rowSize)
end
end
-- Test the Gamepad selection grid using the code below
local GuiService = game:GetService("GuiService")
local UserInputService = game:GetService("UserInputService")
GuiService.SelectedObject = container:FindFirstChild("1")
function updateSelection(input)
if input.UserInputType == Enum.UserInputType.Keyboard then
local key = input.KeyCode
local selectedObject = GuiService.SelectedObject
if not selectedObject then
return
end
if key == Enum.KeyCode.Up then
if not selectedObject.NextSelectionUp then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Down then
if not selectedObject.NextSelectionDown then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Left then
if not selectedObject.NextSelectionLeft then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Right then
if not selectedObject.NextSelectionRight then
GuiService.SelectedObject = selectedObject
end
end
end
end
UserInputService.InputBegan:Connect(updateSelection)

NextSelectionRight

Lecture parallèle

Cette propriété définit la sélectionnée lorsque l'utilisateur déplace le sélecteur de la manette de jeu à droite.Si cette propriété est vide, déplacer la manette de jeu à droite ne changera pas l'interface utilisateur graphiquesélectionnée.

Déplacer le sélecteur de manette de jeu à la droite définit le GuiService.SelectedObject à cet objet à moins que la GUI ne soit pas Selectable .Notez que cette propriété peut être définie sur un élément GUI même si ce n'est pas Selectable, vous devez donc vous assurer que la valeur d'une propriété sélectionnable de interface utilisateur graphiquecorrespond à votre comportement attendu.

Voir aussi NextSelectionUp , NextSelectionDown , et NextSelectionLeft .

Échantillons de code

This example demonstrates how to enable Gamepad navigation through a grid of GuiObject|GUI elements without manually having to connect the GuiObject.NextSelectionUp, GuiObject.NextSelectionDown, and GuiObject|NextSelectionRight, and GuiObject.NextSelectionLeft properties for every element in the grid.

Note that this code sample assumes your UIGridLayout is sorted by name, where elements are named in successive numerical order.

The code relies on this to set the NextSelection properties for all GuiObjects in the same level as the UIGridLayout. In our example, the UIGridLayoutObject and GUI elements within the grid are all children of a Frame named "Container". The code gets the children of "Container" and loops through each child. Children that are not GuiObjects are ignored. For each GUI element, the code attempts to assigned the NextSelection properties using the following logic:

  1. Starting with 1, the name of all GUI elements match their position in the grid
  2. Left: The item to the left will always be numbered 1 less than the current element
  3. Right: The item to the left will always be numbered 1 more than the current element
  4. Up: The item above (up) will always be number of GUIs in a row 1 less than the current element
  5. Down: The item below (down) will always be the number of GUIs in a row more than the current element This logic also allows for the GUI elements at the begging and end of rows (excluding the first and last element) to wrap around to the next and previous rows. If an element doesn't exist to the left, right, up, or down, the NextSelection will remain nil and moving the Gamepad selector in the direction will not change the selected GUI.

This example also contains code to test the grid using the arrow keys (Up, Down, Left, Right) of your keyboard instead of a gamepad, just in case you don't have a gamepad to test with. This portion of code initially selects the element named "1" by assigning it to the GuiService.SelectedObject property.

Creating a Gamepad Selection Grid

-- Setup the Gamepad selection grid using the code below
local container = script.Parent:FindFirstChild("Container")
local grid = container:GetChildren()
local rowSize = container:FindFirstChild("UIGridLayout").FillDirectionMaxCells
for _, gui in pairs(grid) do
if gui:IsA("GuiObject") then
local pos = gui.Name
-- Left edge
gui.NextSelectionLeft = container:FindFirstChild(pos - 1)
-- Right edge
gui.NextSelectionRight = container:FindFirstChild(pos + 1)
-- Above
gui.NextSelectionUp = container:FindFirstChild(pos - rowSize)
-- Below
gui.NextSelectionDown = container:FindFirstChild(pos + rowSize)
end
end
-- Test the Gamepad selection grid using the code below
local GuiService = game:GetService("GuiService")
local UserInputService = game:GetService("UserInputService")
GuiService.SelectedObject = container:FindFirstChild("1")
function updateSelection(input)
if input.UserInputType == Enum.UserInputType.Keyboard then
local key = input.KeyCode
local selectedObject = GuiService.SelectedObject
if not selectedObject then
return
end
if key == Enum.KeyCode.Up then
if not selectedObject.NextSelectionUp then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Down then
if not selectedObject.NextSelectionDown then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Left then
if not selectedObject.NextSelectionLeft then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Right then
if not selectedObject.NextSelectionRight then
GuiService.SelectedObject = selectedObject
end
end
end
end
UserInputService.InputBegan:Connect(updateSelection)

NextSelectionUp

Lecture parallèle

Cette propriété définit la GuiObject sélectionnée lorsque l'utilisateur déplace le sélecteur du gamepad vers le haut.Si cette propriété est vide, déplacer le gamepad vers le haut ne changera pas l'interface utilisateur graphiquesélectionnée.

Déplacer le sélecteur de manette de jeu vers le haut définit le GuiService.SelectedObject à cet objet à moins que la GUI ne soit pas Selectable .Notez que cette propriété peut être définie sur un élément GUI même si ce n'est pas Selectable, vous devez donc vous assurer que la valeur d'une propriété sélectionnable de interface utilisateur graphiquecorrespond à votre comportement attendu.

Voir aussi NextSelectionDown , NextSelectionLeft , NextSelectionRight .

Échantillons de code

This example demonstrates how to enable Gamepad navigation through a grid of GuiObject|GUI elements without manually having to connect the GuiObject.NextSelectionUp, GuiObject.NextSelectionDown, and GuiObject|NextSelectionRight, and GuiObject.NextSelectionLeft properties for every element in the grid.

Note that this code sample assumes your UIGridLayout is sorted by name, where elements are named in successive numerical order.

The code relies on this to set the NextSelection properties for all GuiObjects in the same level as the UIGridLayout. In our example, the UIGridLayoutObject and GUI elements within the grid are all children of a Frame named "Container". The code gets the children of "Container" and loops through each child. Children that are not GuiObjects are ignored. For each GUI element, the code attempts to assigned the NextSelection properties using the following logic:

  1. Starting with 1, the name of all GUI elements match their position in the grid
  2. Left: The item to the left will always be numbered 1 less than the current element
  3. Right: The item to the left will always be numbered 1 more than the current element
  4. Up: The item above (up) will always be number of GUIs in a row 1 less than the current element
  5. Down: The item below (down) will always be the number of GUIs in a row more than the current element This logic also allows for the GUI elements at the begging and end of rows (excluding the first and last element) to wrap around to the next and previous rows. If an element doesn't exist to the left, right, up, or down, the NextSelection will remain nil and moving the Gamepad selector in the direction will not change the selected GUI.

This example also contains code to test the grid using the arrow keys (Up, Down, Left, Right) of your keyboard instead of a gamepad, just in case you don't have a gamepad to test with. This portion of code initially selects the element named "1" by assigning it to the GuiService.SelectedObject property.

Creating a Gamepad Selection Grid

-- Setup the Gamepad selection grid using the code below
local container = script.Parent:FindFirstChild("Container")
local grid = container:GetChildren()
local rowSize = container:FindFirstChild("UIGridLayout").FillDirectionMaxCells
for _, gui in pairs(grid) do
if gui:IsA("GuiObject") then
local pos = gui.Name
-- Left edge
gui.NextSelectionLeft = container:FindFirstChild(pos - 1)
-- Right edge
gui.NextSelectionRight = container:FindFirstChild(pos + 1)
-- Above
gui.NextSelectionUp = container:FindFirstChild(pos - rowSize)
-- Below
gui.NextSelectionDown = container:FindFirstChild(pos + rowSize)
end
end
-- Test the Gamepad selection grid using the code below
local GuiService = game:GetService("GuiService")
local UserInputService = game:GetService("UserInputService")
GuiService.SelectedObject = container:FindFirstChild("1")
function updateSelection(input)
if input.UserInputType == Enum.UserInputType.Keyboard then
local key = input.KeyCode
local selectedObject = GuiService.SelectedObject
if not selectedObject then
return
end
if key == Enum.KeyCode.Up then
if not selectedObject.NextSelectionUp then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Down then
if not selectedObject.NextSelectionDown then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Left then
if not selectedObject.NextSelectionLeft then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Right then
if not selectedObject.NextSelectionRight then
GuiService.SelectedObject = selectedObject
end
end
end
end
UserInputService.InputBegan:Connect(updateSelection)

Position

Lecture parallèle

Cette propriété détermine la position GuiObject pixel et vectorielle en utilisant un UDim2 . La position est centrée autour de la position de l'objet GuiObject.AnchorPoint .

La position polynomiale est relative à la taille de l'élément GUI parent, si nécessaire.

Les parties de pixel de la valeur UDim2 sont identiques, indépendamment de la taille de l'interface utilisateur graphiqueparent.Les valeurs représentent la position de l'objet en pixels.La position réelle des pixels d'un objet peut être lue à partir de la propriété GuiBase2d.AbsolutePosition.

Rotation

Lecture parallèle

Cette propriété détermine le nombre de degrés par lesquels le GuiObject est pivoté.La rotation est relative au centre de l'objet, pas au point de rotation , ce qui signifie que vous ne pouvez pas modifier le point de rotation.De plus, cette propriété n'est pas compatible avec ClipsDescendants .

Selectable

Lecture parallèle

Cette propriété détermine si la GuiObject peut être sélectionnée lors de la navigation dans les interfaces graphiques en utilisant une manette de jeu.

Si cette propriété est true, une interface graphique peut être sélectionnée. Sélectionner une interface graphique définit également la propriété GuiService.SelectedObject à cet objet.

Lorsque ceci est false, l'interface graphique ne peut pas être sélectionnée.Cependant, définir ceci à false lorsqu'une interface graphique est sélectionnée ne le désélectionnera pas ni ne changera la valeur de la propriété GuiService.SelectedObject.

Ajoutez GuiObject.SelectionGained et GuiObject.SelectionLost ne sera pas tiré pour l'élément. Pour désélectionner un GuiObject, vous devez modifier la propriété GuiService.SelectedObject.

Cette propriété est utile si une interface graphique est connectée à plusieurs interfaces graphiques via des propriétés telles que cette GuiObject.NextSelectionUp, GuiObject.NextSelectionDown, NextSelectionRight ou NextSelectionLeft.Au lieu de modifier toutes les propriétés afin que la manette ne puisse pas sélectionner l'interface utilisateur graphique, vous pouvez désactiver sa propriété sélectionnable pour l'empêcher temporairement d'être sélectionnée.Ensuite, lorsque vous voulez que le sélecteur de manette puisse sélectionner l'interface utilisateur graphique, réactivez simplement sa propriété sélectionnable.

Échantillons de code

The example below offers a simple demonstration on how to use the GuiObject.Selectable property to limit when a GUI element can be selected by the Gamepad navigator.

When a TextBox has gains focus, it can be selected. However, when a TextBox loses focus it can no longer be selected.

Although this is a simple demonstration, the property can also be used to prevent the navigator from selecting UI elements that exist for cosmetic rather than functional purposes. For instance, while the buttons on a menu screen should be selectable, the title image should not be.

Limiting TextBox Selection

local GuiService = game:GetService("GuiService")
local textBox = script.Parent
local function gainFocus()
textBox.Selectable = true
GuiService.SelectedObject = textBox
end
local function loseFocus(_enterPressed, _inputObject)
GuiService.SelectedObject = nil
textBox.Selectable = false
end
-- The FocusLost and FocusGained event will fire because the textBox
-- is of type TextBox
textBox.Focused:Connect(gainFocus)
textBox.FocusLost:Connect(loseFocus)

SelectionImageObject

Lecture parallèle

Cette propriété remplace la sélection par défaut utilisée pour les gamepads.

Remarquez que le choisi SelectionImageObject superpose le sélectionné GuiObject avec le Size de l'image.Pour obtenir les meilleurs résultats, vous devez dimensionner le personnalisé SelectionImageObject via les valeurs de l'échelle UDim2 pour aider à garantir que l'objet s'échelle correctement sur l'élément sélectionné.

Changer le SelectionImageObject pour un élément GuiObject affecte seulement cet élément. Pour affecter tous les éléments de l'interface graphique d'un utilisateur, définissez la propriété PlayerGui.SelectionImageObject.

Pour déterminer ou définir l'élément GUI sélectionné par l'utilisateur, vous pouvez utiliser la propriété GuiService.SelectedObject.Le joueur utilise la manette de jeu pour sélectionner différents éléments d'interface graphique, en invoquant les événements NextSelectionUp, NextSelectionDown, NextSelectionLeft et NextSelectionRight.

SelectionOrder

Lecture parallèle

Les objets GUI avec un ordre de sélection inférieur sont sélectionnés plus tôt que les objets GUI avec un ordre de sélection plus élevé lors du démarrage de la sélection du gamepad ou de l'appel de GuiService:Select() sur un ancêtre.Cette propriété n'affecte pas la navigation directionnelle.La valeur par défaut est 0.

Size

Lecture parallèle

Cette propriété détermine la taille GuiObject duscal et du pixel en utilisant un UDim2.

La taille polynomiale est relative à la taille de l'élément GUI parent, si nécessaire.

Les parties de pixel de la valeur UDim2 sont identiques, indépendamment de la taille de l'interface utilisateur graphiqueparent.Les valeurs représentent la taille de l'objet en pixels.La taille réelle des pixels d'un objet peut être lue à partir de la propriété GuiBase2d.AbsoluteSize.

Si le GuiObject a un parent, sa taille le long de chaque axe est également influencée par celle du parent SizeConstraint.

Échantillons de code

This code sample allows you to create a simple color-changing health bar using two nested Frames. Paste this into a LocalScript on the inner frame.

Health Bar

local Players = game:GetService("Players")
local player = Players.LocalPlayer
-- Paste script into a LocalScript that is
-- parented to a Frame within a Frame
local frame = script.Parent
local container = frame.Parent
container.BackgroundColor3 = Color3.new(0, 0, 0) -- black
-- This function is called when the humanoid's health changes
local function onHealthChanged()
local human = player.Character.Humanoid
local percent = human.Health / human.MaxHealth
-- Change the size of the inner bar
frame.Size = UDim2.new(percent, 0, 1, 0)
-- Change the color of the health bar
if percent < 0.1 then
frame.BackgroundColor3 = Color3.new(1, 0, 0) -- black
elseif percent < 0.4 then
frame.BackgroundColor3 = Color3.new(1, 1, 0) -- yellow
else
frame.BackgroundColor3 = Color3.new(0, 1, 0) -- green
end
end
-- This function runs is called the player spawns in
local function onCharacterAdded(character)
local human = character:WaitForChild("Humanoid")
-- Pattern: update once now, then any time the health changes
human.HealthChanged:Connect(onHealthChanged)
onHealthChanged()
end
-- Connect our spawn listener; call it if already spawned
player.CharacterAdded:Connect(onCharacterAdded)
if player.Character then
onCharacterAdded(player.Character)
end

SizeConstraint

Lecture parallèle

Cette propriété définit les axes Size sur lesquels la GuiObject sera basée, par rapport à la taille de son parent.

Cette propriété est utile pour créer des objets GUI qui doivent s'adapter à la largeur ou de la hauteur d'un objet parent, mais pas les deux, en conservant efficacement la proportion de l'objet.

Transparency

Caché
Non répliqué
Lecture parallèle

Une propriété mixée de BackgroundTransparency et TextTransparency.

Visible

Lecture parallèle

Cette propriété si la GuiObject et ses descendants seront rendus.

La rendu des composants individuels d'un GuiObject peut être contrôlé individuellement via des propriétés de transparence telles que GuiObject.BackgroundTransparency , TextLabel.TextTransparency et ImageLabel.ImageTransparency .

Lorsque cette propriété est false, la GuiObject sera ignorée par les structures de mise en page telles que UIListLayout, UIGridLayout et UITableLayout.En d'autres termes, l'espace que l'élément occuperait autrement dans la mise en page est utilisé par d'autres éléments à la place.

Échantillons de code

This code sample adds open/close functionality to a Window UI. Paste as a LocalScript that is a sibling of a Frame named Window, a TextButton/ImageButton named Window, and a TextButton/ImageButton within the Window called Close.

UI Window

local gui = script.Parent
local window = gui:WaitForChild("Window")
local toggleButton = gui:WaitForChild("ToggleWindow")
local closeButton = window:WaitForChild("Close")
local function toggleWindowVisbility()
-- Flip a boolean using the `not` keyword
window.Visible = not window.Visible
end
toggleButton.Activated:Connect(toggleWindowVisbility)
closeButton.Activated:Connect(toggleWindowVisbility)

ZIndex

Lecture parallèle

Cette propriété détermine l'ordre dans lequel un GuiObject rendu se rapporte aux autres.

Par défaut, GuiObjects rendre dans l'ordre de priorité ascendant où ceux avec des valeurs inférieures ZIndex sont rendus sous ceux avec des valeurs plus élevées.Vous pouvez modifier l'ordre de rendu dans un ScreenGui , SurfaceGui ou BillboardGui en modifiant la valeur de son ZIndexBehavior .

Si vous n'êtes pas sûr de devoir ajouter un élément entre deux éléments existants à l'avenir, il est une bonne pratique d'utiliser des multiples de 100 (0 , 100 , 200 , etc.).Cela garantit un grand écart de valeurs d'ordre de rendu que vous pouvez utiliser pour les éléments superposés entre d'autres éléments.

Voir aussi LayoutOrder qui contrôle l'ordre de tri trier d'un GuiObject lorsqu'il est utilisé avec une structure de mise en page telle que UIListLayout ou UIGridLayout .

Méthodes

TweenPosition

Déplace doucement une interface graphique vers une nouvelle position UDim2 dans le temps spécifié en utilisant les spécifiés Enum.EasingDirection et Enum.EasingStyle.

Cette fonction retournera si l'adolescent jouera.Il ne jouera pas si un autre adolescent agit sur le GuiObject et le paramètre d'annulation est false .

Voir aussi GuiObject:TweenSize() et GuiObject:TweenSizeAndPosition() .

Paramètres

endPosition: UDim2

Où la GUI devrait se déplacer.

Valeur par défaut : ""
easingDirection: Enum.EasingDirection

La direction dans laquelle faciliter la GUI vers la position de fin.

Valeur par défaut : "Out"
easingStyle: Enum.EasingStyle

Le style dans lequel faciliter l'interface utilisateur jusqu'à la position de fin endPosition.

Valeur par défaut : "Quad"
time: number

Combien de temps, en secondes, le préadolescent devrait prendre pour se terminer.

Valeur par défaut : 1
override: boolean

Si l'adolescent remplacera un tweenen cours.

Valeur par défaut : false
callback: function

Une fonction de rappel à exécuter lorsque le tween est terminé.

Valeur par défaut : "nil"

Retours

Si l'adolescent jouera ou non.

Échantillons de code

This code sample demonstrates a more involved usage of TweenPosition by detecting when the tween completes/cancels by defining a callback function. It also prints whether the tween will play.

Tween a GUI's Position

local START_POSITION = UDim2.new(0, 0, 0, 0)
local GOAL_POSITION = UDim2.new(1, 0, 1, 0)
local guiObject = script.Parent
local function callback(state)
if state == Enum.TweenStatus.Completed then
print("The tween completed uninterrupted")
elseif state == Enum.TweenStatus.Canceled then
print("Another tween cancelled this one")
end
end
-- Initialize the GuiObject position, then start the tween:
guiObject.Position = START_POSITION
local willPlay = guiObject:TweenPosition(
GOAL_POSITION, -- Final position the tween should reach
Enum.EasingDirection.In, -- Direction of the easing
Enum.EasingStyle.Sine, -- Kind of easing to apply
2, -- Duration of the tween in seconds
true, -- Whether in-progress tweens are interrupted
callback -- Function to be callled when on completion/cancelation
)
if willPlay then
print("The tween will play")
else
print("The tween will not play")
end

TweenSize

Redimensionne sans problème un GuiObject à un nouveau UDim2 dans le temps spécifié en utilisant le Enum.EasingDirection et le Enum.EasingStyle spécifiés.

Cette fonction retournera si l'adolescent jouera.Normalement, cela retournera toujours true, mais il retournera false si un autre adolescent est actif et l'annulation est définie sur false .

Voir aussi GuiObject:TweenSize() et GuiObject:TweenSizeAndPosition() .

Paramètres

endSize: UDim2

La taille que la GUI devrait ajuster.

Valeur par défaut : ""
easingDirection: Enum.EasingDirection

La direction dans laquelle faciliter l'interface utilisateur vers la fin de la taille endSize.

Valeur par défaut : "Out"
easingStyle: Enum.EasingStyle

Le style dans lequel faciliter l'interface utilisateur jusqu'à la taille finale endSize.

Valeur par défaut : "Quad"
time: number

Combien de temps, en secondes, le préadolescent devrait prendre pour se terminer.

Valeur par défaut : 1
override: boolean

Si l'adolescent remplacera un tweenen cours.

Valeur par défaut : false
callback: function

Une fonction de rappel à exécuter lorsque le tween est terminé.

Valeur par défaut : "nil"

Retours

Si l'adolescent jouera ou non.

Échantillons de code

This code sample demonstrates the usage of the GuiObject:TweenSize() function. It initiates an animation on the parent's GuiObject.Size property to UDim2.new(0.5, 0, 0.5, 0), which is half the GuiObject's parent size on both axes.

Additionally, it demonstrates how the callback parameter can be used to detect when the tween stops (whether it was cancelled by another tween or completed).

Tween a GuiObject's Size

local guiObject = script.Parent
local function callback(didComplete)
if didComplete then
print("The tween completed successfully")
else
print("The tween was cancelled")
end
end
local willTween = guiObject:TweenSize(
UDim2.new(0.5, 0, 0.5, 0), -- endSize (required)
Enum.EasingDirection.In, -- easingDirection (default Out)
Enum.EasingStyle.Sine, -- easingStyle (default Quad)
2, -- time (default: 1)
true, -- should this tween override ones in-progress? (default: false)
callback -- a function to call when the tween completes (default: nil)
)
if willTween then
print("The GuiObject will tween")
else
print("The GuiObject will not tween")
end

TweenSizeAndPosition

Redimensionne et déplace doucement une interface graphique à une nouvelle taille et position dans le temps spécifié en utilisant les tailles et positions spécifiées et .

Cette fonction retournera si l'adolescent jouera.Normalement, cela retournera toujours true, mais il retournera false si un autre adolescent est actif et l'annulation est définie sur false .

Voir aussi GuiObject:TweenSize() et GuiObject:TweenSizeAndPosition() .

Paramètres

endSize: UDim2

La taille que la GUI devrait ajuster.

Valeur par défaut : ""
endPosition: UDim2

Où la GUI devrait se déplacer.

Valeur par défaut : ""
easingDirection: Enum.EasingDirection

La direction dans laquelle faciliter la GUI vers la fin endSize et endPosition.

Valeur par défaut : "Out"
easingStyle: Enum.EasingStyle

Le style dans lequel faciliter l'interface utilisateur jusqu'au endSize et endPosition.

Valeur par défaut : "Quad"
time: number

Combien de temps, en secondes, le préadolescent devrait prendre pour se terminer.

Valeur par défaut : 1
override: boolean

Si l'adolescent remplacera un tweenen cours.

Valeur par défaut : false
callback: function

Une fonction de rappel à exécuter lorsque le tween est terminé.

Valeur par défaut : "nil"

Retours

Si l'adolescent jouera ou non.

Échantillons de code

The below example would tween a Frame to the top left of the parent's size and resize it down to 0.

Tween a GUI's Size and Position

local frame = script.Parent.Frame
frame:TweenSizeAndPosition(UDim2.new(0, 0, 0, 0), UDim2.new(0, 0, 0, 0))

Évènements

InputBegan

Cet événement se déclenche lorsqu'un utilisateur commence à interagir avec le GuiObject via un appareil d'interface homme-ordinateur (bouton de souris vers le bas, toucher de début, bouton de clavier vers le bas, etc.).

Le UserInputService a un événement de même nom qui n'est pas limité à un élément d'interface utilisateur spécifique : UserInputService.InputBegan .

Cet événement se déclenchera toujours indépendamment de l'état du jeu.

Voir aussi GuiObject.InputEnded et GuiObject.InputChanged .

Paramètres

Un InputObject , qui contient des données utiles pour interroger l'entrée de l'utilisateur telles que le type of input , state of input et screen coordinates of the input .


Échantillons de code

The following example demonstrates one of many usage examples of handling user input from InputBegan depending on its type.

In order for this to work as expected, it must be placed in a LocalScript and a child of gui.

Tracking the Beginning of Input on a GuiObject

-- In order to use the InputBegan event, you must specify the GuiObject
local gui = script.Parent
-- A sample function providing multiple usage cases for various types of user input
local function inputBegan(input)
if input.UserInputType == Enum.UserInputType.Keyboard then
print("A key is being pushed down! Key:", input.KeyCode)
elseif input.UserInputType == Enum.UserInputType.MouseButton1 then
print("The left mouse button has been pressed down at", input.Position)
elseif input.UserInputType == Enum.UserInputType.MouseButton2 then
print("The right mouse button has been pressed down at", input.Position)
elseif input.UserInputType == Enum.UserInputType.Touch then
print("A touchscreen input has started at", input.Position)
elseif input.UserInputType == Enum.UserInputType.Gamepad1 then
print("A button is being pressed on a gamepad! Button:", input.KeyCode)
end
end
gui.InputBegan:Connect(inputBegan)

InputChanged

Cet événement se déclenche lorsqu'un utilisateur modifie la façon dont il interagit via un appareil d'interface homme-ordinateur (bouton de souris vers le bas, début du toucher, bouton du clavier vers le bas, etc.).

Le UserInputService a un événement de même nom qui n'est pas limité à un élément d'interface utilisateur spécifique : UserInputService.InputChanged .

Cet événement se déclenchera toujours indépendamment de l'état du jeu.

Voir aussi GuiObject.InputBegan et GuiObject.InputEnded .

Paramètres

Un InputObject , qui contient des données utiles pour interroger l'entrée de l'utilisateur telles que le type of input , state of input et screen coordinates of the input .


Échantillons de code

The following example demonstrates one of many usage examples of handling user input from InputChanged depending on its type.

In order for this to work as expected, it must be placed in a LocalScript and a child of gui.

GuiObject InputChanged Demo

local UserInputService = game:GetService("UserInputService")
local gui = script.Parent
local function printMovement(input)
print("Position:", input.Position)
print("Movement Delta:", input.Delta)
end
local function inputChanged(input)
if input.UserInputType == Enum.UserInputType.MouseMovement then
print("The mouse has been moved!")
printMovement(input)
elseif input.UserInputType == Enum.UserInputType.MouseWheel then
print("The mouse wheel has been scrolled!")
print("Wheel Movement:", input.Position.Z)
elseif input.UserInputType == Enum.UserInputType.Gamepad1 then
if input.KeyCode == Enum.KeyCode.Thumbstick1 then
print("The left thumbstick has been moved!")
printMovement(input)
elseif input.KeyCode == Enum.KeyCode.Thumbstick2 then
print("The right thumbstick has been moved!")
printMovement(input)
elseif input.KeyCode == Enum.KeyCode.ButtonL2 then
print("The pressure being applied to the left trigger has changed!")
print("Pressure:", input.Position.Z)
elseif input.KeyCode == Enum.KeyCode.ButtonR2 then
print("The pressure being applied to the right trigger has changed!")
print("Pressure:", input.Position.Z)
end
elseif input.UserInputType == Enum.UserInputType.Touch then
print("The user's finger is moving on the screen!")
printMovement(input)
elseif input.UserInputType == Enum.UserInputType.Gyro then
local _rotInput, rotCFrame = UserInputService:GetDeviceRotation()
local rotX, rotY, rotZ = rotCFrame:toEulerAnglesXYZ()
local rot = Vector3.new(math.deg(rotX), math.deg(rotY), math.deg(rotZ))
print("The rotation of the user's mobile device has been changed!")
print("Position", rotCFrame.p)
print("Rotation:", rot)
elseif input.UserInputType == Enum.UserInputType.Accelerometer then
print("The acceleration of the user's mobile device has been changed!")
printMovement(input)
end
end
gui.InputChanged:Connect(inputChanged)

InputEnded

L'événement InputEnded se déclenche lorsqu'un utilisateur cesse d'interagir via un appareil d'interface homme-ordinateur (bouton de souris vers le bas, début du toucher, bouton du clavier vers le bas, etc.).

Le UserInputService a un événement de même nom qui n'est pas limité à un élément d'interface utilisateur spécifique : UserInputService.InputEnded .

Cet événement se déclenchera toujours indépendamment de l'état du jeu.

Voir aussi GuiObject.InputBegan et GuiObject.InputChanged .

Paramètres

Un InputObject , qui contient des données utiles pour interroger l'entrée de l'utilisateur telles que le Enum.UserInputType , Enum.UserInputState et InputObject.Position .


Échantillons de code

The following example demonstrates one of many usage examples of handling user input from InputEnded depending on its type.

In order for this to work as expected, it must be placed in a LocalScript and a child of gui.

Tracking the End of Input on a GuiObject

-- In order to use the InputChanged event, you must specify a GuiObject
local gui = script.Parent
-- A sample function providing multiple usage cases for various types of user input
local function inputEnded(input)
if input.UserInputType == Enum.UserInputType.Keyboard then
print("A key has been released! Key:", input.KeyCode)
elseif input.UserInputType == Enum.UserInputType.MouseButton1 then
print("The left mouse button has been released at", input.Position)
elseif input.UserInputType == Enum.UserInputType.MouseButton2 then
print("The right mouse button has been released at", input.Position)
elseif input.UserInputType == Enum.UserInputType.Touch then
print("A touchscreen input has been released at", input.Position)
elseif input.UserInputType == Enum.UserInputType.Gamepad1 then
print("A button has been released on a gamepad! Button:", input.KeyCode)
end
end
gui.InputEnded:Connect(inputEnded)

MouseEnter

L'événement MouseEnter se déclenche lorsqu'un utilisateur déplace sa souris dans un élément GuiObject.

Ne vous fiez pas aux arguments x et y passés par cet événement comme moyen infaillible de déterminer où se trouve la souris de l'utilisateur lorsqu'elle entre dans une interface interface utilisateur graphique.Ces coordonnées peuvent varier même lorsque la souris entre dans l'interface graphique via le même bord - notamment lorsque la souris entre rapidement dans l'élément.Cela est dû au fait que les coordonnées indiquent la position de la souris lorsque l'événement se déclenche plutôt que le moment exact où la souris entre dans la interface utilisateur graphique.

Cet événement se déclenche même lorsque l'élément GUI se rend sous un autre élément.

Si vous souhaitez suivre quand la souris d'un utilisateur quitte un élément GUI, vous pouvez utiliser l'événement GuiObject.MouseLeave.

Voir aussi

Paramètres

La coordonnée d'écran de la souris X en pixels, relative au coin supérieur gauche de l'écran.

La coordonnée d'écran de la souris Y en pixels, relative au coin supérieur gauche de l'écran.


Échantillons de code

The following example prints the mouse location, in pixels, when it enters GUI element.

Printing where a Mouse Enters a GuiObject

local guiObject = script.Parent
guiObject.MouseEnter:Connect(function(x, y)
print("The user's mouse cursor has entered the GuiObject at position", x, ",", y)
end)

MouseLeave

L'événement MouseLeave se déclenche lorsqu'un utilisateur déplace sa souris hors d'un élément GuiObject.

Ne vous fiez pas aux arguments x et y passés par cet événement comme moyen infaillible de déterminer où se trouve la souris de l'utilisateur lorsqu'elle quitte une interface interface utilisateur graphique.Ces coordonnées peuvent varier même lorsque la souris quitte la GUI via le même bord - notamment lorsque la souris quitte l'élément rapidement.Cela est dû au fait que les coordonnées indiquent la position de la souris lorsque l'événement se déclenche plutôt que le moment exact où la souris quitte l'interface interface utilisateur graphique.

Cet événement se déclenche même lorsque l'élément GUI se rend sous un autre élément.

Voir aussi

Paramètres

La coordonnée d'écran de la souris X en pixels, relative au coin supérieur gauche de l'écran.

La coordonnée d'écran de la souris Y en pixels, relative au coin supérieur gauche de l'écran.


MouseMoved

S'enflamme chaque fois qu'un utilisateur déplace sa souris alors qu'elle se trouve à l'intérieur d'un élément GuiObject.Il est similaire à Mouse.Move , qui se déclenche indépendamment du fait que la souris de l'utilisateur soit sur un élément GUI.

Notez que cet événement se déclenche lorsque la position de la souris est mise à jour, il se déclenchera donc à plusieurs reprises pendant qu'elle est déplacée.

Les arguments x et y indiquent les coordonnées d'écran mises à jour de la souris de l'utilisateur en pixels.Ces derniers peuvent être utiles pour déterminer la position de la souris sur l'interface interface utilisateur graphique, l'écran et le delta depuis la position précédente de la souris si elle est suivie dans une variable globale.

Le code ci-dessous montre comment déterminer le décalage Vector2 de la souris de l'utilisateur par rapport à un élément GUI :


local Players = game:GetService("Players")
local CustomScrollingFrame = script.Parent
local SubFrame = CustomScrollingFrame:FindFirstChild("SubFrame")
local mouse = Players.LocalPlayer:GetMouse()
local function getPosition(X, Y)
local gui_X = CustomScrollingFrame.AbsolutePosition.X
local gui_Y = CustomScrollingFrame.AbsolutePosition.Y
local pos = Vector2.new(math.abs(X - gui_X), math.abs(Y - gui_Y - 36))
print(pos)
end
CustomScrollingFrame.MouseMoved:Connect(getPosition)

Notez que cet événement peut ne pas se déclencher exactement lorsque la souris de l'utilisateur entre ou quitte un élément de GUI.Les arguments x et y peuvent donc ne pas correspondre parfaitement aux coordonnées des bords de l'interface interface utilisateur graphique.

Voir aussi

Paramètres

La coordonnée d'écran de la souris X en pixels, relative au coin supérieur gauche de l'écran.

La coordonnée d'écran de la souris Y en pixels, relative au coin supérieur gauche de l'écran.


MouseWheelBackward

L'événement WheelBackward se déclenche lorsqu'un utilisateur fait défiler la molette de sa souris en arrière lorsque la souris se trouve sur un élément GuiObject.Il est similaire à Mouse.WheelBackward , qui se déclenche indépendamment du fait que la souris de l'utilisateur soit sur un élément GUI.

Cet événement se déclenche simplement comme un indicateur du mouvement en arrière de la roue.Cela signifie que les arguments de coordonnées de la souris x et y ne changent pas en raison de cet événement.Ces coordonnées ne changent que lorsque la souris se déplace, ce qui peut être suivi par l'événement GuiObject.MouseMoved.

Voir aussi

Paramètres

La coordonnée d'écran de la souris X en pixels, relative au coin supérieur gauche de l'écran.

La coordonnée d'écran de la souris Y en pixels, relative au coin supérieur gauche de l'écran.


MouseWheelForward

L'événement WheelForward se déclenche lorsqu'un utilisateur fait défiler sa roue de souris vers l'avant lorsque la souris se trouve sur un élément GuiObject.Il est similaire à Mouse.WheelForward , qui se déclenche indépendamment du fait que la souris de l'utilisateur soit sur un élément GUI.

Cet événement se déclenche simplement comme indicateur du mouvement en avant de la roue.Cela signifie que les arguments de coordonnées de la souris X et Y ne changent pas en raison de cet événement.Ces coordonnées ne changent que lorsque la souris se déplace, ce qui peut être suivi par l'événement GuiObject.MouseMoved.

Voir aussi

Paramètres

La coordonnée d'écran de la souris X en pixels, relative au coin supérieur gauche de l'écran.

La coordonnée Y de la souris de l'utilisateur.


SelectionGained

Cet événement se déclenche lorsque le sélecteur de manette de jeu commence à se concentrer sur le GuiObject.

Si vous voulez vérifier à partir de la manette de jeu, sélectionnez les arrêts qui se focalisent sur l'élément GUI, vous pouvez utiliser l'événement GuiObject.SelectionLost.

Lorsqu'une interface graphique gagne le focus de sélection, la valeur de la propriété SelectedObject change également pour celle qui gagne la sélection.Pour déterminer laquelle GUI a gagné la sélection, vérifiez la valeur de cette propriété.


Échantillons de code

The following example prints a message when the user selects the object with a gamepad.

In order for this to work as expected, it must be placed in a LocalScript and a child of gui.

Handling GUI Selection Gained

local guiObject = script.Parent
local function selectionGained()
print("The user has selected this button with a gamepad.")
end
guiObject.SelectionGained:Connect(selectionGained)

SelectionLost

Cet événement se déclenche lorsque le sélecteur de manette arrête de se concentrer sur le GuiObject.

Si vous voulez vérifier à partir de la manette de jeu, le début de la concentration se focalise sur l'élément GUI, vous pouvez utiliser l'événement GuiObject.SelectionGained.

Lorsqu'une interface graphique perd le focus de sélection, la valeur de la propriété SelectionObject change soit à nil ou à l'élément de l'interface graphique qui gagne le focus de sélection.Pour déterminer quelle GUI a gagné la sélection, ou si aucune GUI n'est sélectionnée, vérifiez la valeur de cette propriété.


Échantillons de code

The following example prints a message when the element has its focus lost on a gamepad.

In order for this to work as expected, it must be placed in a LocalScript and a child of gui.

Handling GUI Selection Lost

local guiObject = script.Parent
local function selectionLost()
print("The user no longer has this selected with their gamepad.")
end
guiObject.SelectionLost:Connect(selectionLost)

TouchLongPress

Cet événement se déclenche après un bref moment lorsque le joueur maintient son doigt sur l'élément d'interface utilisateur en utilisant un appareil tactile.Il tire avec une table de Vector2 qui décrit les positions relatives des écrans des doigts impliqués dans le geste.En outre, il se déclenche plusieurs fois : Enum.UserInputState.Begin après un court délai, Enum.UserInputState.Change si le joueur déplace son doigt pendant la gestuelle, et enfin Enum.UserInputState.End .Le délai est plateforme dépendant ; dans Studio, c'est un peu plus long qu'une seconde.

Puisque cet événement ne nécessite qu'un doigt, cet événement peut être simulé dans Studio en utilisant l'émulateur et une souris.

Paramètres

touchPositions: Array

Un ensemble de Vector2 qui décrivent les positions relatives des doigts impliqués dans le geste.

Un Enum.UserInputState qui décrit l'état du geste :

  • Commencer les incendies une fois au début du geste (après le court délai)
  • Changer de feux si le joueur déplace son doigt tout en appuyant
  • Éteignez les incendies une fois à la fin du geste lorsqu'ils relâchent leur doigt.

Échantillons de code

This code sample allows the player to manipulate the screen position of some UI element, like a Frame, by holding down on the UI element for a brief moment. Then, the player moves their finger and releases. During the gesture the Frame is colored blue with a white outline.

Move UI Element with TouchLongPress

local frame = script.Parent
frame.Active = true
local dragging = false
local basePosition
local startTouchPosition
local borderColor3
local backgroundColor3
local function onTouchLongPress(touchPositions, state)
if state == Enum.UserInputState.Begin and not dragging then
-- Start a drag
dragging = true
basePosition = frame.Position
startTouchPosition = touchPositions[1]
-- Color the frame to indicate the drag is happening
borderColor3 = frame.BorderColor3
backgroundColor3 = frame.BackgroundColor3
frame.BorderColor3 = Color3.new(1, 1, 1) -- White
frame.BackgroundColor3 = Color3.new(0, 0, 1) -- Blue
elseif state == Enum.UserInputState.Change then
local touchPosition = touchPositions[1]
local deltaPosition =
UDim2.new(0, touchPosition.X - startTouchPosition.X, 0, touchPosition.Y - startTouchPosition.Y)
frame.Position = basePosition + deltaPosition
elseif state == Enum.UserInputState.End and dragging then
-- Stop the drag
dragging = false
frame.BorderColor3 = borderColor3
frame.BackgroundColor3 = backgroundColor3
end
end
frame.TouchLongPress:Connect(onTouchLongPress)

TouchPan

Cet événement se déclenche lorsque le joueur déplace son doigt sur l'élément de l'interface utilisateur en utilisant un appareil tactile.Il se déclenche peu avant que GuiObject.TouchSwipe ne le fasse, et ne se déclenche pas avec GuiObject.TouchTap.Cet événement est utile pour permettre au joueur de manipuler la position des éléments d'interface sur l'écran.

Cet événement se déclenche avec une table de Vector2 qui décrit les positions relatives des doigts impliqués dans le geste.En outre, il se déclenche plusieurs fois : Enum.UserInputState.Begin après un court délai, Enum.UserInputState.Change lorsque le joueur déplace son doigt pendant la gestuelle, et enfin avec Enum.UserInputState.End .

Cet événement ne peut pas être simulé dans Studio en utilisant l'émulateur et une souris ; vous devez avoir un appareil réel activé pour le tirer.

Paramètres

touchPositions: Array

Un tableau Luau de Vector2 objets, chacun indiquant la position de tous les doigts impliqués dans la gestuelle.

totalTranslation: Vector2

Indique jusqu'à où la gestuelle de la poêle est allée de son point de départ.

velocity: Vector2

Indique à quelle vitesse le geste est effectué dans chaque dimension.

Indique le Enum.UserInputState de la gestuelle.


Échantillons de code

This code sample is meant to be placed in a LocalScript within an inner Frame that is inside an outer Frame, or other GuiObject. It allows the player to manipulate the position of the inner frame by moving their finger on the outer frame.

Panning UI Element

local innerFrame = script.Parent
local outerFrame = innerFrame.Parent
outerFrame.BackgroundTransparency = 0.75
outerFrame.Active = true
outerFrame.Size = UDim2.new(1, 0, 1, 0)
outerFrame.Position = UDim2.new(0, 0, 0, 0)
outerFrame.AnchorPoint = Vector2.new(0, 0)
outerFrame.ClipsDescendants = true
local dragging = false
local basePosition
local function onTouchPan(_touchPositions, totalTranslation, _velocity, state)
if state == Enum.UserInputState.Begin and not dragging then
dragging = true
basePosition = innerFrame.Position
outerFrame.BackgroundTransparency = 0.25
elseif state == Enum.UserInputState.Change then
innerFrame.Position = basePosition + UDim2.new(0, totalTranslation.X, 0, totalTranslation.Y)
elseif state == Enum.UserInputState.End and dragging then
dragging = false
outerFrame.BackgroundTransparency = 0.75
end
end
outerFrame.TouchPan:Connect(onTouchPan)

TouchPinch

Cet événement se déclenche lorsque le joueur utilise deux doigts pour faire une pince ou un geste de traction sur l'élément d'interface utilisateur en utilisant un appareil tactile activé.Un pinçage se produit lorsque deux ou plusieurs doigts se rapprochent l'un de l'autre, et un tirage se produit lorsqu'ils se séparent.Cet événement se déclenche en conjonction avec GuiObject.TouchPan .Cet événement est utile pour permettre au joueur de manipuler la taille (la taille) des éléments d'interface sur l'écran, et est le plus souvent utilisé pour les fonctionnalités de zoom.

Cet événement se déclenche avec une table de Vector2 qui décrit les positions relatives des doigts impliqués dans le geste.En outre, il se déclenche plusieurs fois : Enum.UserInputState.Begin après un court délai, Enum.UserInputState.Change lorsque le joueur déplace un doigt pendant la gestuelle, et enfin avec Enum.UserInputState.End .Il est à noter que l'échelle doit être utilisée de manière multiplicative .

Puisque cet événement nécessite au moins deux doigts, il n'est pas possible de le simuler dans Studio en utilisant l'émulateur et une souris ; vous devez avoir un appareil réel activé par le toucher.

Paramètres

touchPositions: Array

Un tableau Luau de Vector2 objets, chacun indiquant la position de tous les doigts impliqués dans la gestuelle d'écrasement.

scale: number

Un flotteur qui indique la différence par rapport au début du geste d'écrasement.

velocity: number

Une flotte indiquant à quelle vitesse se produit la gestuelle de pinçage.

Indique le Enum.UserInputState de la gestuelle.


Échantillons de code

This code sample is meant for a LocalScript within an inner Frame that is inside an outer Frame, or other GuiObject. It allows the player to scale the inner frame by performing a GuiObject.TouchPinch gesture on the outer frame.

Pinch/Pull Scaling

local innerFrame = script.Parent
local outerFrame = innerFrame.Parent
outerFrame.BackgroundTransparency = 0.75
outerFrame.Active = true
outerFrame.Size = UDim2.new(1, 0, 1, 0)
outerFrame.Position = UDim2.new(0, 0, 0, 0)
outerFrame.AnchorPoint = Vector2.new(0, 0)
outerFrame.ClipsDescendants = true
local dragging = false
local uiScale = Instance.new("UIScale")
uiScale.Parent = innerFrame
local baseScale
local function onTouchPinch(_touchPositions, scale, _velocity, state)
if state == Enum.UserInputState.Begin and not dragging then
dragging = true
baseScale = uiScale.Scale
outerFrame.BackgroundTransparency = 0.25
elseif state == Enum.UserInputState.Change then
uiScale.Scale = baseScale * scale -- Notice the multiplication here
elseif state == Enum.UserInputState.End and dragging then
dragging = false
outerFrame.BackgroundTransparency = 0.75
end
end
outerFrame.TouchPinch:Connect(onTouchPinch)

TouchRotate

Cet événement se déclenche lorsque le joueur utilise deux doigts pour faire une pince ou un geste de traction sur l'élément d'interface utilisateur en utilisant un appareil tactile activé.La rotation se produit lorsque l'angle de la ligne entre deux doigts change.Cet événement se déclenche en conjonction avec GuiObject.TouchPan.Cet événement est utile pour permettre au joueur de manipuler la rotation des éléments d'interface sur l'écran.

Cet événement se déclenche avec une table de Vector2 qui décrit les positions relatives des doigts impliqués dans le geste.En outre, il se déclenche plusieurs fois : Enum.UserInputState.Begin après un court délai, Enum.UserInputState.Change lorsque le joueur déplace un doigt pendant la gestuelle, et enfin avec Enum.UserInputState.End .

Puisque cet événement nécessite au moins deux doigts, il n'est pas possible d'être simulé dans Studio en utilisant l'émulateur et une souris ; vous devez avoir un appareil réel activé par le toucher.

Paramètres

touchPositions: Array

Un tableau Luau de Vector2 objets, chacun indiquant la position de tous les doigts impliqués dans la gestuelle.

rotation: number

Un flotteur indiquant à quel point la rotation est partie du début du geste.

velocity: number

Un flotteur qui indique la rapidité avec laquelle la gestuelle est exécutée.

Indique le Enum.UserInputState de la gestuelle.


Échantillons de code

This code sample is meant for a LocalScript within an inner Frame that is inside an outer Frame, or other GuiObject. It allows the player to rotate the inner frame by performing a GuiObject.TouchRotate gesture on the outer frame.

Touch Rotation

local innerFrame = script.Parent
local outerFrame = innerFrame.Parent
outerFrame.BackgroundTransparency = 0.75
outerFrame.Active = true
outerFrame.Size = UDim2.new(1, 0, 1, 0)
outerFrame.Position = UDim2.new(0, 0, 0, 0)
outerFrame.AnchorPoint = Vector2.new(0, 0)
outerFrame.ClipsDescendants = true
local dragging = false
local baseRotation = innerFrame.Rotation
local function onTouchRotate(_touchPositions, rotation, _velocity, state)
if state == Enum.UserInputState.Begin and not dragging then
dragging = true
baseRotation = innerFrame.Rotation
outerFrame.BackgroundTransparency = 0.25
elseif state == Enum.UserInputState.Change then
innerFrame.Rotation = baseRotation + rotation
elseif state == Enum.UserInputState.End and dragging then
dragging = false
outerFrame.BackgroundTransparency = 0.75
end
end
outerFrame.TouchRotate:Connect(onTouchRotate)

TouchSwipe

Cet événement se déclenche lorsque le joueur effectue une gestuelle de glissement sur l'élément d'interface utilisateur en utilisant un appareil tactile activé.Il tire avec la direction du geste (Haut, Bas, Gauche ou Droite) et le nombre de points de contact impliqués dans le geste.Les gestes de balayage sont souvent utilisés pour changer d'onglet dans les interfaces mobiles.

Puisque cet événement ne nécessite qu'un doigt, il peut être simulé dans Studio en utilisant l'émulateur et une souris.

Paramètres

swipeDirection: Enum.SwipeDirection

A Enum.SwipeDirection indiquant la direction du geste de balayage (Haut, Bas, Gauche ou Droite).

numberOfTouches: number

Le nombre de points de contact impliqués dans la gestuelle (généralement 1).


Échantillons de code

This code sample will cause a Frame (or other GuiObject) to bounce when a swipe gesture is performed on a touch-enabled device (or Studio's emulator). Horizontal swipes will change the hue of the GuiObject.BackgroundColor3, while vertical swipes will change the saturation.

Bouncing Color Picker

local frame = script.Parent
frame.Active = true
-- How far the frame should bounce on a successful swipe
local BOUNCE_DISTANCE = 50
-- Current state of the frame
local basePosition = frame.Position
local hue = 0
local saturation = 128
local function updateColor()
frame.BackgroundColor3 = Color3.fromHSV(hue / 256, saturation / 256, 1)
end
local function onTouchSwipe(swipeDir, _touchCount)
-- Change the BackgroundColor3 based on the swipe direction
local deltaPos
if swipeDir == Enum.SwipeDirection.Right then
deltaPos = UDim2.new(0, BOUNCE_DISTANCE, 0, 0)
hue = (hue + 16) % 255
elseif swipeDir == Enum.SwipeDirection.Left then
deltaPos = UDim2.new(0, -BOUNCE_DISTANCE, 0, 0)
hue = (hue - 16) % 255
elseif swipeDir == Enum.SwipeDirection.Up then
deltaPos = UDim2.new(0, 0, 0, -BOUNCE_DISTANCE)
saturation = (saturation + 16) % 255
elseif swipeDir == Enum.SwipeDirection.Down then
deltaPos = UDim2.new(0, 0, 0, BOUNCE_DISTANCE)
saturation = (saturation - 16) % 255
else
deltaPos = UDim2.new()
end
-- Update the color and bounce the frame a little
updateColor()
frame.Position = basePosition + deltaPos
frame:TweenPosition(basePosition, Enum.EasingDirection.Out, Enum.EasingStyle.Bounce, 0.7, true)
end
frame.TouchSwipe:Connect(onTouchSwipe)
updateColor()

TouchTap

Cet événement se déclenche lorsque le joueur effectue une gestuelle de tap sur l'élément de l'interface utilisateur en utilisant un appareil tactile activé.Un tap est une touche rapide sans aucun mouvement impliqué (une pression plus longue déclencherait GuiObject.TouchLongPress , et se déplacer pendant le toucher déclencherait GuiObject.TouchPan et/ou GuiObject.TouchSwipe ).Il tire avec une table de Vector2 objets qui décrivent les positions relatives des doigts impliqués dans le geste.

Puisque cet événement ne nécessite qu'un doigt, il peut être simulé dans Studio en utilisant l'émulateur et une souris.

Paramètres

touchPositions: Array

Un ensemble de Vector2 qui décrivent les positions relatives des doigts impliqués dans le geste.


Échantillons de code

This code sample will toggle the GuiObject.BackgroundTransparency of a UI element, like a Frame, when it is tapped on a touch-enabled device.

Tap Transparency Toggle

local frame = script.Parent
frame.Active = true
local function onTouchTap()
-- Toggle background transparency
if frame.BackgroundTransparency > 0 then
frame.BackgroundTransparency = 0
else
frame.BackgroundTransparency = 0.75
end
end
frame.TouchTap:Connect(onTouchTap)