Class RadTreeMapElement

Represents the core element of the RadTreeMap control that provides data visualization capabilities for hierarchical data through nested rectangles.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
VisualElement
RadComponentElement
RadItem
UIItemBase
LightVisualElement
RadTreeMapElement
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll

Syntax

public class RadTreeMapElement : LightVisualElement, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IComponent, IDisposable, IBindableComponent, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IPrimitiveElement, IShapedElement, IFillElement, IBorderElement, IBoxStyle, IBoxElement, IDrawFillElement, IImageElement, ITextPrimitive, ITextProvider, IDataItemSource
Remarks

RadTreeMapElement is the main element responsible for rendering hierarchical data as a treemap visualization. It supports data binding, grouping, customizable algorithms for rectangle calculation, and various colorization schemes. The element handles user interactions such as selection, hover effects, and tooltip display.

Constructors

RadTreeMapElement()

Initializes a new instance of the RadTreeMapElement class.

Declaration
public RadTreeMapElement()

Fields

GroupBackColorProperty

Identifies the GroupBackColor dependency property.

Declaration
public static RadProperty GroupBackColorProperty
Field Value
RadProperty

GroupBorderColorProperty

Identifies the GroupBorderColor dependency property.

Declaration
public static RadProperty GroupBorderColorProperty
Field Value
RadProperty

GroupHeaderHeightProperty

Identifies the GroupHeaderHeight dependency property.

Declaration
public static RadProperty GroupHeaderHeightProperty
Field Value
RadProperty

HoveredItemBackColorProperty

Identifies the HoveredItemBackColor dependency property.

Declaration
public static RadProperty HoveredItemBackColorProperty
Field Value
RadProperty

HoveredItemBorderColorProperty

Identifies the HoveredItemBorderColor dependency property.

Declaration
public static RadProperty HoveredItemBorderColorProperty
Field Value
RadProperty

HoveredItemBorderWidthProperty

Identifies the HoveredItemBorderWidth dependency property.

Declaration
public static RadProperty HoveredItemBorderWidthProperty
Field Value
RadProperty

SelectedItemBackColorProperty

Identifies the SelectedItemBackColor dependency property.

Declaration
public static RadProperty SelectedItemBackColorProperty
Field Value
RadProperty

SelectedItemBorderColorProperty

Identifies the SelectedItemBorderColor dependency property.

Declaration
public static RadProperty SelectedItemBorderColorProperty
Field Value
RadProperty

SelectedItemBorderWidthProperty

Identifies the SelectedItemBorderWidth dependency property.

Declaration
public static RadProperty SelectedItemBorderWidthProperty
Field Value
RadProperty

Properties

Algorithm

Gets or sets the algorithm used for calculating the layout and positioning of rectangles in the treemap.

Declaration
public TreeMapAlgorithm Algorithm { get; set; }
Property Value
TreeMapAlgorithm

Remarks

The algorithm determines how the available space is divided among the data items based on their values. If no algorithm is explicitly set, a default SquarifiedAlgorithm instance is created.

AllowHotTracking

Gets or sets a value indicating whether hot tracking (hover effects) is enabled for treemap items.

Declaration
public bool AllowHotTracking { get; set; }
Property Value
System.Boolean

Remarks

When hot tracking is disabled, the HoveredItem and HoveredGroup properties are set to null.

AllowSelection

Gets or sets a value indicating whether selection of treemap items is enabled.

Declaration
public bool AllowSelection { get; set; }
Property Value
System.Boolean

Remarks

When selection is disabled, the SelectedItem and SelectedGroup properties are set to null.

Colorizer

Gets or sets the colorizer used for applying colors to treemap items and groups.

Declaration
public BaseColorizer Colorizer { get; set; }
Property Value
BaseColorizer

Remarks

The colorizer determines the background and foreground colors for items and groups in the treemap. If no colorizer is explicitly set, a default PaletteColorizer instance is created.

DataSource

Gets or sets the data source for the treemap visualization.

Declaration
public object DataSource { get; set; }
Property Value
System.Object

Remarks

The DataSource can be any object that implements IList, IListSource, IBindingList, or IEnumerable. When set to null, both DisplayMember and ValueMember are reset to empty strings.

DataView

Gets the collection view that provides filtering, sorting, and grouping capabilities over the data source.

Declaration
public RadCollectionView<TreeMapDataItem> DataView { get; }
Property Value
RadCollectionView<TreeMapDataItem>

DisplayMember

Gets or sets the name of the property that provides display text for each data item in the treemap.

Declaration
public string DisplayMember { get; set; }
Property Value
System.String

Remarks

The DisplayMember property specifies which property of the bound data objects contains the text that will be displayed on each rectangle in the treemap visualization.

EnableGrouping

Gets or sets a value indicating whether grouping functionality is enabled for the treemap.

Declaration
public bool EnableGrouping { get; set; }
Property Value
System.Boolean

Remarks

When grouping is disabled, all items are displayed as individual rectangles without hierarchical organization. When enabled, items can be organized into groups based on the configured GroupDescriptors.

Font

Gets or sets the font used for rendering text in the treemap elements.

Declaration
[RadPropertyDefaultValue("Font", typeof(VisualElement))]
public override Font Font { get; set; }
Property Value
System.Drawing.Font

Overrides
Remarks

The font property defines the typeface, size, and style attributes for text displayed on treemap items and groups. This property is inheritable through the element tree and cached for performance optimization.

