Ph0rd.ColorSampler 1.0.1

<h1 align="center">Ph0rd.ColorSampler</h1>

<p align="center"> <a style="text-decoration:none" href="https://www.nuget.org/packages/Ph0rd.ColorSampler"> <img src="https://img.shields.io/nuget/v/Ph0rd.ColorSampler" alt="NuGet version" /></a> <a style="text-decoration:none" href="https://github.com/ph0rd/ColorSampler/actions/workflows/build.yml"> <img src="https://github.com/ph0rd/ColorSampler/actions/workflows/build.yml/badge.svg?branch=master" alt="Build status" /></a> </p>

Ph0rd.ColorSampler is a performant Windows desktop eyedropper for .NET Windows apps (WinForms, WPF, WinUI 3, and custom HWND/Win32 hosts). It shows a click-through crosshair, a zoomed pixel preview, and raises one sampler event as the sampled color changes, is confirmed, or is cancelled.

The sampler UI is implemented with native Win32 APIs, not WinForms, WPF, or WinUI. Use it from any of those app frameworks without pulling in a dependency on another UI framework.

It is the color sampling component used by Instant Syntax Styler, the Visual Studio 2026 extension for changing syntax colors and styles directly in the editor window.

<table align="center"> <tr> <th>Package icon</th> <th>Live sampling preview</th> </tr> <tr> <td align="center"> <img src="https://raw.githubusercontent.com/ph0rd/ColorSampler/master/assets/package-icon.png" alt="Ph0rd.ColorSampler package icon" /> </td> <td align="center"> <img src="https://raw.githubusercontent.com/ph0rd/ColorSampler/master/assets/capture-1.png" alt="ColorSampler crosshair and zoomed pixel preview over code" /> </td> </tr> </table>

Install

dotnet add package Ph0rd.ColorSampler

No third-party packages are required. The library has no WinForms, WPF, or WinUI dependency; it uses native Win32 windows, GDI screen capture, DWM synchronization, and the Windows Magnification API.

Quick Start

using Ph0rd.ColorSampler;
using System;
using System.Drawing;

Sampler? sampler = new Sampler();

sampler.SamplerEvent += (_, e) =>
{
    var hex = ToHex(e.Color);

    switch (e.Kind)
    {
        case SamplerEventKind.ColorChanged:
            // This event is not raised on your UI thread.
            // Marshal before touching UI controls, for example:
            // WinUI 3:  textBlock.DispatcherQueue.TryEnqueue(() => textBlock.Text = hex);
            // WPF:      textBlock.Dispatcher.BeginInvoke(() => textBlock.Text = hex);
            // WinForms: label.BeginInvoke(() => label.Text = hex);
            Console.WriteLine(hex);
            break;

        case SamplerEventKind.Confirmed:
            Console.WriteLine($"Confirmed {hex}");
            sampler.Dispose();
            break;

        case SamplerEventKind.Cancelled:
            Console.WriteLine("Cancelled");
            sampler.Dispose();
            break;
    }
};

sampler.Start();

static string ToHex(Color c) => $"#{c.R:X2}{c.G:X2}{c.B:X2}";

User Controls

• Move the mouse to move the virtual crosshair.
• Scroll the mouse wheel to zoom in or out.
• Left-click to confirm the color.
• Right-click or press Escape to cancel.

Threading Contract

SamplerEvent fires on the sampler's dedicated render thread. UI apps must marshal back to their own UI thread:

• WPF: Dispatcher.BeginInvoke(...)
• WinForms: BeginInvoke(...)
• WinUI 3: DispatcherQueue.TryEnqueue(...)

Only one sampler session can run at a time. Calling Start() while another Sampler is active throws InvalidOperationException.

Platform Requirements

This package is Windows-only. It uses a low-level mouse hook, GDI screen capture, DWM synchronization, layered windows, and the Windows Magnification API. Sampler events report colors as System.Drawing.Color.

The sampler overlay is a native Win32 window. It is framework-neutral: WinForms, WPF, WinUI 3, and custom HWND/Win32 hosts can all use it without adopting another Windows UI framework.

During an active sampling session, the package temporarily hides the cursor, then restores it when sampling stops, the sampler is disposed, or the host process exits.

Supported app targets:

• .NET Framework 4.8 Windows desktop apps
• .NET 8 or newer Windows desktop apps, including .NET 9 and .NET 10

The NuGet package includes net48 and net8.0-windows builds of the library.

The sampler expects access to the interactive Windows desktop. Security tools, RDP sessions, UAC prompts, or other secure-desktop transitions may block or interrupt sampling.

Samples

The repository includes three small samples:

dotnet run --project samples/ColorSampler.WpfSample/ColorSampler.WpfSample.csproj
dotnet run --project samples/ColorSampler.WinFormsSample/ColorSampler.WinFormsSample.csproj
dotnet run --project samples/ColorSampler.WinUISample/ColorSampler.WinUISample.csproj

Each sample shows the same pattern: create a Sampler, subscribe to SamplerEvent, switch on SamplerEventKind, marshal back to the UI thread, and dispose the sampler when finished.

Build

dotnet restore ColorSampler.slnx
dotnet build ColorSampler.slnx -c Release --no-restore

Links

• Project: github.com/ph0rd/ColorSampler
• Instant Syntax Styler: VS Marketplace
• Instant Syntax Styler: ph0rd.com/instant-syntax-styler
• Instant Syntax Styler public repo: github.com/ph0rd/Instant-Syntax-Styler

License

MIT for the source code.

The Ph0rd name, Ph0rd.ColorSampler name, package icon, logos, and other branding assets are reserved and are not licensed for use as your own product branding.