Skip to content

charts and graphs

vijay@envivo edited this page Oct 20, 2026 · 2 revisions

Charts

Charts display numeric data visually. Declare a property of type IChartData, then populate it with a ChartData instance containing one or more data series.

Type Description
ChartData The chart itself. Sets the ChartType and holds the Series.
ChartData.DataSeries A named set of points, with an optional HexColour.
ChartData.DataPoint A single value. The members used depend on the chart type (see below).

In code, a chart is declared and populated like so:

public IChartData SalesChart { get; internal set; } //👈

...

SalesChart = new ChartData
{
    Id = Guid.NewGuid(),
    ChartType = "Line",
    Series =
    [
        new ChartData.DataSeries
        {
            Id = Guid.NewGuid(),
            SeriesName = "2025",
            HexColour = "#487de7",
            Points =
            [
                new ChartData.DataPoint { Id = Guid.NewGuid(), XValue = 1, YValue = 120 },
                new ChartData.DataPoint { Id = Guid.NewGuid(), XValue = 2, YValue = 95 },
            ]
        }
    ]
};

Chart types

The ChartType value determines which DataPoint members are used:

ChartType DataPoint members Notes
Line XValue, YValue Supports multiple series.
Column XValue, YValue Supports multiple series.
Bar XValue, YValue Supports multiple series.
Bubble XValue, YValue, Size, PointName, HexColour Size sets the bubble size. Keep point counts low for readability.
Gauge Size Size is a fraction (0–1), not a percentage. One point per series. Multiple series are drawn as multiple gauges, side by side.
Treemap PointName, Size Typically a single series. Size sets each tile's area.

For Line, Column and Bar, XValue is the point's position along the category axis, and YValue is its value. Points from different series that share an XValue occupy the same slot. So to show one bar per series (for example, one named bar per category), give each series its own XValue (1, 2, 3, ...):

Series = categories
    .Select((category, index) => new ChartData.DataSeries
    {
        Id = Guid.NewGuid(),
        SeriesName = category.Name,
        Points = [new ChartData.DataPoint { Id = Guid.NewGuid(), XValue = index + 1, YValue = category.Value }], //👈 own slot
    })
    .ToArray()

Displaying charts in the UI

Inline charts

By default a chart property is shown collapsed. Use InlineExpanded to render the chart directly on the object:

[UI(UiRenderOption.InlineExpanded)] //👈
public IChartData LineChart { get; internal set; }

Charts need space, so consider enlarging the object's explorer:

[UiExplorer(preferredSize: UiExplorerSize.Maximised)] //👈
public class AdjustableChartDemo

Collections of charts

To show several charts together, wrap each chart in a small class and expose a collection of them:

[Visible(isVisibleInLibrary: false)]
public class EmbeddedChart
{
    public Guid Id { get; init; }

    public string ChartType => Chart?.ChartType;

    [UI(renderOption: UiRenderOption.InlineExpanded)]
    public IChartData Chart { get; internal set; }

    public override string ToString() => ChartType;
}
[AllowedOperations(canAdd: false, canModify: false)]
[Collection(
    canExpandRows: true, //👈 each row expands to show its chart
    visibleColumnNames: [nameof(EmbeddedChart.ChartType)])]
public ICollection<EmbeddedChart> Charts { get; internal set; }

Charts on persisted objects

ChartData can't be stored: an Aggregate that holds a populated ChartData in a settable property fails to load from its repository. On a persisted object, store the figures the chart shows instead, and draw the chart from them when it is shown. Mark the IChartData read-only property with [IgnoreDataMember] (from System.Runtime.Serialization) so it is left out of the stored copy, and cached in a private field that is cleared whenever the figures change:

private IChartData? _SalesChart;

[IgnoreDataMember] //👈 not stored; drawn from MonthlySales
[UI(renderOption: UiRenderOption.InlineExpanded)]
public IChartData SalesChart => _SalesChart ??= DrawSalesChart();

public ICollection<MonthlySales> MonthlySales { get; init; } = new List<MonthlySales>();

internal void UpdateFigures(...)
{
    // ... change MonthlySales ...
    _SalesChart = null; //👈 redrawn when next shown
}

Updating charts

Charts are replaced rather than modified: assign a new ChartData to the property. Link the updating method to the property using relatedPropertyName:

[Method(relatedPropertyName: nameof(LineChart))] //👈
public void UpdateChart()
{
    LineChart = new ChartData { ... };
}

To make a chart react to user input, rebuild it from the input property's setter:

[UI(preferredControl: UiControlType.Range)]
[Range(1, 365)]
public int Max_X_Value
{
    get => _Max_X_Value;
    set
    {
        _Max_X_Value = value;
        UpdateChart(); //👈
    }
}

💡 Developer Tips

  • Chart properties are normally set in code, so use internal set to prevent editing from the UI.
  • ChartType is a string. Use the values exactly as listed above.
  • Rebuilding a large chart on every setter call (e.g. while dragging a slider) can be slow. Keep point counts reasonable.

Clone this wiki locally