GroupBackColor

Gets or sets the background color for group headers and areas.

Declaration
public Color GroupBackColor { get; set; }
Property Value
System.Drawing.Color

Remarks

This color is used to fill the background of group rectangles in the treemap visualization. The value is cached for performance during rendering operations.

GroupBorderColor

Gets or sets the border color for group rectangles.

Declaration
public Color GroupBorderColor { get; set; }
Property Value
System.Drawing.Color

Remarks

This color is used to draw the borders around group rectangles in the treemap visualization. The value is cached for performance during rendering operations.

GroupDescriptors

Gets a collection of GroupDescriptor objects that define grouping rules for the treemap data items.

Declaration
public GroupDescriptorCollection GroupDescriptors { get; }
Property Value
GroupDescriptorCollection

Remarks

Group descriptors are used to organize data items into hierarchical groups, which are then visualized as nested rectangles in the treemap. Each group can contain child groups and individual items.

GroupHeaderHeight

Gets or sets the height of group headers in pixels.

Declaration
public int GroupHeaderHeight { get; set; }
Property Value
System.Int32

Remarks

This property determines the vertical space allocated for displaying group titles. The value is cached for performance during rendering operations.

Groups

Gets a collection of TreeMapDataItemGroup objects that represent groups in the treemap hierarchy.

Declaration
public TreeMapDataItemGroupCollection Groups { get; }
Property Value
TreeMapDataItemGroupCollection

Remarks

Groups are used to organize related data items and are visualized as larger rectangles containing nested rectangles for their child items or subgroups.

GroupTextAlignment

Gets or sets the text alignment for group headers.

Declaration
public ContentAlignment GroupTextAlignment { get; set; }
Property Value
System.Drawing.ContentAlignment

Remarks

This property determines how group titles are positioned within group header areas.

HasGroups

Gets a value indicating whether the treemap has groups and grouping is enabled.

Declaration
public bool HasGroups { get; }
Property Value
System.Boolean

Remarks

This property returns true only when both EnableGrouping is true and there are groups in the Groups collection.

HoveredGroup

Gets the currently hovered group, or null if no group is being hovered.

Declaration
public TreeMapDataItemGroup HoveredGroup { get; protected set; }
Property Value
TreeMapDataItemGroup

Remarks

This property is automatically updated when the mouse moves over treemap groups, provided that AllowHotTracking is enabled.

HoveredItem

Gets the currently hovered data item, or null if no item is being hovered.

Declaration
public TreeMapDataItem HoveredItem { get; protected set; }
Property Value
TreeMapDataItem

Remarks

This property is automatically updated when the mouse moves over treemap items, provided that AllowHotTracking is enabled.

HoveredItemBackColor

Gets or sets the background color for hovered items.

Declaration
public Color HoveredItemBackColor { get; set; }
Property Value
System.Drawing.Color

Remarks

When an item is hovered and this color is not empty, it overrides the item's default background color. The value is cached for performance during rendering operations.

HoveredItemBorderColor

Gets or sets the border color for hovered items.

Declaration
public Color HoveredItemBorderColor { get; set; }
Property Value
System.Drawing.Color

Remarks

This color is used to draw the border around items when they are being hovered by the mouse. The value is cached for performance during rendering operations.

HoveredItemBorderWidth

Gets or sets the border width in pixels for hovered items.

Declaration
public int HoveredItemBorderWidth { get; set; }
Property Value
System.Int32

Remarks

This value determines the thickness of the border drawn around items when they are being hovered. The value is cached for performance during rendering operations.

Items

Gets a collection of TreeMapDataItem objects that represent individual items in the treemap.

Declaration
public TreeMapDataItemCollection Items { get; }
Property Value
TreeMapDataItemCollection

Remarks

This collection contains all the data items that will be visualized as rectangles in the treemap. Each item has properties for value, text, style, and calculated bounds.

ItemTextAlignment

Gets or sets the text alignment for individual treemap items.

Declaration
public ContentAlignment ItemTextAlignment { get; set; }
Property Value
System.Drawing.ContentAlignment

Remarks

This property determines how text is positioned within each item's rectangle, such as top-left, center, bottom-right, etc.

LegendElement

Gets the legend element that displays color mappings and group information.

Declaration
public TreeMapLegendElement LegendElement { get; }
Property Value
TreeMapLegendElement

LegendOrientation

Gets or sets the orientation of the legend items (horizontal or vertical layout).

Declaration
public Orientation LegendOrientation { get; set; }
Property Value
System.Windows.Forms.Orientation

LegendPosition

Gets or sets the position of the legend relative to the treemap visualization area.

Declaration
public RadPosition LegendPosition { get; set; }
Property Value
RadPosition

Remarks

The legend can be positioned at the top, bottom, left, right, or hidden by setting to None.

LegendStack

Gets the stack layout element that contains the legend area.

Declaration
public StackLayoutElement LegendStack { get; }
Property Value
StackLayoutElement

LegendTitle

Gets or sets the title text displayed in the legend.

Declaration
public string LegendTitle { get; set; }
Property Value
System.String

ListSource

Gets the source object that manages data binding and collection operations.

Declaration
public TreeMapListSource ListSource { get; }
Property Value
TreeMapListSource

ScreenTip

This property is not relevant for this class.

Declaration
public override RadScreenTipElement ScreenTip { get; set; }
Property Value
RadScreenTipElement

Overrides

ScreenTipElement

Gets or sets the screen tip element used for displaying Office-style screen tips.

