DrawGUI.Scope

Abstract base class for IDisposable layout scopes in the Paragon Editor. Scopes wrap Unity's Begin/End IMGUI patterns into using blocks with support for chaining multiple scopes via Push(). Concrete implementations (HorizontalLayout, VerticalLayout, Box, Colorize, etc.) live in the Scopes/ subsystem.

Definition

Namespace: Paragon.Editor Assembly: Paragon.Editor.dll

public static partial class DrawGUI
{
    public abstract class Scope : IDisposable
}

Implements: IDisposable

Remarks

Unity's IMGUI requires explicit Begin/End call pairs (e.g., BeginHorizontal/EndHorizontal). Forgetting an End call causes layout errors. DrawGUI.Scope solves this by wrapping these pairs into IDisposable objects that can be used with using blocks, guaranteeing End is called even if exceptions occur.

Scope Lifecycle

1. Constructor — Concrete scope is created, calls Begin() which calls OnBegin()

2. Content — GUI code runs inside the using block

3. Dispose — When the using block exits, Dispose() is called:

   • First, all pushed (nested) scopes are disposed in LIFO order

   • Then End() calls OnEnd() on the outer scope

Scope Chaining

The Push() method enables composing multiple scopes in a single using block. Each pushed scope is stored on an internal stack and disposed before the parent scope when the using block exits:

// Instead of nested using blocks:
using (DrawGUI.VerticalLayout())
{
    using (DrawGUI.HorizontalLayout())
    {
        // content
    }
}

// Use chaining:
using (DrawGUI.VerticalLayout().HorizontalLayout())
{
    // content — HorizontalLayout is pushed onto VerticalLayout's stack
}

Extension methods on Scope (defined in the Scopes/ subsystem files) provide fluent chaining syntax like .HorizontalLayout(), .Colorize(), etc.

Quick Lookup

Goal	How
Use a scope	using (DrawGUI.HorizontalLayout()) { ... }
Chain scopes	using (DrawGUI.VerticalLayout().HorizontalLayout()) { ... }
Push a scope manually	scope.Push(new MyScope())
Create a custom scope	Subclass Scope, override OnBegin() and OnEnd()

Fields

Field	Type	Access	Description
stack	Stack<Scope>	private	Lazily-initialized stack of pushed child scopes

Methods

Push

Pushes a child scope onto this scope's internal stack. The child will be disposed before this scope when the using block exits. Returns this for fluent chaining.

public Scope Push(Scope scope)

Parameter	Type	Description
scope	Scope	The child scope to push

Returns: this — enables fluent chaining.

Begin (protected)

Calls OnBegin(). Invoked by concrete scope constructors.

protected void Begin()

OnBegin (abstract)

Override to implement the Begin call (e.g., EditorGUILayout.BeginHorizontal).

protected abstract void OnBegin()

OnEnd (abstract)

Override to implement the End call (e.g., EditorGUILayout.EndHorizontal).

protected abstract void OnEnd()

Dispose (explicit IDisposable)

Unwinds all pushed scopes (LIFO order), then calls End() on this scope.

void IDisposable.Dispose()

Algorithm:

1. While the stack has scopes, pop and dispose each one

2. Null out the stack

3. Call End() → OnEnd()

Extension Points

Creating a Custom Scope

Subclass Scope and override OnBegin() / OnEnd(). Call Begin() in the constructor:

public static partial class DrawGUI
{
    // Factory method
    public static Scope MyCustomScope(Color color)
    {
        return new MyCustomScopeImpl(color);
    }

    // Extension method for chaining
    public static Scope MyCustomScope(this Scope scope, Color color)
    {
        return scope.Push(new MyCustomScopeImpl(color));
    }

    private class MyCustomScopeImpl : Scope
    {
        private readonly Color previousColor;
        private readonly Color color;

        public MyCustomScopeImpl(Color color)
        {
            this.color = color;
            previousColor = GUI.color;
            Begin();
        }

        protected override void OnBegin()
        {
            GUI.color = color;
        }

        protected override void OnEnd()
        {
            GUI.color = previousColor;
        }
    }
}

Implementation Requirements

When subclassing Scope, you MUST:

1. Override OnBegin() — called when the scope starts

2. Override OnEnd() — called when the scope is disposed (cleanup/restore)

3. Call Begin() in the constructor — this triggers OnBegin()

You SHOULD:

• Provide a static factory method on DrawGUI for creation (e.g., DrawGUI.MyScope())

• Provide an extension method on Scope for chaining (e.g., scope.MyScope())

• Store and restore any modified GUI state in OnBegin/OnEnd

You MUST NOT:

• Override Dispose() — it is explicitly implemented and handles the push stack

• Call End() directly — it is private; use Dispose() (via using)

Common Pitfalls

Always use using blocks Scopes implement IDisposable and must be disposed to call OnEnd(). Failing to use a using block (or manually calling Dispose()) will leave IMGUI Begin/End calls unbalanced, causing layout errors.

Push order is LIFO When multiple scopes are pushed via Push(), they are disposed in reverse order (last pushed = first disposed). This mirrors the nesting order of using blocks: the innermost scope ends first.

Chaining extension methods require partial class Extension methods like .HorizontalLayout() on Scope are defined in the Scopes/ subsystem files as partial class members of DrawGUI. If you create a custom scope with a chaining method, it must also be a partial class extension.

Examples

Basic Layout Scope

using Paragon.Editor;
using static Paragon.Editor.DrawGUI;

// Horizontal layout
using (HorizontalLayout())
{
    Label("Left");
    FlexibleSpace();
    Label("Right");
}

Chained Scopes

using static Paragon.Editor.DrawGUI;

// Vertical > Horizontal > Colorize — all in one using
using (VerticalLayout(Style.Box).HorizontalLayout().Colorize(Color.yellow))
{
    Label("Yellow text in a horizontal row inside a box");
}

Nested Scopes

using static Paragon.Editor.DrawGUI;

using (VerticalLayout())
{
    Title("Header");

    using (HorizontalLayout())
    {
        Label("Column A");
        VerticalLine();
        Label("Column B");
    }

    HorizontalLine();

    using (HorizontalLayout())
    {
        FlexibleSpace();
        Button("OK", Style.Button, GUILayout.Width(80));
        Button("Cancel", Style.Button, GUILayout.Width(80));
    }
}

See Also

• DrawGUI — core drawing methods

• DrawGUI.Style — style presets used with scopes

• DrawGUI.Icon — icon caching

• DrawGUI Overview — system overview with full scope listing