WPF › Skinning › BinarySkinSerializer

BinarySkinSerializer

class.NET 6 / 8 / 10.NET Framework 4.8Binarymission.WPF.Skinning

Reads and writes skins as JSON files, so that a skin can be shipped with an application, chosen by a user or edited by hand.

public static class BinarySkinSerializer

Remarks

The file

A skin file names a built-in skin to start from and lists only what differs:

{
  "format": "binarymission-skin/1",
  "name": "Harbour",
  "basedOn": "Black",
  "colors": {
    "accent": "#2BA3A3",
    "surface": "#1C2A30"
  }
}

basedOn is one of the BinarySkinTheme names, White when left out. The colours are named as BinarySkinColor is, starting with a lower-case letter, and written #RRGGBB or #AARRGGBB. isDark, prefersSystemBackdrop and cornerRadius may also be given; format may be left out. Comments (// and /* */) are allowed.

What is filled in

An accent left out is the one chosen in Windows when the file is read. The selected tab's colours, when not given, are made from the accent to read on the canvas, and isDark, when not given and the surface is, follows the surface.

Mistakes

Anything that is not part of a skin – an unknown name, a colour written wrongly, a corner radius out of range – is reported as a BinarySkinFormatException naming the line and column, never passed over. ToJson writes every value, so a file it writes reads back as a skin that looks the same.

Examples

// Offer every skin in the Skins folder; tell the user about any file that cannot be used.
foreach (string path in Directory.GetFiles("Skins", "*.json"))
{
    try
    {
        skinPicker.Items.Add(BinarySkinSerializer.Load(path));
    }
    catch (BinarySkinFormatException ex)
    {
        problems.AppendLine(Path.GetFileName(path) + ": " + ex.Message);
    }
}

Members at a glance

Methods
`FromJson`	Reads a skin from JSON text.
`Load`	Reads a skin from a file of UTF-8 text.
`Load`	Reads a skin from a stream of UTF-8 text – an embedded resource, say.
`Save`	Writes a skin to a file, as UTF-8 text without a byte order mark.
`ToJson`	Writes a skin as JSON text.
Fields
`Format`	The format a skin file declares, `binarymission-skin/1`, and the only one this version reads.

Methods

FromJson static

public static BinarySkin FromJson(string json)

Reads a skin from JSON text.

Parameters

json: The text, in the form described on BinarySkinSerializer.

Returns

A new skin.

Exceptions

ArgumentNullException: json is null.
BinarySkinFormatException: The text does not describe a skin; the message names the line and column.

Load static

public static BinarySkin Load(string path)

Reads a skin from a file of UTF-8 text.

Parameters

path: The file.

Returns

A new skin.

Exceptions

ArgumentNullException: path is null.
BinarySkinFormatException: The file does not describe a skin; the message names the line and column.
System.IO.IOException: The file cannot be read – it does not exist, say.

Load static

public static BinarySkin Load(Stream stream)

Reads a skin from a stream of UTF-8 text – an embedded resource, say.

Parameters

stream: The stream, read to its end and left open.

Returns

A new skin.

Exceptions

ArgumentNullException: stream is null.
BinarySkinFormatException: The text does not describe a skin.

Example

using (Stream stream = typeof(App).Assembly.GetManifestResourceStream("Retail.Skins.Harbour.json"))
{
    BinarySkinManager.Apply(BinarySkinSerializer.Load(stream));
}

Save static

public static void Save(BinarySkin skin, string path)

Writes a skin to a file, as UTF-8 text without a byte order mark.

Parameters

skin: The skin.
path: The file, replaced if it exists.

Exceptions

ArgumentNullException: skin or path is null.

ToJson static

public static string ToJson(BinarySkin skin)

Writes a skin as JSON text.

Parameters

skin: The skin.

Returns

The text: every value the skin has, one to a line, every colour included.

Exceptions

ArgumentNullException: skin is null.

Fields

Format

public const string Format

The format a skin file declares, binarymission-skin/1, and the only one this version reads.