Declaration
public virtual RadOffice2007ScreenTipElement ScreenTipElement { get; set; }
Property Value
RadOffice2007ScreenTipElement

Remarks

If no screen tip element is explicitly set, a default RadOffice2007ScreenTipElement instance is created when first accessed.

SelectedGroup

Gets or sets the currently selected group in the treemap.

Declaration
public TreeMapDataItemGroup SelectedGroup { get; set; }
Property Value
TreeMapDataItemGroup

Remarks

Setting this property triggers the SelectedGroupChanging event, which can be cancelled. If not cancelled, the selection is changed and the SelectedGroupChanged event is raised.

SelectedItem

Gets or sets the currently selected item in the treemap.

Declaration
public TreeMapDataItem SelectedItem { get; set; }
Property Value
TreeMapDataItem

Remarks

Setting this property triggers the SelectedItemChanging event, which can be cancelled. If not cancelled, the selection is changed and the SelectedItemChanged event is raised.

SelectedItemBackColor

Gets or sets the background color for selected items.

Declaration
public Color SelectedItemBackColor { get; set; }
Property Value
System.Drawing.Color

Remarks

When an item is selected and this color is not empty, it overrides the item's default background color. The value is cached for performance during rendering operations.

SelectedItemBorderColor

Gets or sets the border color for selected items.

Declaration
public Color SelectedItemBorderColor { get; set; }
Property Value
System.Drawing.Color

Remarks

This color is used to draw the border around items when they are selected. The value is cached for performance during rendering operations.

SelectedItemBorderWidth

Gets or sets the border width in pixels for selected items.

Declaration
public int SelectedItemBorderWidth { get; set; }
Property Value
System.Int32

Remarks

This value determines the thickness of the border drawn around items when they are selected. The value is cached for performance during rendering operations.

ShowLegend

Gets or sets a value indicating whether the legend is displayed for the treemap.

Declaration
public bool ShowLegend { get; set; }
Property Value
System.Boolean

Remarks

The legend shows color mappings for different groups or categories in the treemap visualization.

Title

Gets or sets the title text displayed at the top of the treemap.

Declaration
public string Title { get; set; }
Property Value
System.String

TitleElement

Gets the title element that displays the treemap title.

Declaration
public TreeMapTitleElement TitleElement { get; }
Property Value
TreeMapTitleElement

TitleStack

Gets the stack layout element that contains the title area.

Declaration
public StackLayoutElement TitleStack { get; }
Property Value
StackLayoutElement

ToolTip

Gets or sets the tooltip control used for displaying standard tooltips.

Declaration
public RadToolTip ToolTip { get; set; }
Property Value
RadToolTip

Remarks

If no tooltip is explicitly set, a default RadToolTip instance is created when first accessed.

ToolTipDisplayMode

Gets or sets the mode for displaying tooltips when hovering over treemap elements.

Declaration
public ToolTipDisplayMode ToolTipDisplayMode { get; set; }
Property Value
ToolTipDisplayMode

Remarks

Options include None (no tooltips), ToolTip (standard tooltips), or ScreenTip (Office-style screen tips).

ValueMember

Gets or sets the value member.

Declaration
public string ValueMember { get; set; }
Property Value
System.String

Remarks

The ValueMember property specifies which property of the bound data objects contains the numeric values that determine the size of each rectangle in the treemap visualization.

WrapItemText

Gets or sets a value indicating whether text in treemap items should wrap to multiple lines.

Declaration
public bool WrapItemText { get; set; }
Property Value
System.Boolean

Remarks

When enabled, long text that doesn't fit within an item's rectangle will wrap to the next line. When disabled, text is displayed on a single line and may be truncated with ellipsis.

Methods

AddStylePropertySetting(IPropertySetting)

Adds a style property setting and clears the cached values to ensure they are refreshed.

Declaration
protected override ValueUpdateResult AddStylePropertySetting(IPropertySetting setting)
Parameters
IPropertySetting setting

The property setting to add.
Returns
ValueUpdateResult

The result of the value update operation.
Overrides

ArrangeOverride(SizeF)

Arranges the treemap element and positions the title and legend stacks according to the legend position.

Declaration
protected override SizeF ArrangeOverride(SizeF finalSize)
Parameters
System.Drawing.SizeF finalSize

The final size allocated for the element.
Returns
System.Drawing.SizeF

The actual size used by the element.
Overrides
Remarks

This method positions the legend and title stacks to avoid overlapping with the main treemap content area. The legend has priority in positioning, and the title area is adjusted accordingly.

ColorizeItems()

Applies colors to all treemap items and groups using the configured Colorizer.

Declaration
public virtual void ColorizeItems()
Remarks

This method delegates to the colorizer to set background and foreground colors for items or groups, depending on whether grouping is enabled. It also synchronizes the legend display.

CreateBindingContext()

Creates the binding context used for data binding operations.

Declaration
protected virtual BindingContext CreateBindingContext()
Returns
System.Windows.Forms.BindingContext

A new System.Windows.Forms.BindingContext instance.

CreateChildElements()

Creates the child elements including title stack, title element, legend stack, and legend element.

Declaration
protected override void CreateChildElements()
Overrides

CreateDefaultAlgorithm()

Creates the default tree map algorithm used for calculating rectangle layouts.

Declaration
protected virtual TreeMapAlgorithm CreateDefaultAlgorithm()
Returns
TreeMapAlgorithm

