rojo/.cursor/rules/roblox/reference/engine/classes/ScreenGui.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: ScreenGui
type: class
memory_category: Instances
summary: |
  Primary container of on-screen 2D user interface elements.
description: |
  `Class.ScreenGui` is a storage container for 2D `Class.GuiObject|GuiObjects`
  displayed on the user's screen. A `Class.ScreenGui` only shows if parented to
  a player's `Class.PlayerGui`; parenting a `Class.ScreenGui` to
  `Class.StarterGui` ensures it clones into each player's `Class.PlayerGui` when
  they join the experience and their character first spawns. See
  [On‑Screen UI Containers](../../../ui/on-screen-containers.md) for further
  details.

  <img src="../../../assets/ui/ui-objects/ScreenGui-Example.jpg" width="840" alt="Example ScreenGui with various GuiObject children, including a Frame, TextLabel, TextBox, and ImageButton." />

  For performance improvements, the appearance of a `Class.ScreenGui` is cached
  until one of the following events occurs:

  - A descendant is added to or removed from it.
  - A property of a descendant changes.
  - A property of the `Class.ScreenGui` itself changes.

  If any of these events occur, the `Class.ScreenGui` appearance is recomputed
  on the next frame it gets rendered.
code_samples: []
inherits:
  - LayerCollector
descendants:
  - GuiMain
tags: []
deprecation_message: ''
properties:
  - name: ScreenGui.ClipToDeviceSafeArea
    summary: |
      Whether to clip the contents of this `Class.ScreenGui` to the device's
      safe area.
    description: |
      If this property is `true`, all `Class.GuiObject` descendants of the
      `Class.ScreenGui` will be clipped to the device's safe area (see
      `Enum.ScreenInsets`). The default is `true` to maintain backwards
      compatibility of UI that is intentionally hidden offscreen, such as
      objects that slide into view from a screen edge when they're needed.

      <img
      src="../../../assets/engine-api/classes/ScreenGui/ClipToDeviceSafeArea-True.png"
      width="840" alt="Mobile device showing UI button clipped by device safe
      area" />

      If this property is `false`, `Class.GuiObject` descendants will **not** be
      clipped to the device's safe area and may be obscured by the camera notch
      or other screen cutouts.

      <img
      src="../../../assets/engine-api/classes/ScreenGui/ClipToDeviceSafeArea-False.png"
      width="840" alt="Mobile device showing UI button overflowing device safe
      area, obscured by screen camera notch" />

      Note that this property will be ignored if you set
      `Class.ScreenGui.ScreenInsets|ScreenInsets` to `Enum.ScreenInsets|None`,
      as doing so implies that you intentionally want to disregard the device's
      safe insets.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: ScreenGui.DisplayOrder
    summary: |
      Controls the Z-index order in which multiple `Class.ScreenGui` containers
      are drawn.
    description: |
      This property controls the Z-index order in which multiple
      `Class.ScreenGui` containers are drawn. Those with a higher
      `Class.ScreenGui.DisplayOrder|DisplayOrder` will be drawn on top of those
      with a lower value.
    code_samples: []
    type: int
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: ScreenGui.IgnoreGuiInset
    summary: |
      Determines whether the `Class.ScreenGui` overflows into the range of
      Roblox's core UI elements.
    description: |
      If this property is `false` (default),
      `Class.ScreenGui.ScreenInsets|ScreenInsets` is set to
      `Enum.ScreenInsets|CoreUISafeInsets`, effectively keeping its bounds below
      the Roblox top bar core UI.

      If this property is changed to `true` and
      `Class.ScreenGui.ScreenInsets|ScreenInsets` is currently set to
      `Enum.ScreenInsets|CoreUISafeInsets`,
      `Class.ScreenGui.ScreenInsets|ScreenInsets` will be set to
      `Enum.ScreenInsets|DeviceSafeInsets`.

      See `Class.ScreenGui.ScreenInsets|ScreenInsets` for details on how screen
      insets affect the contents of a `Class.ScreenGui`.
    code_samples: []
    type: boolean
    tags:
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: false
    capabilities:
      - UI
  - name: ScreenGui.SafeAreaCompatibility
    summary: |
      Specifies whether automatic UI compatibility transformations are applied
      to descendant "fullscreen" `Class.GuiObject|GuiObjects` on displays with
      screen cutouts.
    description: |
      This property specifies whether automatic UI compatibility transformations
      are applied to descendant "fullscreen" `Class.GuiObject|GuiObjects` of the
      `Class.ScreenGui` on displays with screen cutouts. Eligibility occurs if
      the total area of the descendant `Class.GuiObject` (including any applied
      border or `Class.UIStroke`) covers the device's safe area both
      horizontally and vertically. See the `Enum.SafeAreaCompatibility` enum
      reference for details.

      The default value is `Enum.SafeAreaCompatibility|FullscreenExtension` in
      order to automatically improve the appearance of UI that was authored for
      screens without any cutouts. However, it's recommended that you avoid
      fullscreen extensions for new work; instead, use the
      `Class.ScreenGui.ScreenInsets|ScreenInsets` property to specify which
      insets should be respected for different `Class.ScreenGui` containers.

      Note that descendant UI objects will continue to be clipped by the
      device's safe area if
      `Class.ScreenGui.ClipToDeviceSafeArea|ClipToDeviceSafeArea` is set to
      `true`.
    code_samples: []
    type: SafeAreaCompatibility
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: ScreenGui.ScreenInsets
    summary: |
      Controls the safe area insets that are applied to the contents of the
      `Class.ScreenGui`.
    description: |
      This property controls the safe area insets that are applied to the
      contents of the `Class.ScreenGui`.

      The default of `Enum.ScreenInsets|CoreUISafeInsets` keeps all descendant
      `Class.GuiObject|GuiObjects` inside the core UI safe area, clear of the
      Roblox top bar buttons and other screen cutouts like the device's camera
      notch.

      <img src="../../../assets/engine-api/enums/ScreenInsets/CoreUISafeInsets.png" width="840" alt="Mobile device showing UI buttons inside core UI safe area" />

      If you set this property to `Enum.ScreenInsets|None`, UI objects may be
      obscured behind core UI objects or device cutouts like the camera notch.
      As a result, you should only use `Enum.ScreenInsets|None` for a
      `Class.ScreenGui` that contains noninteractive content like background
      images.

      See
      [On-Screen UI Containers](../../../ui/on-screen-containers.md#screen-insets)
      for alternative examples.
    code_samples: []
    type: ScreenInsets
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
methods: []
events: []
callbacks: []