mirror of
https://github.com/rojo-rbx/rojo.git
synced 2026-10-25 13:31:37 +00:00
108 lines
4.6 KiB
Markdown
108 lines
4.6 KiB
Markdown
---
|
||
title: Text & image buttons
|
||
description: Buttons allow users to prompt an action.
|
||
---
|
||
|
||
**Buttons** are `Class.GuiObject|GuiObjects` that allow users to perform an action. You can customize buttons to provide context and feedback, such as changing the visual appearance or [scripting](#script-buttons) audible feedback when a user clicks a button.
|
||
|
||
There are two types of buttons which you can place [on‑screen](../ui/on-screen-containers.md) or [in‑experience](../ui/in-experience-containers.md):
|
||
|
||
- A `Class.TextButton` is a rectangle with text that triggers the `Class.GuiButton.Activated|Activated` event on click/tap.
|
||
|
||
- An `Class.ImageButton` is a rectangle with an image that triggers the `Class.GuiButton.Activated|Activated` event on click/tap. It features additional states for swapping the image on user hover or press.
|
||
|
||
## Create buttons on the screen
|
||
|
||
Buttons on a screen are useful to quickly guide users to various menus or pages.
|
||
|
||
To add a button to the screen:
|
||
|
||
1. In the **Explorer** window, select **StarterGui** and add a **ScreenGui**.
|
||
|
||
1. Hover over **StarterGui** and click the ⊕ button. A contextual menu displays.
|
||
|
||
1. Insert a **ScreenGui**.
|
||
|
||
2. Select the new **ScreenGui** and add a button.
|
||
|
||
1. Hover over **ScreenGui** and click the ⊕ button. A contextual menu displays.
|
||
|
||
1. Insert either a **TextButton** or **ImageButton**.
|
||
|
||
<img src="../assets/ui/button-text-input/ImageButton-Screen-New.jpg" width="800" />
|
||
|
||
## Create buttons on part faces
|
||
|
||
Buttons on a part are useful for allowing users to interact with parts. For
|
||
example, you can let users step on a button to complete an action.
|
||
|
||
To add a button to the face of a part:
|
||
|
||
1. In the **Explorer** window, select the **part** and add a **SurfaceGui**.
|
||
|
||
1. Hover over the **part** and click the ⊕ button. A contextual menu displays.
|
||
|
||
1. Insert a **SurfaceGui**.
|
||
|
||
2. Select the new **SurfaceGui** and add any type of button or input.
|
||
|
||
1. Hover over **SurfaceGui** and click the ⊕ button. A contextual menu displays.
|
||
|
||
1. Insert either a **TextButton** or
|
||
**ImageButton**.
|
||
|
||
<img src="../assets/ui/button-text-input/ImageButton-SurfaceGui-New.jpg"
|
||
width="800" />
|
||
|
||
<Alert severity="warning">
|
||
If you don't see the button, try [choosing a different face](../parts/textures-decals.md#choose-a-face) in the <b>Face</b> property of the <b>SurfaceGui</b>.
|
||
</Alert>
|
||
|
||
## Change the appearance of an ImageButton
|
||
|
||
Changing the appearance of an `Class.ImageButton` when a user is interacting with it provides useful visual feedback. For example, when an `Class.ImageButton` changes visual appearance when a user hovers over it, it lets the user know that it isn't disabled and that they have the option to click it if they want to perform that `Class.ImageButton` action.
|
||
|
||
An `Class.ImageButton` has three properties to change its visual appearance:
|
||
|
||
- `Class.ImageButton.Image|Image` - The image that displays when a user is not interacting with the `Class.ImageButton`.
|
||
|
||
- `Class.ImageButton.HoverImage|HoverImage` - The image that displays when a user is hovering their cursor over the `Class.ImageButton`.
|
||
|
||
- `Class.ImageButton.PressedImage|PressedImage` - The image that displays when a user is clicking the `Class.ImageButton`.
|
||
|
||
<GridContainer numColumns="3">
|
||
<figure>
|
||
<img src="../assets/ui/button-text-input/ImageButton-State-Normal.png" />
|
||
<figcaption>Normal</figcaption>
|
||
</figure>
|
||
<figure>
|
||
<img src="../assets/ui/button-text-input/ImageButton-State-Hover.png" />
|
||
<figcaption>Hover</figcaption>
|
||
</figure>
|
||
<figure>
|
||
<img src="../assets/ui/button-text-input/ImageButton-State-Pressed.png" />
|
||
<figcaption>Pressed</figcaption>
|
||
</figure>
|
||
</GridContainer>
|
||
|
||
To change the appearance of an `Class.ImageButton` with user input:
|
||
|
||
1. Add an **ImageButton** to a [screen](#create-buttons-on-the-screen) or a [surface](#create-buttons-on-the-screen).
|
||
|
||
2. In the **Explorer** window, click the **ImageButton** object.
|
||
|
||
3. In the **Properties** window, assign three different respective asset IDs for the **Image**, **HoverImage**, and **PressedImage** properties.
|
||
|
||
## Script buttons
|
||
|
||
You can script an action when a user presses a button by connecting the button to a `Class.GuiButton.Activated` event. For example, when you parent the following `Class.LocalScript` to a button, the button changes to a random color every time a user clicks it.
|
||
|
||
```lua
|
||
local button = script.Parent
|
||
local RNG = Random.new()
|
||
local function onButtonActivated()
|
||
-- randomize the button color
|
||
button.BackgroundColor3 = Color3.fromHSV(RNG:NextNumber(), 1, 1)
|
||
end
|
||
button.Activated:Connect(onButtonActivated)
|
||
```
|