rojo/.cursor/rules/roblox/reference/engine/classes/GuiButton.yaml

# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: GuiButton
type: class
memory_category: Gui
summary: |
  An abstract class for interactive 2D user interface elements.
description: |
  `Class.GuiButton` is an abstract class that inherits from `Class.GuiObject`.
  It is the base class for the interactive, clickable `Class.ImageButton` and
  `Class.TextButton` objects. This class also defines several properties for
  interactive behavior, namely `Class.GuiButton.AutoButtonColor|AutoButtonColor`
  and `Class.GuiButton.Modal|Modal`.

  The most important event of a `Class.GuiButton` is
  `Class.GuiButton.Activated|Activated`, a **multi-platform event** that fires
  when the button is activated. When using a mouse, this means clicking the
  button and releasing with the cursor still over the UI object. For touch, the
  same applies but with a touch instead of button press. Finally, for gamepads,
  `Class.GuiButton.Activated|Activated` fires if a `Class.GuiButton` is selected
  when the **A** button is pressed and released. In short, this event is very
  useful for multi-platform user interface programming as it provides a nice
  general interface for a single user input.
code_samples: []
inherits:
  - GuiObject
descendants:
  - ImageButton
  - TextButton
tags:
  - NotCreatable
  - NotBrowsable
deprecation_message: ''
properties:
  - name: GuiButton.AutoButtonColor
    summary: |
      Determines whether the button automatically changes color when the mouse
      hovers over or clicks on it.
    description: |
      This property determines whether the button automatically changes color
      when the user's `Class.Mouse` hovers over or clicks on it. If `true`, the
      button will automatically change color when the mouse hovers over or
      clicks on it. If `false`, the button will not change.

      If you would like to customize how a button changes when the user's mouse
      hovers over or clicks on it, consider using an `Class.ImageButton` and
      changing the element's `Class.ImageButton.HoverImage|HoverImage` and
      `Class.ImageButton.PressedImage|PressedImage`.

      Please note that this property will not have an effect on an
      `Class.ImageButton` if its `Class.ImageButton.Image|Image` property is set
      to an image. Additionally, this property will not affect an
      `Class.ImageButton` on mouse hover when its
      `Class.ImageButton.HoverImage|HoverImage` is not `nil`, nor on mouse click
      if its `Class.ImageButton.PressedImage|PressedImage` is not `nil`.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: GuiButton.HoverHapticEffect
    summary: |
      A `Class.HapticEffect` instance that will play when the `Class.GuiButton`
      is being hovered.
    description: |
      A `Class.HapticEffect` instance that will play when the `Class.GuiButton`
      is being hovered.
    code_samples: []
    type: HapticEffect
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Haptic
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: GuiButton.Modal
    summary: |
      If `true` while the GUI element is visible, the mouse will not be locked
      unless the right mouse button is down.
    description: |
      If `true` while the GUI element is visible, the mouse will not be locked
      unless the right mouse button is down.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: GuiButton.PressHapticEffect
    summary: |
      A `Class.HapticEffect` instance that will play when the `Class.GuiButton`
      is being pressed.
    description: |
      A `Class.HapticEffect` instance that will play when the `Class.GuiButton`
      is being pressed.
    code_samples: []
    type: HapticEffect
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Haptic
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: GuiButton.Selected
    summary: |
      A boolean property which indicates whether the object has been selected.
    description: |
      A boolean property which indicates whether the object has been selected.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Selection
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: GuiButton.Style
    summary: |
      Sets the style of the `Class.GuiButton` based on a list of pre-determined
      styles.
    description: |
      Sets the style of the `Class.GuiButton` based on a list of pre-determined
      styles.
    code_samples: []
    type: ButtonStyle
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
methods: []
events:
  - name: GuiButton.Activated
    summary: |
      Fires when the button is activated.
    description: |
      Fires when the button is activated. As this event doesn't fire on the
      server, it should only be used in a `Class.LocalScript`, or in a
      `Class.Script` with `Class.Script.RunContext|RunContext` of
      `Enum.RunContext.Client`.
    code_samples: []
    parameters:
      - name: inputObject
        type: InputObject
        default:
        summary: ''
      - name: clickCount
        type: int
        default:
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - UI
  - name: GuiButton.MouseButton1Click
    summary: |
      Fires when the user's mouse fully left clicks the `Class.GuiButton`.
    description: |
      This event fires when the user's mouse fully left clicks the
      `Class.GuiButton`.

      In regards to clicking, the mouse must be in bounds of the
      `Class.GuiButton` and the mouse button must be pressed down and up again
      before this event fires. If the mouse leaves the bounds of the
      `Class.GuiButton` and is released, the event will not fire. If you would
      like to avoid this limitation, you can use
      `Class.GuiButton.MouseButton1Down|MouseButton1Down` and
      `Class.GuiButton.MouseButton1Up|MouseButton1Up`; these events are similar
      but will fire whenever the user presses their left mouse button down or
      up, respectively.
    code_samples: []
    parameters: []
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - UI
  - name: GuiButton.MouseButton1Down
    summary: |
      Fires when the user presses their left mouse button down on the
      `Class.GuiButton`.
    description: |
      This event fires when the user presses their left mouse button down on the
      `Class.GuiButton`.

      For an event requiring the user to press **and** release their left mouse
      on a `Class.GuiButton` in order for the event to fire, consider using
      `Class.GuiButton.MouseButton1Click|MouseButton1Click`.
    code_samples: []
    parameters:
      - name: x
        type: int
        default:
        summary: |
          The mouse's **X** screen coordinate in pixels.
      - name: 'y'
        type: int
        default:
        summary: |
          The mouse's **Y** screen coordinate in pixels.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - UI
  - name: GuiButton.MouseButton1Up
    summary: |
      Fires when the user releases their left mouse button off of the
      `Class.GuiButton`.
    description: |
      This event fires when the user releases their left mouse button off of the
      `Class.GuiButton`.

      For an event requiring the user to press **and** release their left mouse
      on a `Class.GuiButton` in order for the event to fire, consider using
      `Class.GuiButton.MouseButton1Click|MouseButton1Click`.
    code_samples: []
    parameters:
      - name: x
        type: int
        default:
        summary: |
          The mouse's **X** screen coordinate in pixels.
      - name: 'y'
        type: int
        default:
        summary: |
          The mouse's **Y** screen coordinate in pixels.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - UI
  - name: GuiButton.MouseButton2Click
    summary: |
      Fires when the user's mouse fully right clicks the `Class.GuiButton`.
    description: |
      This event fires when the user's mouse fully right clicks the
      `Class.GuiButton`.

      In regards to clicking, the mouse must be in bounds of the
      `Class.GuiButton` and the mouse button must be pressed down and up again
      before this event fires. If the mouse leaves the bounds of the
      `Class.GuiButton` and is released, the event will not fire. If you would
      like to avoid this limitation, you can use
      `Class.GuiButton.MouseButton2Down|MouseButton2Down` and
      `Class.GuiButton.MouseButton2Up|MouseButton2Up`; these events are similar
      but will fire whenever the user presses their right mouse button down or
      up, respectively.
    code_samples: []
    parameters: []
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - UI
  - name: GuiButton.MouseButton2Down
    summary: |
      Fires when the user presses their right mouse button down on the
      `Class.GuiButton`.
    description: |
      This event fires when the user presses their right mouse button down on
      the `Class.GuiButton`.

      For an event requiring the user to press **and** release their right mouse
      on a `Class.GuiButton` in order for the event to fire, consider using
      `Class.GuiButton.MouseButton2Click|MouseButton2Click`.
    code_samples: []
    parameters:
      - name: x
        type: int
        default:
        summary: |
          The mouse's **X** screen coordinate in pixels.
      - name: 'y'
        type: int
        default:
        summary: |
          The mouse's **Y** screen coordinate in pixels.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - UI
  - name: GuiButton.MouseButton2Up
    summary: |
      Fires when the user releases their right mouse button off of the
      `Class.GuiButton`.
    description: |
      This event fires when the user releases their right mouse button off of
      the `Class.GuiButton`.

      For an event requiring the user to press **and** release their right mouse
      on a `Class.GuiButton` in order for the event to fire, consider using
      `Class.GuiButton.MouseButton2Click|MouseButton2Click`.
    code_samples: []
    parameters:
      - name: x
        type: int
        default:
        summary: |
          The mouse's **X** screen coordinate in pixels.
      - name: 'y'
        type: int
        default:
        summary: |
          The mouse's **Y** screen coordinate in pixels.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - UI
  - name: GuiButton.SecondaryActivated
    summary: ''
    description: ''
    code_samples: []
    parameters:
      - name: inputObject
        type: InputObject
        default:
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - UI
callbacks: []