A new SquarifiedAlgorithm instance as the default algorithm.

CreateDefaultColorizer()

Creates the default colorizer used for applying colors to treemap items and groups.

Declaration
protected virtual BaseColorizer CreateDefaultColorizer()
Returns
BaseColorizer

A new PaletteColorizer instance as the default colorizer.

CreateLegendElement()

Creates a new TreeMapLegendElement for displaying the treemap legend.

Declaration
protected virtual TreeMapLegendElement CreateLegendElement()
Returns
TreeMapLegendElement

A new TreeMapLegendElement instance associated with this treemap element.

CreateLegendStack()

Creates a new StackLayoutElement for organizing the legend area.

Declaration
protected virtual StackLayoutElement CreateLegendStack()
Returns
StackLayoutElement

A new StackLayoutElement instance.

CreateListSource()

Creates the list source that manages the data binding and collection view.

Declaration
protected virtual TreeMapListSource CreateListSource()
Returns
TreeMapListSource

A new TreeMapListSource instance associated with this treemap element.

CreateScreenTipElement()

Creates a new RadOffice2007ScreenTipElement instance for displaying screen tips.

Declaration
protected virtual RadOffice2007ScreenTipElement CreateScreenTipElement()
Returns
RadOffice2007ScreenTipElement

A new RadOffice2007ScreenTipElement instance with empty text labels.

CreateTitleElement()

Creates a new TreeMapTitleElement for displaying the treemap title.

Declaration
protected virtual TreeMapTitleElement CreateTitleElement()
Returns
TreeMapTitleElement

A new TreeMapTitleElement instance.

CreateTitleStack()

Creates a new StackLayoutElement for organizing the title area.

Declaration
protected virtual StackLayoutElement CreateTitleStack()
Returns
StackLayoutElement

A new StackLayoutElement instance.

CreateToolTip()

Creates a new RadToolTip instance for displaying tooltips.

Declaration
protected virtual RadToolTip CreateToolTip()
Returns
RadToolTip

A new RadToolTip instance.

DisposeManagedResources()

Releases the unmanaged resources used by the RadTreeMapElement and optionally releases the managed resources.

Declaration
protected override void DisposeManagedResources()
Overrides

EvaluateAlgorithm()

Evaluates the treemap layout algorithm and updates the bounds of all items and groups.

Declaration
public virtual void EvaluateAlgorithm()
Remarks

This method calculates the size and position of each rectangle in the treemap based on the item values and the configured algorithm. It handles both grouped and ungrouped scenarios and applies colorization after layout calculation.

FindGroup(Point)

Finds the topmost group at the specified location within the treemap.

Declaration
protected virtual TreeMapDataItemGroup FindGroup(Point location)
Parameters
System.Drawing.Point location

The point to search for groups.
Returns
TreeMapDataItemGroup

The TreeMapDataItemGroup at the specified location, or null if no group is found.
Remarks

This method performs hierarchical hit testing to find the most specific group at the given location. If groups are nested, it returns the innermost group that contains the point.

FindGroup(Point, TreeMapDataItemGroup, IEnumerable<TreeMapDataItemGroup>)

Recursively searches for groups at the specified location within a collection of groups.

Declaration
protected virtual TreeMapDataItemGroup FindGroup(Point location, TreeMapDataItemGroup parent, IEnumerable<TreeMapDataItemGroup> groups)
Parameters
System.Drawing.Point location

The point to search for groups.
TreeMapDataItemGroup parent

The parent group being searched (can be null for root level).
System.Collections.Generic.IEnumerable<TreeMapDataItemGroup> groups

The collection of groups to search within.
Returns
TreeMapDataItemGroup

The most specific TreeMapDataItemGroup at the location, or null if none found.

GetAlgorithmRectangle()

Calculates the rectangle area available for the treemap algorithm, excluding title, legend, borders, and padding.

Declaration
protected virtual Rectangle GetAlgorithmRectangle()
Returns
System.Drawing.Rectangle

A System.Drawing.Rectangle representing the area where treemap items should be positioned.
Remarks

This method accounts for the title height, legend position and size, element borders, and padding to determine the actual space available for rendering treemap rectangles.

GetItemAndGroup(Point, out TreeMapDataItem, out TreeMapDataItemGroup)

Determines the item and group at the specified location.

Declaration
protected virtual bool GetItemAndGroup(Point location, out TreeMapDataItem item, out TreeMapDataItemGroup group)
Parameters
System.Drawing.Point location

The point to perform hit testing.
TreeMapDataItem item

When this method returns, contains the item at the location or null.
TreeMapDataItemGroup group

When this method returns, contains the group at the location or null.
Returns
System.Boolean

True if an item or group was found at the location; otherwise, false.
Remarks

This method first searches for groups, then searches for items within the found group or at the root level. It provides the foundation for hover detection, selection, and tooltip functionality.

InitializeFields()

Initializes the fields and default property values for the RadTreeMapElement.

Declaration
protected override void InitializeFields()
Overrides

InitializeTreeMap()

Initializes the treemap by evaluating the layout algorithm and applying colors.

Declaration
public virtual void InitializeTreeMap()
Remarks

This method should be called after setting up data sources, algorithms, or other configuration to ensure the treemap is properly rendered.

ManageToolTip(Point, TreeMapDataItem, TreeMapDataItemGroup)

Manages tooltip display for the specified item or group at the given location.

