Provide Data

Jan 15, 2024
7 minutes to read

This topic explains how to populate a sunburst with data. The Sunburst control allows you to generate items based on data-source fields and to create items manually.

This document consists of the following sections:

Overview
Provide Flat Data
Provide Hierarchical Data
Create Sunburst Items Manually

Overview

Use adapters that implement the ISunburstDataAdapter interface to load and render data within the Sunburst control. The Sunburst control provides three built-in adapters: the Flat Data Adapter and Hierarchical Data Adapter allow you to connect to data sources and generate items based on data-source fields; the Item Storage adapter stores sunburst items you created.

The SunburstControl.DataAdapter property allows you to assign an adapter to the sunburst.

The Sunburst control allows you to develop a custom provider. Create the class that inherits the ISunburstDataAdapter interface, and implement its ISunburstDataAdapter.Items property.

Provide Flat Data

The Sunburst control uses the SunburstFlatDataAdapter class to operate with flat data. You can specify the data members that store item value and label data. Add data member names to the GroupDataMembers collection to define how to group items.

The following sunburst uses the Flat Data Adapter to process data.

The code below configures a SunburstFlatDataAdapter object and assigns it to the sunburst.

C#
VB.NET

csharp

private void OnLoad(object sender, EventArgs e) {
    SunburstFlatDataAdapter dataAdapter = new SunburstFlatDataAdapter();            
    dataAdapter.ValueDataMember = "Annual";
    dataAdapter.LabelDataMember = "Product";
    dataAdapter.GroupDataMembers.AddRange(new string[] { "Category", "Country" });
    dataAdapter.DataSource = CreateProductInfos();
    sunburstControl.DataAdapter = dataAdapter;
}

Class SurroundingClass
    Private Sub OnLoad(ByVal sender As Object, ByVal e As EventArgs)
        Dim dataAdapter As SunburstFlatDataAdapter = New SunburstFlatDataAdapter()
        dataAdapter.ValueDataMember = "Annual"
        dataAdapter.LabelDataMember = "Product"
        dataAdapter.GroupDataMembers.AddRange(New String() {"Category", "Country"})
        dataAdapter.DataSource = CreateProductInfos()
        sunburstControl.DataAdapter = dataAdapter
    End Sub
End Class

The following table lists members used by the code above.

Member	Description
SunburstControl.DataAdapter	Gets or sets the data adapter used to populate the sunburst with data.
SunburstFlatDataAdapter	The data adapter that provides flat data to a sunburst.
SunburstFlatDataAdapter.ValueDataMember	Specifies the data member that provides item values.
SunburstFlatDataAdapter.LabelDataMember	Defines the data member that provides item label text.
SunburstFlatDataAdapter.GroupDataMembers	Returns the collection of data members that specifies how to aggregate items.

Provide Hierarchical Data

The Sunburst control uses the SunburstHierarchicalDataAdapter to operate with hierarchical data. You should populate the Mappings collection with data mappings to specify how the Sunburst should convert data objects to sunburst items. A data mapping allows you to define the data members that store data for item values, and label text and child items.

The following sunburst uses the Hierachical Data Adapter to operate with data.

The following code configures a SunburstHierarchicalDataAdapter object and assigns it to the sunburst.

C#
VB.NET

csharp

private void OnFormLoad(object sender, EventArgs e) {
    SunburstHierarchicalDataAdapter dataAdapter = new SunburstHierarchicalDataAdapter();
    dataAdapter.Mappings.Add(new SunburstHierarchicalDataMapping {
        Type = typeof(CountryInfo), 
        LabelDataMember = "CountryName",  
        ChildrenDataMember = "CityInfos"
    });
    dataAdapter.Mappings.Add(new SunburstHierarchicalDataMapping {
        Type = typeof(CityInfo),  
        LabelDataMember = "CityName",              
        ChildrenDataMember = "SaleInfos"
    });
    dataAdapter.Mappings.Add(new SunburstHierarchicalDataMapping {
        Type = typeof(ProductInfo),
        ValueDataMember = "Total",
        LabelDataMember = "Category",
    });
    dataAdapter.DataSource = CreateInfos();
    sunburstControl.DataAdapter = dataAdapter;
}

Private Sub OnFormLoad(ByVal sender As Object, ByVal e As EventArgs)
    Dim dataAdapter As SunburstHierarchicalDataAdapter = New SunburstHierarchicalDataAdapter()
    dataAdapter.Mappings.Add(New SunburstHierarchicalDataMapping With {
        .Type = GetType(CountryInfo),
        .LabelDataMember = "CountryName",
        .ChildrenDataMember = "CityInfos"
    })
    dataAdapter.Mappings.Add(New SunburstHierarchicalDataMapping With {
        .Type = GetType(CityInfo),
        .LabelDataMember = "CityName",
        .ChildrenDataMember = "SaleInfos"
    })
    dataAdapter.Mappings.Add(New SunburstHierarchicalDataMapping With {
        .Type = GetType(ProductInfo),
        .ValueDataMember = "Total",
        .LabelDataMember = "Category"
    })
    dataAdapter.DataSource = CreateInfos()
    sunburstControl.DataAdapter = dataAdapter
End Sub

The code above uses the following API members.

