RadHeatMapElement
Represents the main visual element that renders a heat map visualization with data cells, headers, legend, and title. This element provides the core functionality for displaying tabular data as a color-coded matrix with support for interactive features like selection, hover tracking, and tool tips.
Definition
Namespace:Telerik.WinControls.UI
Assembly:Telerik.WinControls.UI.dll
Syntax:
public class RadHeatMapElement : LightVisualElement, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IBindableComponent, IComponent, IDisposable, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IPrimitiveElement, IShapedElement, IFillElement, IBorderElement, IBoxStyle, IBoxElement, IDrawFillElement, IImageElement, ITextPrimitive, ITextProviderInheritance: objectDisposableObjectRadObjectRadElementVisualElementRadComponentElementRadItemUIItemBaseLightVisualElementRadHeatMapElement...
Implements:
Inherited Members
Constructors
Initializes a new instance of the RadHeatMapElement class.
public RadHeatMapElement()Fields
cellIndicesToRects
IDictionary<CellIndex, RectangleF>
public IDictionary<CellIndex, RectangleF> cellIndicesToRectsIdentifies the ColumnHeaderHeight dependency property for controlling column header cell height.
public static RadProperty ColumnHeaderHeightPropertyIdentifies the HeaderCellBackColor dependency property for controlling header cell background color.
public static RadProperty HeaderCellBackColorPropertyIdentifies the HeaderCellBorderColor dependency property for controlling header cell border color.
public static RadProperty HeaderCellBorderColorPropertyIdentifies the HeaderCellBorderWidth dependency property for controlling header cell border width.
public static RadProperty HeaderCellBorderWidthPropertyIdentifies the HeaderCellFont dependency property for styling header cell text.
public static RadProperty HeaderCellFontPropertyIdentifies the HeaderCellForeColor dependency property for controlling header cell text color.
public static RadProperty HeaderCellForeColorPropertyIdentifies the HeaderCellHoverBackColor dependency property for controlling header cell background color during mouse hover.
public static RadProperty HeaderCellHoverBackColorPropertyIdentifies the HeaderCellHoverForeColor dependency property for controlling header cell text color during mouse hover.
public static RadProperty HeaderCellHoverForeColorPropertyIdentifies the HoveredCellBorderColor dependency property for controlling data cell border color during mouse hover.
public static RadProperty HoveredCellBorderColorPropertyIdentifies the HoveredCellBorderWidth dependency property for controlling data cell border width during mouse hover.
public static RadProperty HoveredCellBorderWidthPropertyIdentifies the RowHeaderWidth dependency property for controlling row header cell width.
public static RadProperty RowHeaderWidthPropertyIdentifies the SelectedCellBorderColor dependency property for controlling selected data cell border color.
public static RadProperty SelectedCellBorderColorPropertyIdentifies the SelectedCellBorderWidth dependency property for controlling selected data cell border width.
public static RadProperty SelectedCellBorderWidthPropertyProperties
Gets or sets a value indicating whether hot tracking behavior is enabled, allowing cells to be highlighted when hovered.
public bool AllowHotTracking { get; set; }Gets or sets a value indicating whether cell selection functionality is enabled in the heat map.
public bool AllowSelection { get; set; }Gets or sets a value indicating whether legend items should be generated automatically when ShowLegend is enabled. When true, legend items are automatically created and the VisualItemCreating event is fired for each item. When false, legend items must be added programmatically.
public bool AutoGenerateLegendItems { get; set; }Gets or sets the text alignment for content within data cells in the heat map.
public ContentAlignment CellTextAlignment { get; set; }Gets or sets the format string used for displaying data values as text within heat map cells.
public string CellTextFormat { get; set; }Gets or sets the height in pixels of column header cells in the heat map.
public int ColumnHeaderHeight { get; set; }Gets or sets the position of column headers within the heat map layout.
public ColumnHeadersPosition ColumnHeadersPosition { get; set; }Gets or sets the format string used for displaying text within column header cells.
public string ColumnHeaderTextFormat { get; set; }Gets or sets the heat map definition that is responsible for managing the data source and organizing data into rows and columns for visualization.
public HeatMapDefinition Definition { get; set; }Gets or sets the content of the description cell located in the corner between row and column header cells. Note that the description is not shown if row or column headers are hidden.
public string DescriptionContent { get; set; }Gets or sets a value indicating whether cell values should be rendered as text within the heat map cells.
public bool DisplayCellText { get; set; }Gets or sets the text content displayed in cells that contain no data or null values. This text is also used as the tool tip text for empty cells.
public string EmptyCellText { get; set; }Gets or sets the font used for rendering text within data cells of the heat map. This property defines the font face, size, and style attributes for cell text and is inheritable through the element tree.
public override Font Font { get; set; }Overrides:
Gets or sets the background color for header cells in the heat map.
public Color HeaderCellBackColor { get; set; }Gets or sets the border color for header cells in the heat map.
public Color HeaderCellBorderColor { get; set; }Gets or sets the border width in pixels for header cells in the heat map.
public int HeaderCellBorderWidth { get; set; }Gets or sets the font used for rendering text within header cells of the heat map.
public Font HeaderCellFont { get; set; }Gets or sets the text color for header cells in the heat map.
public Color HeaderCellForeColor { get; set; }Gets or sets the background color for header cells when the mouse is hovering over them.
public Color HeaderCellHoverBackColor { get; set; }Gets or sets the text color for header cells when the mouse is hovering over them.
public Color HeaderCellHoverForeColor { get; set; }Gets or sets the text alignment for content within header cells in the heat map.
public ContentAlignment HeaderCellTextAlignment { get; set; }Gets or sets the border color for data cells when the mouse is hovering over them.
public Color HoveredCellBorderColor { get; set; }Gets or sets the border width in pixels for data cells when the mouse is hovering over them.
public int HoveredCellBorderWidth { get; set; }Gets the index of the cell currently being hovered by the mouse cursor.
[Browsable(false)]
public CellIndex HoveredCellIndex { get; protected set; }Gets a collection of HeatMapDataItem objects that represent the data items displayed in the heat map visualization.
[Browsable(false)]
public HeatMapDataItemCollection Items { get; }Gets or sets the alignment of the legend element relative to the control layout rectangle.
public LegendAlignment LegendAlignment { get; set; }Gets the HeatMapLegendElement that displays the heat map legend.
public HeatMapLegendElement LegendElement { get; }Gets or sets the layout orientation of items within the legend element.
public Orientation LegendOrientation { get; set; }Gets or sets the position of the legend element in the control layout rectangle.
public RadPosition LegendPosition { get; set; }Gets the StackLayoutElement that contains the legend element in the heat map layout.
public StackLayoutElement LegendStack { get; }Gets or sets the text displayed as the title of the legend element.
public string LegendTitle { get; set; }Gets or sets the format string used for displaying values in legend items.
public string LegendValueFormat { get; set; }Gets or sets the position of row headers within the heat map layout.
public RowHeadersPosition RowHeadersPosition { get; set; }Gets or sets the format string used for displaying text within row header cells.
public string RowHeaderTextFormat { get; set; }Gets or sets the width in pixels of row header cells in the heat map.
public int RowHeaderWidth { get; set; }Gets or sets the RadOffice2007ScreenTipElement instance used for displaying screen tips when ToolTipDisplayMode is set to ScreenTip.
public virtual RadOffice2007ScreenTipElement ScreenTipElement { get; set; }Gets or sets the border color for data cells when they are selected in the heat map.
public Color SelectedCellBorderColor { get; set; }Gets or sets the border width in pixels for data cells when they are selected in the heat map.
public int SelectedCellBorderWidth { get; set; }Gets or sets the index of the currently selected cell in the heat map.
[Browsable(false)]
public CellIndex SelectedCellIndex { get; set; }Gets the data item associated with the currently selected cell in the heat map.
[Browsable(false)]
public HeatMapDataItem SelectedDataItem { get; }Gets or sets a value indicating whether the legend element should be displayed in the heat map visualization.
public bool ShowLegend { get; set; }Gets or sets the title text displayed above the heat map visualization.
public string Title { get; set; }Gets the HeatMapTitleElement that displays the heat map title.
public HeatMapTitleElement TitleElement { get; }Gets the StackLayoutElement that contains the title element in the heat map layout.
public StackLayoutElement TitleStack { get; }Gets or sets the RadToolTip instance used for displaying tool tips when ToolTipDisplayMode is set to ToolTip.
public RadToolTip ToolTip { get; set; }Gets or sets the display mode for tool tips shown when hovering over heat map cells.
public ToolTipDisplayMode ToolTipDisplayMode { get; set; }Gets or sets a value indicating whether text should be wrapped within data cells when it exceeds the cell width.
public bool WrapCellText { get; set; }Gets or sets a value indicating whether text should be wrapped within header cells when it exceeds the cell width.
public bool WrapHeaderCellText { get; set; }Methods
Adds a style property setting and clears the internal cache to ensure proper rendering updates.
protected override ValueUpdateResult AddStylePropertySetting(IPropertySetting setting)The property setting to add.
Returns:A ValueUpdateResult indicating the result of the operation.
Overrides:
Creates and initializes the child elements including title stack, title element, legend stack, and legend element.
protected override void CreateChildElements()Overrides:
Creates a new HeatMapLegendElement instance for displaying the heat map legend.
protected virtual HeatMapLegendElement CreateLegendElement()A new HeatMapLegendElement instance associated with this heat map element.
Creates a new StackLayoutElement instance to contain the heat map legend element.
protected virtual StackLayoutElement CreateLegendStack()A new StackLayoutElement instance for legend layout.
Creates a new RadOffice2007ScreenTipElement instance for displaying screen tips when hovering over heat map cells.
protected virtual RadOffice2007ScreenTipElement CreateScreenTipElement()A new RadOffice2007ScreenTipElement instance with empty caption, main text, and footer text.
Creates a new HeatMapTitleElement instance for displaying the heat map title.
protected virtual HeatMapTitleElement CreateTitleElement()A new HeatMapTitleElement instance.
Creates a new StackLayoutElement instance to contain the heat map title element.
protected virtual StackLayoutElement CreateTitleStack()A new StackLayoutElement instance for title layout.
Creates a new RadToolTip instance for displaying tool tips when hovering over heat map cells.
protected virtual RadToolTip CreateToolTip()A new RadToolTip instance attached to the element tree's root element.
Releases the managed resources used by the RadHeatMapElement and optionally releases the unmanaged resources.
protected override void DisposeManagedResources()Overrides:
Determines the cell index at the specified location within the heat map content area.
protected virtual void GetCellIndex(Point location, out int rowIndex, out int columnIndex)The point location to check.
rowIndexintWhen this method returns, contains the row index of the cell at the specified location.
columnIndexintWhen this method returns, contains the column index of the cell at the specified location.
Initializes the default field values for the heat map element properties and appearance settings.
protected override void InitializeFields()Overrides:
Manages the display of tool tips and screen tips based on the current mouse location and cell index.
Handles bounds changes by updating cached cell bounds and invalidating the display.
protected override void OnBoundsChanged(RadPropertyChangedEventArgs e)A RadPropertyChangedEventArgs that contains the event data.
Overrides:
Raises the CellPainted event.
protected virtual void OnCellPainted(HeatMapCellPaintedEventArgs args)A HeatMapCellPaintedEventArgs that contains the event data.
Raises the HeaderCellPainted event.
protected virtual void OnHeaderPainted(HeatMapHeaderCellPaintedEventArgs args)A HeatMapHeaderCellPaintedEventArgs that contains the event data.
Raises the HeaderCellPainting event.
protected virtual void OnHeaderPainting(HeatMapHeaderCellPaintingEventArgs args)A HeatMapHeaderCellPaintingEventArgs that contains the event data.
Raises the HoveredCellIndexChanged event.
protected virtual void OnHoveredCellIndexChanged(HeatMapIndexChangedEventArgs args)A HeatMapIndexChangedEventArgs that contains the event data.
Raises the CellPainting event.
protected virtual void OnItemPainting(HeatMapCellPaintingEventArgs args)A HeatMapCellPaintingEventArgs that contains the event data.
Handles the element loaded event by updating the legend visibility and configuration.
protected override void OnLoaded()Overrides:
Handles the mouse down event by updating the selected cell index when selection is enabled.
protected override void OnMouseDown(MouseEventArgs e)A MouseEventArgs that contains the event data.
Overrides:
Handles the mouse move event by updating hover tracking and managing tool tip display.
protected override void OnMouseMove(MouseEventArgs e)A MouseEventArgs that contains the event data.
Overrides:
Handles property changes by updating the internal cache and triggering necessary updates for display properties.
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)A RadPropertyChangedEventArgs that contains the event data.
Overrides:
Raises the ScreenTipShowing event.
protected virtual void OnScreenTipShowing(HeatMapScreenTipEventArgs args)A HeatMapScreenTipEventArgs that contains the event data.
Raises the SelectedCellIndexChanged event.
protected virtual void OnSelectedCellIndexChanged(HeatMapIndexChangedEventArgs args)A HeatMapIndexChangedEventArgs that contains the event data.
Raises the SelectedCellIndexChanging event.
protected virtual void OnSelectedCellIndexChanging(HeatMapIndexChangingEventArgs args)A HeatMapIndexChangingEventArgs that contains the event data.
Prevents the default screen tip behavior from being executed.
protected override bool OnShowScreenTip(ComponentInputBehavior inputBehavior)The input behavior instance.
Returns:Always returns false to stop the default screen tip behavior.
Overrides:
Raises the ToolTipShowing event.
protected virtual void OnToolTipShowing(HeatMapToolTipEventArgs args)A HeatMapToolTipEventArgs that contains the event data.
Renders a single data cell with background color, border, and text based on the data item and current state.
public virtual void PaintCell(IGraphics graphics, RectangleF rect, CellIndex cellIndex, HeatMapDataItem dataItem)The IGraphics object used for rendering.
rectRectangleFThe RectangleF defining the cell's painting area.
cellIndexCellIndexThe CellIndex identifying the cell position.
dataItemHeatMapDataItemThe HeatMapDataItem containing the cell's data.
protected virtual void PaintCellBackground(CellIndex cellIndex, IGraphics graphics, RectangleF rectangle, Color backColor)protected virtual void PaintCellBorder(CellIndex cellIndex, IGraphics graphics, RectangleF rectangle, Color borderColor, int borderWidth)protected virtual void PaintCellText(CellIndex cellIndex, IGraphics graphics, RectangleF rectangle, string text, Color foreColor, Font font, ContentAlignment textAlignment)Orchestrates the painting of all content elements including background image, main image or SVG image, and text.
protected override void PaintContent(IGraphics graphics)The graphics context used for rendering content.
Overrides:
Renders a single header cell at the specified cell index with appropriate styling and content.
protected virtual void PaintHeaderCellBackground(CellIndex cellIndex, IGraphics graphics, RectangleF headerRect, Color backColor)protected virtual void PaintHeaderCellBorder(CellIndex cellIndex, IGraphics graphics, RectangleF rectangle, Color borderColor, int borderWidth)protected virtual void PaintHeaderCellText(CellIndex cellIndex, IGraphics graphics, RectangleF headerRect, string headerText, Color foreColor, Font font, ContentAlignment textAlignment, StringTrimming trimming, StringFormatFlags formatFlags)Resets and regenerates the visual items in the legend element when the legend is visible.
public virtual void ResetLegendItems()Determines whether the specified child element should be arranged during the layout process.
protected override bool ShouldArrangeChild(RadElement child)The child RadElement to evaluate.
Returns:True if the child should be arranged; otherwise, false.
Overrides:
Determines whether the specified child element should be measured during the layout process.
protected override bool ShouldMeasureChild(RadElement child)The child RadElement to evaluate.
Returns:True if the child should be measured; otherwise, false.
Overrides:
Updates the cached bounds for all cells including row headers, column headers, and data cells in the heat map.
public virtual void UpdateCachedBounds()protected virtual void UpdateLegend()protected virtual void UpdateLegendVisibility()Events
Occurs after a data cell in the heat map has been painted.
public event HeatMapCellPaintedEventHandler CellPaintedOccurs when a data cell in the heat map is about to be painted, allowing customization of cell appearance.
public event HeatMapCellPaitingEventHandler CellPaintingOccurs after a row or column header cell has been painted.
public event HeatMapHeaderPaintedEventHandler HeaderCellPaintedOccurs when a row or column header cell is about to be painted, allowing customization of header cell appearance.
public event HeatMapHeaderPaintingEventHandler HeaderCellPaintingOccurs when the hovered cell index changes during mouse movement over the heat map.
public event HeatMapIndexChangedEventHandler HoveredCellIndexChangedOccurs before a screen tip is displayed, allowing customization or cancellation of the screen tip.
public event HeatMapScreenTipEventHandler ScreenTipShowingOccurs after the selected cell index has changed in the heat map.
public event HeatMapIndexChangedEventHandler SelectedCellIndexChangedOccurs before the selected cell index changes, allowing the operation to be cancelled.
public event HeatMapIndexChangingEventHandler SelectedCellIndexChangingOccurs before a tool tip is displayed, allowing customization or cancellation of the tool tip.
public event HeatMapToolTipEventHandler ToolTipShowing