Declaration
protected virtual void ManageToolTip(Point location, TreeMapDataItem item, TreeMapDataItemGroup group)
Parameters
System.Drawing.Point location

The mouse location where the tooltip should be displayed.
TreeMapDataItem item

The item to show tooltip for, or null.
TreeMapDataItemGroup group

The group to show tooltip for, or null.
Remarks

This method handles both screen tip and standard tooltip modes, showing appropriate content based on the hovered item or group and the configured ToolTipDisplayMode.

MeasureOverride(SizeF)

Measures the treemap element and its child elements to determine the desired size.

Declaration
protected override SizeF MeasureOverride(SizeF availableSize)
Parameters
System.Drawing.SizeF availableSize

The maximum size available for the element.
Returns
System.Drawing.SizeF

The desired size of the element, which is the full available size.
Overrides
Remarks

This method measures the legend stack first, then calculates the remaining space for the title stack. The legend position affects how the available space is divided between title and legend areas.

NewItem()

Creates a new data item instance for use in the treemap.

Declaration
public IDataItem NewItem()
Returns
IDataItem

A new TreeMapDataItem instance associated with this treemap element.
Implements
Remarks

This method creates a new item and raises the ItemCreating event to allow customization of the item creation process.

OnAlgorithmEvaluated()

Raises the AlgorithmEvaluated event.

Declaration
protected virtual void OnAlgorithmEvaluated()

OnBoundsChanged(RadPropertyChangedEventArgs)

Handles bounds changes by reevaluating the algorithm and invalidating the display.

Declaration
protected override void OnBoundsChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

The bounds change event arguments.
Overrides
Remarks

When the element size changes, the treemap layout needs to be recalculated to fit the new dimensions.

OnDataItemCreating(TreeMapItemCreatingEventArgs)

Raises the ItemCreating event.

Declaration
protected virtual void OnDataItemCreating(TreeMapItemCreatingEventArgs args)
Parameters
TreeMapItemCreatingEventArgs args

The event arguments containing the item being created.

OnGroupPainted(TreeMapGroupPaintedEventArgs)

Raises the GroupPainted event.

Declaration
protected virtual void OnGroupPainted(TreeMapGroupPaintedEventArgs args)
Parameters
TreeMapGroupPaintedEventArgs args

The event arguments containing information about the painted group.

OnGroupPainting(TreeMapGroupPaintingEventArgs)

Raises the GroupPainting event.

Declaration
protected virtual void OnGroupPainting(TreeMapGroupPaintingEventArgs args)
Parameters
TreeMapGroupPaintingEventArgs args

The event arguments containing painting information for the group.

OnHoveredGroupChanged(TreeMapGroupChangedEventArgs)

Raises the HoveredGroupChanged event.

Declaration
protected virtual void OnHoveredGroupChanged(TreeMapGroupChangedEventArgs args)
Parameters
TreeMapGroupChangedEventArgs args

The event arguments containing the old and new hovered groups.

OnHoveredItemChanged(TreeMapItemChangedEventArgs)

Raises the HoveredItemChanged event.

Declaration
protected virtual void OnHoveredItemChanged(TreeMapItemChangedEventArgs args)
Parameters
TreeMapItemChangedEventArgs args

The event arguments containing the old and new hovered items.

OnItemDataBound(TreeMapItemEventArgs)

Raises the ItemDataBound event.

Declaration
protected virtual void OnItemDataBound(TreeMapItemEventArgs args)
Parameters
TreeMapItemEventArgs args

The event arguments containing the bound item.

OnItemPainted(TreeMapItemPaintedEventArgs)

Raises the ItemPainted event.

Declaration
protected virtual void OnItemPainted(TreeMapItemPaintedEventArgs args)
Parameters
TreeMapItemPaintedEventArgs args

The event arguments containing information about the painted item.

OnItemPainting(TreeMapItemPaintingEventArgs)

Raises the ItemPainting event.

Declaration
protected virtual void OnItemPainting(TreeMapItemPaintingEventArgs args)
Parameters
TreeMapItemPaintingEventArgs args

The event arguments containing painting information for the item.

OnLoaded()

Handles the Loaded event by updating the legend display.

Declaration
protected override void OnLoaded()
Overrides
Remarks

This method ensures that the legend is properly initialized and displayed when the element is loaded.

OnMouseDown(MouseEventArgs)

Handles the mouse down event for item and group selection.

