ViewportControl

A WinForms viewport implementing editor-grade infinite canvas navigation (cursor-centric zoom & pan).

Designed for editors and tools — provides camera navigation so you only implement rendering.

✨ What Problem It Solves

WinForms has no built-in concept of an editor viewport. Typical implementations suffer from:

• Zoom drifting away from the cursor
• Inconsistent panning at different zoom levels
• Manual coordinate math everywhere
• Rendering tightly coupled with transforms

ViewportControl provides a ready-made navigation model:

• Cursor-anchored zoom
• Smooth panning
• Infinite world space
• Stable world ↔ screen transform

Focus on drawing, not camera math.

🎬 Demo Preview

⚡ Quick Example

Create a zoomable world-space canvas and draw a rectangle in world coordinates:

var viewport = new Viewport { Dock = DockStyle.Fill };
this.Controls.Add(viewport);

viewport.Render += (s, e) =>
{
    e.Graphics.DrawRectangle(Pens.Red, -50, -50, 100, 100);
};

Handle input in world space:

private void viewport_MouseDown(object sender, MouseEventArgs e)
{
    var world = viewport.ScreenToWorld(e.Location);
    Console.WriteLine(world);
}

Zooming and panning are handled automatically.

🧠 Core Concepts

Concept	Meaning
World space	Infinite logical coordinates you draw in
Screen space	Actual pixels on the control
Viewport transform	Automatically handled camera transform
Render event	Draw in world coordinates

📦 Installation

Option 1 - GitHub Packages (development feed)

Requires a GitHub Personal Access Token.

Add source:

dotnet nuget add source https://nuget.pkg.github.com/kehan-zhou/index.json --name github --username YOUR_GITHUB_USERNAME --password YOUR_GITHUB_TOKEN --store-password-in-clear-text

Install:

dotnet add package ViewportControl

Option 2 - Build from source (simplest)

1. Clone the repository
2. Open ViewportControl.sln
3. Build Release configuration
4. Reference the generated DLL src/ViewportControl/bin/Release/ViewportControl.dll

No NuGet configuration required.

🧩 Typical Use Cases

• Level editors
• Node graph editors
• CAD-like tools
• Tile map editors
• 2D scene authoring tools

📄 License

This project is licensed under the MIT License.

You're free to use, modify, and distribute this control in personal and commercial projects.

See the LICENSE file for full details.

🤝 Contributing

PRs and issues welcome.

For major changes, please open an issue first.