Class ScyllaUIScreenMargin
Safe-area aware screen-margin component. Combines UnityEngine.Screen.safeArea (toggled per edge) with a designer-tunable per-edge margin, then applies the resulting inset to its own RectTransform as anchored stretch values.
Inherited Members
Namespace: Scylla.Core.Util.UI
Assembly: ScyllaCore.dll
Syntax
[AddComponentMenu("Scylla/UI/Layout/Screen Margin")]
[DisallowMultipleComponent]
[RequireComponent(typeof(RectTransform))]
[ExecuteAlways]
public sealed class ScyllaUIScreenMargin : MonoBehaviourRemarks
Add as a direct child of the canvas root (or directly under a ScyllaUILayoutRoot) and parent all interactive UI inside it. Background art that should bleed to the physical screen edges behind notches should remain outside this RectTransform.
The component re-applies on enable, on Inspector change, and whenever the
parent's RectTransform dimensions change. A ScyllaUILayoutRoot
ancestor (when present) watches Screen.safeArea, resolution, and
orientation and propagates changes to this component automatically.
Safe-area per-edge toggles (SafeAreaTop, SafeAreaRight, SafeAreaBottom, SafeAreaLeft) allow keeping the OS-reported safe area on some edges while ignoring it on others. For example, a game with a fixed landscape orientation might apply safe area only on the left and right edges to handle notches, while leaving the top and bottom edges flush with the canvas.
The designer margin (DesignerMargin) is applied on top of the safe-area inset, adding additional padding on each edge. Percent values in the designer margin resolve against the parent canvas dimensions.
Use OverrideSafeArea to simulate arbitrary device notch configurations in demos or automated tests without relying on OS-reported values.
Properties
DesignerMargin
Additional per-edge inset added on top of the safe-area anchors. Percent values
resolve against the parent canvas dimensions. Maps to offsetMin and
offsetMax on the RectTransform. Changing this property triggers an
immediate Apply() call.
Declaration
public ScyllaUIEdgeInsets DesignerMargin { get; set; }Property Value
| Type | Description |
|---|---|
| ScyllaUIEdgeInsets |
OverrideSafeArea
Optional override for Screen.safeArea. When set, Apply()
uses this rect instead of the OS-reported Screen.safeArea. Intended for
demos and tests that need to simulate device notches or cutouts
deterministically, without relying on a physical device or Unity's Device
Simulator. Set to null to revert to the real Screen.safeArea.
Declaration
public Rect? OverrideSafeArea { get; set; }Property Value
| Type | Description |
|---|---|
| Rect? |
RectTransform
Lazily resolved reference to this component's RectTransform. Cached on
first access to avoid repeated GetComponent calls during Apply().
Declaration
public RectTransform RectTransform { get; }Property Value
| Type | Description |
|---|---|
| RectTransform |
SafeAreaBottom
Controls whether the Screen.safeArea bottom-edge inset is converted to
an anchor offset on the bottom edge. When false, the bottom anchor
reaches the physical bottom of the screen regardless of any home indicator or
gesture bar.
Declaration
public bool SafeAreaBottom { get; set; }Property Value
| Type | Description |
|---|---|
| bool |
SafeAreaLeft
Controls whether the Screen.safeArea left-edge inset is converted to an
anchor offset on the left edge. When false, the left anchor reaches
the physical left of the screen regardless of any cutout.
Declaration
public bool SafeAreaLeft { get; set; }Property Value
| Type | Description |
|---|---|
| bool |
SafeAreaRight
Controls whether the Screen.safeArea right-edge inset is converted to an
anchor offset on the right edge. When false, the right anchor reaches
the physical right of the screen regardless of any cutout.
Declaration
public bool SafeAreaRight { get; set; }Property Value
| Type | Description |
|---|---|
| bool |
SafeAreaTop
Controls whether the Screen.safeArea top-edge inset is converted to an
anchor offset on the top edge. When false, the top anchor reaches the
physical top of the screen regardless of any notch or status bar.
Declaration
public bool SafeAreaTop { get; set; }Property Value
| Type | Description |
|---|---|
| bool |
Methods
Apply()
Recomputes and applies the combined safe-area and designer-margin inset to this
component's RectTransform, writing the anchorMin, anchorMax,
offsetMin, and offsetMax properties.
Declaration
public void Apply()Remarks
The safe area is sourced from OverrideSafeArea when set, or
from Screen.safeArea otherwise. In batch mode or during early
initialization when the Screen subsystem reports zero dimensions, the method
falls back to a full-screen rect to avoid division-by-zero.
Each safe-area edge toggle is applied as a normalized anchor: enabled edges
pull the corresponding anchor inward by the safe-area amount. Disabled edges
leave the anchor at 0 or 1 (flush with the screen boundary).
The DesignerMargin is then applied as offsetMin and
offsetMax on the RectTransform; percent values resolve against the
parent RectTransform's rect dimensions, or against the screen
dimensions when no parent rect is available.
This method registers all driven properties with the internal
DrivenRectTransformTracker so Unity shows the "driven by" badge in
the Inspector. Call Apply() directly whenever the safe area
changes outside the component's normal lifecycle (for example, after an
orientation change that the owning ScyllaUILayoutRoot has
already detected).