Declaration
protected override void OnMouseDown(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

The mouse event arguments.
Overrides

OnMouseLeave(EventArgs)

Handles the mouse leave event by clearing hover states and hiding tooltips.

Declaration
protected override void OnMouseLeave(EventArgs e)
Parameters
System.EventArgs e

The event arguments.
Overrides

OnMouseMove(MouseEventArgs)

Handles the mouse move event for hover tracking and tooltip management.

Declaration
protected override void OnMouseMove(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

The mouse event arguments.
Overrides

OnPropertyChanged(RadPropertyChangedEventArgs)

Handles property change notifications and clears cached values when relevant properties change.

Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

The property change event arguments.
Overrides
Remarks

This method clears specific cached values when their corresponding properties change, ensuring that the cached values are refreshed on the next access.

OnScreenTipShowing(TreeMapScreenTipEventArgs)

Raises the ScreenTipShowing event.

Declaration
protected virtual void OnScreenTipShowing(TreeMapScreenTipEventArgs args)
Parameters
TreeMapScreenTipEventArgs args

The event arguments containing screen tip information and cancellation capability.

OnSelectedGroupChanged(TreeMapGroupChangedEventArgs)

Raises the SelectedGroupChanged event.

Declaration
protected virtual void OnSelectedGroupChanged(TreeMapGroupChangedEventArgs args)
Parameters
TreeMapGroupChangedEventArgs args

The event arguments containing the old and new selected groups.

OnSelectedGroupChanging(TreeMapGroupChangingEventArgs)

Raises the SelectedGroupChanging event.

Declaration
protected virtual void OnSelectedGroupChanging(TreeMapGroupChangingEventArgs args)
Parameters
TreeMapGroupChangingEventArgs args

The event arguments containing the old and new selected groups and cancellation capability.

OnSelectedItemChanged(TreeMapItemChangedEventArgs)

Raises the SelectedItemChanged event.

Declaration
protected virtual void OnSelectedItemChanged(TreeMapItemChangedEventArgs args)
Parameters
TreeMapItemChangedEventArgs args

The event arguments containing the old and new selected items.

OnSelectedItemChanging(TreeMapItemChangingEventArgs)

Raises the SelectedItemChanging event.

Declaration
protected virtual void OnSelectedItemChanging(TreeMapItemChangingEventArgs args)
Parameters
TreeMapItemChangingEventArgs args

The event arguments containing the old and new selected items and cancellation capability.

OnShowScreenTip(ComponentInputBehavior)

Overrides the default screen tip behavior to prevent automatic screen tip display.

Declaration
protected override bool OnShowScreenTip(ComponentInputBehavior inputBehavior)
Parameters
ComponentInputBehavior inputBehavior

The input behavior requesting the screen tip.
Returns
System.Boolean

False to prevent the default screen tip behavior.
Overrides
Remarks

This method is used internally to control screen tip display through the ManageToolTip(Point, TreeMapDataItem, TreeMapDataItemGroup) method instead.

OnToolTipShowing(TreeMapToolTipEventArgs)

Raises the ToolTipShowing event.

Declaration
protected virtual void OnToolTipShowing(TreeMapToolTipEventArgs args)
Parameters
TreeMapToolTipEventArgs args

The event arguments containing tooltip information and cancellation capability.

PaintContent(IGraphics)

Renders the visual content of the treemap by painting groups or individual items.

Declaration
protected override void PaintContent(IGraphics graphics)
Parameters
IGraphics graphics

The graphics object used for rendering.
Overrides
Remarks

This method serves as the main entry point for treemap rendering. It delegates to either group painting or item painting based on whether grouping is enabled and groups exist.

PaintGroup(IGraphics, TreeMapDataItemGroup)

Renders a single treemap group including its header, background, border, and contents.

Declaration
public virtual void PaintGroup(IGraphics graphics, TreeMapDataItemGroup group)
Parameters
IGraphics graphics

The graphics object used for rendering.
TreeMapDataItemGroup group

The group to paint.
Remarks

This method handles the complete rendering of a group, including raising the GroupPainting event for customization, painting the header background and text, drawing borders, and rendering child content.

PaintGroupBorder(TreeMapDataItemGroup, IGraphics, RectangleF, RectangleF, Color)

Renders the border around a group and the separator line below the header.

Declaration
protected virtual void PaintGroupBorder(TreeMapDataItemGroup group, IGraphics graphics, RectangleF rectangle, RectangleF headerRect, Color borderColor)
Parameters
TreeMapDataItemGroup group

The group whose border is being painted.
IGraphics graphics

The graphics object used for rendering.
System.Drawing.RectangleF rectangle

The overall rectangle of the group.
System.Drawing.RectangleF headerRect

The rectangle area of the header.
System.Drawing.Color borderColor

The border color to use.

PaintGroupContent(TreeMapDataItemGroup, IGraphics)

Renders the content area of a group, including child groups or items.

Declaration
protected virtual void PaintGroupContent(TreeMapDataItemGroup group, IGraphics graphics)
Parameters
TreeMapDataItemGroup group

The group whose content is being painted.
IGraphics graphics

The graphics object used for rendering.
Remarks

This method recursively paints child groups if they exist, otherwise it paints the individual items within the group.

PaintGroupHeaderBackground(TreeMapDataItemGroup, IGraphics, RectangleF, Color)

Renders the background of a group header.

Declaration
protected virtual void PaintGroupHeaderBackground(TreeMapDataItemGroup group, IGraphics graphics, RectangleF headerRect, Color backColor)
Parameters
TreeMapDataItemGroup group

The group whose header background is being painted.
IGraphics graphics

The graphics object used for rendering.
System.Drawing.RectangleF headerRect

The rectangle area of the header.
System.Drawing.Color backColor

The background color to use.

PaintGroupHeaderText(TreeMapDataItemGroup, IGraphics, RectangleF, String, Color, Font, ContentAlignment)

Renders the text content of a group header.

Declaration
protected virtual void PaintGroupHeaderText(TreeMapDataItemGroup group, IGraphics graphics, RectangleF headerRect, string groupText, Color foreColor, Font font, ContentAlignment textAlignment)
Parameters
TreeMapDataItemGroup group

The group whose header text is being painted.
IGraphics graphics

The graphics object used for rendering.
System.Drawing.RectangleF headerRect

The rectangle area of the header.
System.String groupText

The text to display.
System.Drawing.Color foreColor

The text color to use.
System.Drawing.Font font

The font to use for text rendering.
System.Drawing.ContentAlignment textAlignment

The alignment of the text within the header rectangle.

PaintGroups(IGraphics, IEnumerable<TreeMapDataItemGroup>)

Renders a collection of treemap groups.

Declaration
public virtual void PaintGroups(IGraphics graphics, IEnumerable<TreeMapDataItemGroup> groups)
Parameters
IGraphics graphics

The graphics object used for rendering.
System.Collections.Generic.IEnumerable<TreeMapDataItemGroup> groups

The collection of groups to paint.
Remarks

This method iterates through all groups and calls PaintGroup(IGraphics, TreeMapDataItemGroup) for each one.

PaintItem(IGraphics, TreeMapDataItem)

Renders a single treemap item including its background, text, and border.

Declaration
public virtual void PaintItem(IGraphics graphics, TreeMapDataItem dataItem)
Parameters
IGraphics graphics

The graphics object used for rendering.
TreeMapDataItem dataItem

The item to paint.
Remarks

This method handles the complete rendering of an item, including applying selection and hover effects, raising the ItemPainting event for customization, and painting the background, text, and border.

PaintItemBackground(TreeMapDataItem, IGraphics, RectangleF, Color)

Renders the background of a treemap item.

Declaration
protected virtual void PaintItemBackground(TreeMapDataItem dataItem, IGraphics graphics, RectangleF rectangle, Color backColor)
Parameters
TreeMapDataItem dataItem

The item whose background is being painted.
IGraphics graphics

The graphics object used for rendering.
System.Drawing.RectangleF rectangle

The rectangle area to fill.
System.Drawing.Color backColor

The background color to use.

PaintItemBorder(TreeMapDataItem, IGraphics, RectangleF, Color, Int32)

Renders the border around a treemap item.

Declaration
protected virtual void PaintItemBorder(TreeMapDataItem dataItem, IGraphics graphics, RectangleF rectangle, Color borderColor, int borderWidth)
Parameters
TreeMapDataItem dataItem

The item whose border is being painted.
IGraphics graphics

The graphics object used for rendering.
System.Drawing.RectangleF rectangle

The rectangle area for the border.
System.Drawing.Color borderColor

The border color to use.
System.Int32 borderWidth

The width of the border in pixels.

PaintItems(IGraphics, IEnumerable<TreeMapDataItem>)

Renders a collection of treemap items.

Declaration
public virtual void PaintItems(IGraphics graphics, IEnumerable<TreeMapDataItem> items)
Parameters
IGraphics graphics

The graphics object used for rendering.
System.Collections.Generic.IEnumerable<TreeMapDataItem> items

The collection of items to paint.
Remarks

This method iterates through all items and calls PaintItem(IGraphics, TreeMapDataItem) for each one.

PaintItemText(TreeMapDataItem, IGraphics, RectangleF, String, Color, Font, ContentAlignment)

Renders the text content of a treemap item.

Declaration
protected virtual void PaintItemText(TreeMapDataItem dataItem, IGraphics graphics, RectangleF rectangle, string text, Color foreColor, Font font, ContentAlignment textAlignment)
Parameters
TreeMapDataItem dataItem

The item whose text is being painted.
IGraphics graphics

The graphics object used for rendering.
System.Drawing.RectangleF rectangle

The rectangle area for text placement.
System.String text

The text to display.
System.Drawing.Color foreColor

The text color to use.
System.Drawing.Font font

The font to use for text rendering.
System.Drawing.ContentAlignment textAlignment

The alignment of the text within the rectangle.

ShouldArrangeChild(RadElement)

Determines whether a child element should be arranged during the layout process.

Declaration
protected override bool ShouldArrangeChild(RadElement child)
Parameters
RadElement child

The child element to evaluate.
Returns
System.Boolean

False if the child is the title stack or legend stack; otherwise, the base implementation result.
Overrides
Remarks

The title and legend stacks are handled separately in the layout process and do not participate in the normal child arrangement cycle.

ShouldMeasureChild(RadElement)

Determines whether a child element should be measured during the layout process.

Declaration
protected override bool ShouldMeasureChild(RadElement child)
Parameters
RadElement child

The child element to evaluate.
Returns
System.Boolean

False if the child is the title stack or legend stack; otherwise, the base implementation result.
Overrides
Remarks

The title and legend stacks are handled separately in the layout process and do not participate in the normal child measurement cycle.

UpdateLegend()

Updates the legend visibility and content based on current settings.

Declaration
protected virtual void UpdateLegend()
Remarks

This method refreshes the legend visual items if the legend is enabled, then updates the legend visibility based on grouping state and legend display settings.

UpdateLegendVisibility()

Updates the visibility state of the legend element based on current conditions.

Declaration
protected virtual void UpdateLegendVisibility()
Remarks

The legend is visible only when there are groups, ShowLegend is true, and LegendPosition is not None. Changes in visibility trigger layout updates.

Events

AlgorithmEvaluated

Occurs when the treemap layout Algorithm has been evaluated and all items have valid bounds.

Declaration
public event EventHandler AlgorithmEvaluated
Event Type
System.EventHandler

Remarks

This event is raised after the algorithm calculates the size and position of all rectangles in the treemap, providing an opportunity to perform custom operations on the calculated layout.

GroupPainted

Occurs after a group and its items have been painted, providing an opportunity for post-rendering operations.

Declaration
public event TreeMapGroupPaintedEventHandler GroupPainted
Event Type
TreeMapGroupPaintedEventHandler

Remarks

This event is raised after the complete group rendering is finished, including all child content, allowing for additional custom drawing or overlay effects.

GroupPainting

Occurs before a group is painted, allowing custom rendering or modification of paint parameters.

Declaration
public event TreeMapGroupPaitingEventHandler GroupPainting
Event Type
TreeMapGroupPaitingEventHandler

Remarks

This event provides access to the graphics object and paint parameters, enabling custom rendering logic for group headers, backgrounds, and borders.

HoveredGroupChanged

Occurs when the hovered group changes due to mouse movement.

Declaration
public event TreeMapGroupChangedEventHandler HoveredGroupChanged
Event Type
TreeMapGroupChangedEventHandler

Remarks

This event is raised when the mouse moves over different groups in the treemap, provided that AllowHotTracking is enabled.

HoveredItemChanged

Occurs when the hovered item changes due to mouse movement.

Declaration
public event TreeMapItemChangedEventHandler HoveredItemChanged
Event Type
TreeMapItemChangedEventHandler

Remarks

This event is raised when the mouse moves over different items in the treemap, provided that AllowHotTracking is enabled.

ItemCreating

Occurs when a TreeMapDataItem needs to be created during data binding operations.

Declaration
public event TreeMapItemCreatingEventHandler ItemCreating
Event Type
TreeMapItemCreatingEventHandler

Remarks

This event allows customization of the item creation process, enabling the use of custom item types or initialization of item properties during data binding.

ItemDataBound

Occurs when a data-bound item is being attached to a TreeMapDataItem instance.

Declaration
public event TreeMapItemEventHandler ItemDataBound
Event Type
TreeMapItemEventHandler

Remarks

This event is raised after an item has been created and bound to its data source object, allowing for custom initialization or property mapping.

ItemPainted

Occurs after an item has been painted, providing an opportunity for post-rendering operations.

Declaration
public event TreeMapItemPaitedEventHandler ItemPainted
Event Type
TreeMapItemPaitedEventHandler

Remarks

This event is raised after the standard item rendering is complete, allowing for additional custom drawing or overlay effects.

ItemPainting

Occurs before an item is painted, allowing custom rendering or modification of paint parameters.

Declaration
public event TreeMapItemPaitingEventHandler ItemPainting
Event Type
TreeMapItemPaitingEventHandler

Remarks

This event provides access to the graphics object and paint parameters, enabling custom rendering logic or modification of colors, fonts, and other visual properties.

ScreenTipShowing

Occurs before a screen tip is displayed, allowing customization or cancellation.

Declaration
public event TreeMapScreenTipEventHandler ScreenTipShowing
Event Type
TreeMapScreenTipEventHandler

Remarks

This event provides access to the screen tip element and allows modification of its content or cancellation of its display by setting the Cancel property to true.

SelectedGroupChanged

Occurs after the selected group has changed.

Declaration
public event TreeMapGroupChangedEventHandler SelectedGroupChanged
Event Type
TreeMapGroupChangedEventHandler

Remarks

This event is raised after a successful selection change, providing information about the previous and current selected groups.

SelectedGroupChanging

Occurs before the selected group changes, providing an opportunity to cancel the selection.

Declaration
public event TreeMapGroupChangingEventHandler SelectedGroupChanging
Event Type
TreeMapGroupChangingEventHandler

Remarks

This event can be cancelled by setting the Cancel property of the event arguments to true, which will prevent the selection change from occurring.

SelectedItemChanged

Occurs after the selected item has changed.

Declaration
public event TreeMapItemChangedEventHandler SelectedItemChanged
Event Type
TreeMapItemChangedEventHandler

Remarks

This event is raised after a successful selection change, providing information about the previous and current selected items.

SelectedItemChanging

Occurs before the selected item changes, providing an opportunity to cancel the selection.

Declaration
public event TreeMapItemChangingEventHandler SelectedItemChanging
Event Type
TreeMapItemChangingEventHandler

Remarks

This event can be cancelled by setting the Cancel property of the event arguments to true, which will prevent the selection change from occurring.

ToolTipShowing

Occurs before a tooltip is displayed, allowing customization or cancellation.

Declaration
public event TreeMapToolTipEventHandler ToolTipShowing
Event Type
TreeMapToolTipEventHandler

Remarks

This event provides access to the tooltip parameters and allows modification of the text, location, duration, or cancellation of the tooltip display.

Explicit Interface Implementations

IDataItemSource.BindingComplete()

This method is not relevant for this class.

Declaration
void IDataItemSource.BindingComplete()
Implements

IDataItemSource.BindingContext

Gets the binding context used for data binding operations.

Declaration
BindingContext IDataItemSource.BindingContext { get; }
Returns
System.Windows.Forms.BindingContext

Implements

IDataItemSource.BindingContextChanged

This event is not relevant for this class.

Declaration
event EventHandler IDataItemSource.BindingContextChanged
Returns
System.EventHandler

Implements

IDataItemSource.Initialize()

Initializes the data item source by reinitializing the treemap if a data source is present.

Declaration
void IDataItemSource.Initialize()
Implements
Remarks

This method clears any existing selections and reinitializes the treemap layout and data binding.

IDataItemSource.MetadataChanged(PropertyDescriptor)

This method is not relevant for this class.

Declaration
void IDataItemSource.MetadataChanged(PropertyDescriptor pd)
Parameters
System.ComponentModel.PropertyDescriptor pd

The property descriptor that changed.
Implements

Extension Methods