BlackBeard.Spyglass 1.1.2

BlackBeard.Spyglass

A guided-tour ("coach marks") overlay for WPF applications. Wrap your window's content in one control, tag the controls you want to point at, register a tour, and ask a service to run it — fully MVVM, no code-behind required in your app.

Install

dotnet add package BlackBeard.Spyglass

Register (Prism)

protected override void RegisterTypes(IContainerRegistry containerRegistry)
{
    containerRegistry.RegisterSpyglass();
}

Not using Prism? Just read/write SpyglassLocator.Current instead — it lazily creates a default TourService the first time it's touched.

Wrap your window

<Window ...
        xmlns:sg="http://schemas.blackbeard.dev/spyglass">
    <sg:TourOverlay ScrimBrush="#B2101010" SpotlightPadding="10" SpotlightCornerRadius="8">
        <ContentControl prism:RegionManager.RegionName="MainRegion" />
    </sg:TourOverlay>
</Window>

Tag a control

<Button Content="Save" sg:Spyglass.TargetId="save-button" />

Define a tour

var tour = new TourDefinition
{
    Key = "main-tour",
    Name = "Welcome",
    Introduction = "Here's a quick look around.",
    ShowEveryTime = true,
};

tour.Steps.Add(new TourStep
{
    TargetId = "save-button",
    Title = "Save your work",
    Description = "Click here any time to save.",
});

tour.Steps.Add(new TourStep
{
    TargetId = "settings-button",
    Description = "Your preferences live here.",
});

tourService.Register(tour);

Run it

// On view activation - honours the persisted "show every time" setting.
await _tours.RequestAsync("main-tour");

// From a "Help > Take the tour" menu item - always runs.
await _tours.StartAsync("main-tour", showPrompt: true);

TourOverlay reference

Where preferences are stored

The default JsonFileTourStateStore writes to:

%LOCALAPPDATA%\{CompanyName}\{ProductName}\spyglass.tours.json

CompanyName/ProductName come from your entry assembly's AssemblyCompanyAttribute / AssemblyProductAttribute. Pass SpyglassOptions.StorageFilePath to RegisterSpyglass(...) to override the location, or SpyglassOptions.StateStore to supply your own ITourStateStore (e.g. one backed by Properties.Settings). Writes are atomic and never throw; if persistence fails for any reason, Spyglass logs a warning and keeps working in memory for that session.

License

Apache-2.0 - see LICENSE.