HierarchicalChartControlBase.Legend Property
Gets or sets a treemap/sunburst legend.
Namespace: DevExpress.XtraTreeMap
Assembly: DevExpress.XtraTreeMap.v24.2.UI.dll
NuGet Package: DevExpress.Win.TreeMap
#Declaration
[XtraSerializableProperty(XtraSerializationVisibility.Hidden)]
public LegendBase Legend { get; set; }
#Property Value
Type | Description |
---|---|
Legend |
An object of a class derived from Legend |
#Remarks
A legend contains descriptions of colors used to paint treemap/sunburst items. Each legend item includes the treemap item’s group name (if the group does not have nested groups) or the sunburst item’s root group name with the corresponding color marker.
Initialize the Legend property with the LegendBase class descendant to add a legend to a treemap/sunburst. You can also use the predefined legend type (ColorListLegend) to initialize the Legend property.
#Example: How to Add a Legend to a Treemap
This example adds a legend to a treemap and configures its title, border, and text settings.
Create a ColorListLegend object.
Use the LegendBase.Title property to access the legend title settings. Specify the following title options:
Configure the options below to customize the position and alignment of the legend and legend items:
The following properties allow you to customize the legend border’s color and width:
Use the treemap’s
Legend
property to assign the legend to the treemap.
using DevExpress.XtraTreeMap;
using System;
using System.Drawing;
using System.Windows.Forms;
//...
private void Form1_Load(object sender, EventArgs e) {
//...
// Create a legend.
ColorListLegend legend = new ColorListLegend();
// Specify the legend title, and the title's color and font.
legend.Title.Text = "Field of Activity";
legend.Title.TextColor = Color.Black;
legend.Title.DXFont = new DXFont("Tahoma", 10);
// Define the color for legend items.
legend.TextColor = Color.Black;
// Set the offset beween an item's marker and text.
legend.TextOffset = 16;
// Specify the legend alignment and position.
legend.Direction = LegendDirection.LeftToRight;
legend.HorizontalAlignment = LegendHorizontalAlignment.Center;
legend.VerticalAlignment = LegendVerticalAlignment.BottomOutside;
// Define whether to arrange items in left-aligned columns.
legend.EquallySpacedItems = true;
// Configure the border color and width.
legend.BorderColor = Color.LightGray;
legend.BorderWidth = 1;
// Assign the legend to the treemap.
treeMapControl1.Legend = legend;
}
#Colorizer Specificity
A legend item’s marker appearance and text depends on the colorizer type that you use to color treemap/sunburst items.
The legend shows value ranges if a TreeMapRangeColorizer is applied to the treemap chart:
If you use a TreeMapGroupGradientColorizer or SunburstGradientColorizer, the legend displays a gradient marker for legend items:
The legend is not displayed in the following cases:
- You use a TreeMapGradientColorizer to paint a treemap.
- A treemap’s TreeMapPaletteColorizer.ColorizeGroups property is set to false.
- A sunburst’s SunburstPaletteColorizer.VaryColorInGroup property is set to true.
- A sunburst’s SunburstGradientColorizer.Mode property is set to ByItemIndex.
#Format Text in Legend
If you want to format legend item text, you should apply a colorizer to a treemap/sunburst and configure the colorizer’s TreeMapPaletteColorizerBase.LegendItemPattern (SunburstPaletteColorizerBase.LegendItemPattern) property.