# Quickstart Copy-Paste Guide

This guide contains the shortest public consumer path for Nexamas UI. It is intentionally based on the public `MASApplication` / `MASApplicationWindow` facade and does not use internal host, proof, or Showcase APIs.

Naming note: use `Nexamas.UI.*` namespaces and `MAS*` public types together. `MASApplication`, `MASApplicationWindow`, `MASButton`, `MASDataGrid`, and `MASSize` are stable Nexamas UI API names.

## 1. Create a WinForms project

Use a .NET Framework 4.8 Windows Forms project.

Install the package from the current local package output:

```powershell
Install-Package Nexamas.UI -Version 1.0.0-rc.1 -Source .\.artifacts\nuget
```

For an official release, use the published package version instead.

## 2. Attach Nexamas UI to one form

Use `MASApplication.AttachWindow(...)` when one form owns one MAS window and you want Nexamas UI to manage the application lifetime automatically.

```vb
Option Strict On
Option Explicit On

Imports System
Imports System.Windows.Forms
Imports Nexamas.UI.Application
Imports Nexamas.UI.Controls
Imports Nexamas.UI.Layout

Public NotInheritable Class MainForm
    Inherits Form

    Private ReadOnly _window As MASApplicationWindow

    Public Sub New()
        Text = "Nexamas UI Quickstart"
        Width = 1000
        Height = 700
        StartPosition = FormStartPosition.CenterScreen

        _window = MASApplication.AttachWindow(
            owner:=Me,
            configure:=Sub(window As MASApplicationWindow)
                           Dim title As MASTitle = window.Controls.AddTitle("Nexamas UI")
                           Dim message As MASLabel = window.Controls.AddLabel("Hello from the public MASApplication facade.")
                           Dim action As MASButton = window.Controls.AddButton("Click")

                           AddHandler action.Click,
                               Sub(sender As Object, e As EventArgs)
                                   window.Services.Toasts.Success("The MAS window is alive.", "Quickstart")
                               End Sub

                           window.Controls.LayoutPage(
                               Sub(page As MASApplicationLayoutPageBuilder)
                                   page.Padding(MASLayoutSpacing.Spacious)
                                   page.Spacing(MASLayoutSpacing.Medium)
                                   page.FullWidth(title, MASSize.FillWidth)
                                   page.FullWidth(message, MASSize.FillWidth)
                                   page.ActionGroup(
                                       Sub(actions As MASApplicationActionGroupLayoutBuilder)
                                           actions.AlignCenter().EqualItemWidth().Add(action, MASSize.Default)
                                       End Sub)
                               End Sub)
                       End Sub)
    End Sub
End Class
```

## 3. Add the WinForms entry point

```vb
Friend Module Program
    <STAThread>
    Public Sub Main()
        Global.System.Windows.Forms.Application.EnableVisualStyles()
        Global.System.Windows.Forms.Application.SetCompatibleTextRenderingDefault(False)
        Global.System.Windows.Forms.Application.Run(New MainForm())
    End Sub
End Module
```

## 4. Explicit lifetime pattern

Use explicit lifetime when one `MASApplication` should manage more than one `MASApplicationWindow`.

```vb
Imports System.Windows.Forms
Imports Nexamas.UI.Application

Public NotInheritable Class MainForm
    Inherits Form

    Private ReadOnly _application As MASApplication
    Private ReadOnly _window As MASApplicationWindow

    Public Sub New()
        _application = MASApplication.Create()
        _window = _application.CreateWindow(owner:=Me)
    End Sub

    Protected Overrides Sub OnFormClosed(e As FormClosedEventArgs)
        If _window IsNot Nothing Then _window.Dispose()
        If _application IsNot Nothing Then _application.Dispose()
        MyBase.OnFormClosed(e)
    End Sub
End Class
```

## 5. Add controls through the window facade

```vb
Dim title As MASTitle = _window.Controls.AddTitle("Nexamas UI")
Dim label As MASLabel = _window.Controls.AddLabel("Ready")
Dim button As MASButton = _window.Controls.AddButton("Save")
```

## 6. Layout the page through MAS layout builders

```vb
_window.Controls.LayoutPage(
    Sub(page As MASApplicationLayoutPageBuilder)
        page.Padding(MASLayoutSpacing.Spacious)
        page.Spacing(MASLayoutSpacing.Medium)
        page.FullWidth(title, MASSize.FillWidth)
        page.FullWidth(label, MASSize.FillWidth)
        page.ActionGroup(
            Sub(actions As MASApplicationActionGroupLayoutBuilder)
                actions.AlignCenter().EqualItemWidth().Add(button, MASSize.Default)
            End Sub)
    End Sub)
```

## 7. Check Output capabilities before showing export actions

```vb
Imports Nexamas.UI.Output

If _application.Output.CanExport(MASOutputArtifactKind.VisualCapture, MASOutputFormat.Png) Then
    Dim result As MASOutputResult = _application.Output.ExportVisualCapturePng(
        MASOutputTarget.File("C:\Temp\NexamasVisualCapture.png"),
        MASOutputOptions.ForVisualCapture("showcase-real-buttons-light-1x"))
End If
```

## 8. Attach proof pages only through official public gateways

```vb
Dim proofPage As IDisposable = MASRenderVerification.AttachDashboard(_window)
Dim rtlPage As IDisposable = MASLocalizationRtl.AttachPage(_window)
```

## More examples

- [Application window quickstart](../examples/application-window-quickstart.md)
- [Basic controls](../examples/controls-basic-example.md)
- [LayoutPage](../examples/layout-page-example.md)
- [Application surface](../examples/application-surface-example.md)
- [Theme and surfaces](../examples/theme-surface-example.md)
- [DataGrid](../examples/datagrid-example.md)
- [Output](../examples/output-example.md)
- [Render Verification](../examples/render-verification-example.md)
- [Localization / RTL](../examples/localization-rtl-page-example.md)
- [Product controls](../examples/product-controls/README.md)