# Nexamas UI Nexamas UI is a premium SkiaSharp-based .NET Framework 4.8 UI SDK for modern Windows Forms desktop applications. Nexamas UI is the product and package identity. The public developer-facing API intentionally uses the `MAS` family prefix for controls and application surfaces such as `MASApplication`, `MASApplicationWindow`, `MASButton`, `MASLabel`, `MASDataGrid`, `MASApplicationTheme`, `IMASAppTheme`, and `MASSize`. These identifiers are stable Nexamas UI API names, part of the official Nexamas UI naming model. This repository is packaged for commercial delivery. It intentionally keeps only the product source, build/package assets, essential legal/package notices, the official quality runner, and minimal samples. ## What you can build with it Nexamas UI gives a WinForms application a MAS-owned application/window layer, SkiaSharp rendering, themed controls, page layout helpers, data presentation controls, localization/RTL foundations, motion infrastructure, output/export capabilities, and quality proof tooling. The recommended consumer path is simple: 1. Install the `Nexamas.UI` NuGet package. 2. Create a normal .NET Framework 4.8 WinForms app. 3. Attach a `MASApplicationWindow` to your form. 4. Add controls through `window.Controls`. 5. Layout the page through the official MAS layout builders. ## Requirements - Windows desktop application - .NET Framework 4.8 - Visual Studio / MSBuild capable of building classic WinForms projects - NuGet package restore enabled ## Install For a local package produced by this repository: ```powershell Install-Package Nexamas.UI -Version 1.0.0-rc.1 -Source .\.artifacts\nuget ``` This source snapshot is prepared for the first release candidate package: `1.0.0-rc.1`. Promote to `1.0.0` only after the release-candidate proof passes. ## Quick start: first Nexamas window Create a .NET Framework 4.8 WinForms application and replace the startup form code with this minimal pattern: ```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 Nexamas UI.") Dim action As MASButton = window.Controls.AddButton("Click me") 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 ``` Use the normal WinForms entry point: ```vb Friend Module Program 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 ``` ## Explicit application lifetime Use `MASApplication.AttachWindow(...)` for one-form applications. Use explicit lifetime when one application instance should own more than one MAS window: ```vb 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 ``` ## Core public concepts | Concept | Consumer entry point | |---|---| | Application lifetime | `MASApplication.Create()` or `MASApplication.AttachWindow(...)` | | Window facade | `MASApplicationWindow` | | Controls | `window.Controls.AddButton(...)`, `AddLabel(...)`, `AddDataGrid(...)`, and other typed factories | | Layout | `window.Controls.LayoutPage(...)`, `MASSize`, `MASLayoutSpacing` | | Theme and surfaces | `application.Theme`, `window.Theme`, public surface-material helpers | | DataGrid/DataView | `MASDataGrid`, `MASDataView`, data factories | | Localization / RTL | official localization/RTL public gateways documented under `docs/developer/` | | Output | `MASApplication.Output` capability catalog and supported export routes | | Quality proof | `tools/quality/Run-NexamasUIQuality.ps1` and source-contract gates | ## Brand and API identity Use this naming model consistently: ```text Nexamas UI Product / SDK name Nexamas.UI NuGet package, assembly, and namespace root MAS* Stable API/control family exposed by Nexamas UI ``` Correct consumer code uses `Nexamas.UI.*` namespaces with `MAS*` types: ```vb Imports Nexamas.UI.Application Imports Nexamas.UI.Controls Imports Nexamas.UI.Layout Dim app As MASApplication = MASApplication.Create() Dim window As MASApplicationWindow = app.CreateWindow(owner:=Me) Dim button As MASButton = window.Controls.AddButton("Save") ``` Do not reintroduce former platform-era product identity names. ## Documentation map Start here when evaluating or adopting the SDK: - `docs/index.md` — main documentation center. - `docs/customer-guide.md` — customer-facing explanation of what is included and what is not included. - `docs/company-adoption-guide.md` — safe company evaluation path. - `docs/commercial/pricing-and-evaluation.md` — seven-day evaluation and commercial offer boundary. - `docs/developer-guide.md` — developer entry point for public consumer APIs. - `docs/developer/quickstart-copy-paste.md` — shortest copy-paste examples. - `docs/examples/README.md` — example catalog. - `docs/quality-proof-guide.md` — quality proof wording and execution boundaries. - `release-docs/README.md` — curated commercial reading pack. ## Repository layout ```text Component/ Public controls and component internals MASSystem/ Nexamas UI domains: Application, Layout, Visual, Interaction, Data, Commands, Quality, Output, Localization, Extensibility buildTransitive/ NuGet build integration eng/ci/ Release, pack, and external consumer proof scripts eng/tests/ Source-contract, sample proof, and SDK runtime harness eng/benchmarks/ Startup probe and optional baseline performance capture samples/MinimalConsumerApp Minimal raw-code consumer sample docs/ Code-first documentation center release-docs/ Curated commercial documentation pack tools/quality/ Single official quality entry point tools/validation/ Windows validation pack runner NuGet.Config Product-local NuGet restore configuration Nexamas.UI.nuspec Binary package contract ``` ## Source build and package proof The main quality command is: ```powershell .\tools\quality\Run-NexamasUIQuality.ps1 -Configuration Release -Platform x64 ``` Direct package lane after a successful `Release|x64` build: ```powershell .\eng\ci\Pack-Nexamas.UI.ps1 -Configuration Release -Platform x64 .\eng\ci\Test-NexamasUIPackedConsumer.ps1 -Configuration Release -Platform x64 ``` The packed consumer proof must pass from the `.nupkg`, not from a project reference. Expected local package output for the current release-candidate line: ```text .artifacts\nuget\Nexamas.UI.1.0.0-rc.1.nupkg .artifacts\nuget\Nexamas.UI.1.0.0-rc.1.snupkg ``` Commercial release lane: ```text Release candidate: 1.0.0-rc.1 First stable release: 1.0.0 ``` ## Quality and release discipline A build is not releaseable only because it compiles. Before release, validate: - clean source-contract tests, - public API freeze gates, - approved V1 public surface gate, - package proof, - packed external consumer proof, - source-distribution cleanliness, - license and third-party notices. Useful commands: ```powershell .\eng\tests\Run-NexamasUITestSuite.ps1 -Configuration Release -Platform x64 .\eng\ci\Test-NexamasUIPackedConsumer.ps1 -Configuration Release -Platform x64 ``` ## Package contents The binary NuGet package is intentionally small and consumer-clean. It contains the product assembly, XML documentation, buildTransitive target, README, license, and third-party notices. The companion symbol package carries the PDB. The binary package does not ship `docs/`, `eng/`, `samples/`, `tools/`, local build output, historical audit reports, or machine-specific artifacts. ## Advanced notes ### Surface material routing Surface materials are owned by `MASSystem/Visual/Surface/Material`. Canonical material identities use `surface.material.*`; reusable material distributions use `surface.material-profile.*`; complex elements should request materials through generic surface slots such as Root, Header, Body, Footer, Toolbar, Viewport, Overlay, and SelectedItem. The material registry remains element-agnostic: no material id should contain component names such as button, grid, avatar, preview, date, time, menu, toast, tooltip, progressbar, or imageviewer. ### TileBox bitmap ownership `MASTileBox` keeps the existing safe default: bitmaps passed directly or returned by providers are borrowed and are not disposed by the control. When a consumer creates fresh bitmaps that are not owned by an external cache, use the explicit TileBox ownership overloads with `takeOwnership:=True` or an `Action(Of SKBitmap)` disposer. The renderer still reads prepared snapshots only; ownership is held by `MASTileItem` and released when owned item resources are cleared/replaced or when the tile item/control is disposed. ### Motion frame-clock lifecycle Nexamas UI Motion uses a host-scoped `MASMotionFrameClock` owned by each `MASSkiaFrameScheduler`, together with `MASMotionTimelineRunner`, instead of consumer-local timers or background loops. Controls resolve their owning clock through `MASControlRuntimeServices`; non-control runtime owners such as Float transitions receive the clock explicitly from the host runtime. Motion consumers that keep active runners or frame-clock registrations must unregister at their dispose lifecycle boundary. ## License, evaluation, and third-party notices Nexamas UI is proprietary commercial software distributed under the terms in `LICENSE.md`. The default evaluation path is a seven-day, non-production evaluation license. Commercial use, customer delivery, paid client work, and redistribution require a valid commercial license. Pricing and evaluation policy are documented in `docs/commercial/pricing-and-evaluation.md`. Third-party notices are listed in `THIRD_PARTY_NOTICES.md`.