Member	Description
SunburstControl.DataAdapter	Gets or sets the data adapter used to populate the sunburst with data.
SunburstHierarchicalDataAdapter	The data adapter that provides hierarchical data to the sunburst.
SunburstHierarchicalDataAdapter.Mappings	Returns the collection of data object mappings to sunburst items.
HierarchicalDataMapping.ValueDataMember	Defines the data member that provides item values.
HierarchicalDataMapping.ChildrenDataMember	Gets or sets the name of the data field whose values are used to specify child items of current level sunburst items.
HierarchicalDataMapping.LabelDataMember	Specifies the data member that provides item label text.
HierarchicalDataMapping.Type	Gets or sets the data object type on the current nested level.

Create Sunburst Items Manually

The Sunburst control uses SunburstItemStorage to operate with manually created items. Add new items to the Items collection. You can specify each item’s value, label, and child items.

The following sunburst uses a SunburstItemStorage to store items.

The code below configures a SunburstItemStorage object and assigns it to the sunburst.

C#
VB.NET

csharp

private void OnFormLoad(object sender, EventArgs e) {
    SunburstItemStorage itemStorage = new SunburstItemStorage();
    SunburstItem usaItem = new SunburstItem();
    usaItem.Label = "USA";
    usaItem.Children.AddRange(new List<SunburstItem> {
        new SunburstItem { Label = "Nuclear", Value = 187.9 },
        new SunburstItem { Label = "Oil", Value = 937.6 },
        new SunburstItem { Label = "Natural Gas", Value = 582 },
        new SunburstItem { Label = "Hydro Electric", Value = 59.8 },
        new SunburstItem { Label = "Coal", Value = 564.3 },
    });
    SunburstItem chinaItem = new SunburstItem();
    chinaItem.Label = "China";
    chinaItem.Children.AddRange(new List<SunburstItem> {
        new SunburstItem { Label = "Nuclear", Value = 11.3 },
        new SunburstItem { Label = "Oil", Value = 308.6 },
        new SunburstItem { Label = "Natural Gas", Value = 35.1 },
        new SunburstItem { Label = "Hydro Electric", Value = 74.2 },
        new SunburstItem { Label = "Coal", Value = 956.9 },
    });
    SunburstItem russiaItem = new SunburstItem();
    russiaItem.Label = "Russia";
    russiaItem.Children.AddRange(new List<SunburstItem> {
        new SunburstItem { Label = "Nuclear", Value = 32.4 },
        new SunburstItem { Label = "Oil", Value = 128.5 },
        new SunburstItem { Label = "Natural Gas", Value = 361.8 },
        new SunburstItem { Label = "Hydro Electric", Value = 40 },
        new SunburstItem { Label = "Coal", Value = 105.9 },
    });
    itemStorage.Items.AddRange(new List<SunburstItem> { usaItem, chinaItem, russiaItem });
    sunburstControl.DataAdapter = itemStorage;
    sunburstControl.CenterLabel.TextPattern = "{TV}";
    sunburstControl.StartAngle = 60;
}

Private Sub OnFormLoad(ByVal sender As Object, ByVal e As EventArgs)
    Dim itemStorage As SunburstItemStorage = New SunburstItemStorage()
    Dim usaItem As SunburstItem = New SunburstItem()
    usaItem.Label = "USA"
    usaItem.Children.AddRange(New List(Of SunburstItem) From {
        New SunburstItem With { .Label = "Nuclear", .Value = 187.9 },
        New SunburstItem With { .Label = "Oil", .Value = 937.6 },
        New SunburstItem With { .Label = "Natural Gas", .Value = 582 },
        New SunburstItem With { .Label = "Hydro Electric", .Value = 59.8 },
        New SunburstItem With { .Label = "Coal", .Value = 564.3 }
    })
    Dim chinaItem As SunburstItem = New SunburstItem()
    chinaItem.Label = "China"
    chinaItem.Children.AddRange(New List(Of SunburstItem) From {
        New SunburstItem With { .Label = "Nuclear", .Value = 11.3 },
        New SunburstItem With { .Label = "Oil", .Value = 308.6 },
        New SunburstItem With { .Label = "Natural Gas", .Value = 35.1 },
        New SunburstItem With { .Label = "Hydro Electric", .Value = 74.2 },
        New SunburstItem With { .Label = "Coal", .Value = 956.9 }
    })
    Dim russiaItem As SunburstItem = New SunburstItem()
    russiaItem.Label = "Russia"
    russiaItem.Children.AddRange(New List(Of SunburstItem) From {
        New SunburstItem With { .Label = "Nuclear", .Value = 32.4 },
        New SunburstItem With { .Label = "Oil", .Value = 128.5 },
        New SunburstItem With { .Label = "Natural Gas", .Value = 361.8 },
        New SunburstItem With { .Label = "Hydro Electric", .Value = 40 },
        New SunburstItem With { .Label = "Coal", .Value = 105.9 }
    })
    itemStorage.Items.AddRange(New List(Of SunburstItem) From {
        usaItem,
        chinaItem,
        russiaItem
    })
    sunburstControl.DataAdapter = itemStorage
    sunburstControl.CenterLabel.TextPattern = "{TV}"
    sunburstControl.StartAngle = 60
End Sub

The following table lists members used in the code above.

Member	Description
SunburstControl.DataAdapter	Gets or sets the data adapter used to populate the sunburst with data.
SunburstItemStorage	The data adapter that stores the item collection and provides it to a sunburst.
SunburstItemStorage.Items	Returns the sunburst item collection.
SunburstItem	A sunburst item.
SunburstItem.Children	The sunburst item’s child elements.
SunburstItem.Value	Gets or sets the sunburst item’s value.
SunburstItem.Label	Gets or sets the sunburst item’s label.