HTML Support#

Flexible TreeView's HTML rendering capabilities empower developers to create rich, visually dynamic content within tree nodes, significantly enhancing the end-user experience. By leveraging HTML, you can transform standard tree structures into compelling information displays. This allows your application to present complex hierarchical data more effectively, offering users a more intuitive and polished interface with minimal additional development effort.

Key benefits include:

Improved Information Hierarchy: Utilize visual styling such as bold, italics, and colors to emphasize key data points.
Enhanced Readability: Increase content density without sacrificing clarity.
Interactive Elements: Incorporate hyperlinks to foster user engagement and provide direct access to related information or actions.
Visual Cues: Employ background colors and embedded images to draw attention to critical information or differentiate node types.
Consistent Visual Language: Maintain a cohesive look and feel across your application by standardizing text presentation.

This document details the supported HTML tags and features, enabling you to fully harness the power of HTML in your Flexible TreeView implementations.

Enable HTML support#

All text-based node controls (e.g., NodeTextBox, NodeExpandableTextBox, NodeExpandablePanel) and column headers support HTML text rendering. To enable this feature, set the SupportHtml property of the respective node control or TreeColumn instance to true.

C#Visual Basic

// Enable HTML support for a node control
NodeTextBox nodeTextBox = new ARMSoft.FlexibleTreeView.NodeControls.NodeTextBox();
nodeTextBox.SupportHtml = true;

// Enable HTML support for a treeview column header
TreeColumn treeColumn = new ARMSoft.FlexibleTreeView.Columns.TreeColumn();
treeColumn.SupportHtml = true;

// Create a node with HTML text
Node node = new Node("<b>Bold,</b> <i>Italic,</i> <u>Underlined,</u> <s>Strikethrough</s> text");
node.AttachTo(tree);

' Enable HTML support for a node control
Dim nodeTextBox As New ARMSoft.FlexibleTreeView.NodeControls.NodeTextBox()
nodeTextBox.SupportHtml = True

' Enable HTML support for a treeview column header
Dim treeColumn As New ARMSoft.FlexibleTreeView.Columns.TreeColumn()
treeColumn.SupportHtml = True

' Create a node with HTML text
Dim node As New Node("<b>Bold,</b> <i>Italic,</i> <u>Underlined,</u> <s>Strikethrough</s> text")
node.AttachTo(tree)

Supported HTML tags#

The following HTML tags are supported:

Bold text - Renders Bold text.
Italic text - Renders Italic text.
Underlined text - Renders Underlined text.
<s>Strikeout text</s> - Renders ~~Strikeout text~~.
  - Inserts a single line break.
Colored text - Changes the text color. ColorId can be a predefined color name (from System.Drawing.Color) or a hexadecimal RGB value (e.g., #RRGGBB).
<a href='url'>Hyperlink</a> - Displays a clickable hyperlink. Handle link activation by subscribing to the LinkClicked event on the treeview. Link appearance can be customized via the TextStyle treeview property.
<tab width='xx'/> - Inserts a tab space. The optional width attribute (in pixels) overrides the default tab width of 20 pixels.
<img src='xx'/> - Renders an image specified in the src attribute. Refer to the IMG tag section for comprehensive information.
Text with background - Renders text with a specified background color. colorValue can be a color name or an RGB value (e.g., green, #112233).

Basic HTML usage

C#Visual Basic

// Enable HTML support for a node control
NodeTextBox nodeTextBox = new ARMSoft.FlexibleTreeView.NodeControls.NodeTextBox();
nodeTextBox.SupportHtml = true;
nodeTextBox.DataFieldName = "Text";
nodeTextBox.AttachTo(tree);

// Create test nodes with HTML text
Node node1 = new Node("<i>Some text</i><br/><b><font color='Blue'>Second</font> line</b>");
node1.AttachTo(tree);

Node node2 = new Node("<tab/>First line<br/>Second line");
node2.AttachTo(tree);

' Enable HTML support for a node control
Dim nodeTextBox As New ARMSoft.FlexibleTreeView.NodeControls.NodeTextBox()
nodeTextBox.SupportHtml = True
nodeTextBox.DataFieldName = "Text"
nodeTextBox.AttachTo(tree)

' Create test nodes with HTML text
Dim node1 As New Node("<i>Some text</i><br/><b><font color='Blue'>Second</font> line</b>")
node1.AttachTo(tree)

Dim node2 As New Node("<tab/>First line<br/>Second line")
node2.AttachTo(tree)

Attribute values for complex tags (e.g., font.color, a.href) must be enclosed in quotes. For text lacking proper quoting, use the HtmlTextHelper.TextToHtml static method to ensure valid HTML formatting.

Ensuring valid HTML with HtmlTextHelper

C#Visual Basic

// Potentially problematic HTML
string text = "<font color=Blue>Blue text</font>";
// Corrected HTML
Node node = new Node(ARMSoft.FlexibleTreeView.Text.Html.HtmlTextHelper.TextToHtml(text));

' Potentially problematic HTML
Dim text As String = "<font color=Blue>Blue text</font>"
' Corrected HTML
Dim node As New Node(ARMSoft.FlexibleTreeView.Text.Html.HtmlTextHelper.TextToHtml(text))

Special characters#

To render special characters within HTML text, use their corresponding HTML entities or encoding methods.

Rendering `<` and `>` characters#

To display literal < and > characters, replace them with < and > respectively. Alternatively, use << and >> in your source text and process it with the HtmlTextHelper.TextToHtml method for automatic conversion.

Handling < and > characters

C#Visual Basic

// Using << and >> with HtmlTextHelper for conversion
Node nodeWithHelper = new Node();
// Text becomes "if(a < 10 || b > 20) { return; }"
nodeWithHelper.Text = HtmlTextHelper.TextToHtml("if(a << 10 || b >> 20) { return; }");

// Using HTML entities directly
Node nodeWithEntities = new Node();
nodeWithEntities.Text = "if(a &lt; 10 || b &gt; 20) { return; }";

' Using << and >> with HtmlTextHelper for conversion
Dim nodeWithHelper As New Node()
' Text becomes "if(a < 10 || b > 20) { return; }"
nodeWithHelper.Text = HtmlTextHelper.TextToHtml("if(a << 10 || b >> 20) { return; }")

' Using HTML entities directly
Dim nodeWithEntities As New Node()
nodeWithEntities.Text = "if(a &lt; 10 || b &gt; 20) { return; }"

Rendering the `&` character#

To display the ampersand (&) character, use the & text instead.

IMG tag#

The <img> HTML tag facilitates the embedding of images from various sources, specified via the src attribute.

Rendering an image from the current node's Image property

HTML

<img src="node:Image">

The src attribute for <img> tags supports three distinct prefixes to define the image source:

node: Retrieves the image from a property or field of the current node (the node where the image is being rendered). This applies to both bound and unbound nodes.
HTML
<img src="node:Image">
This example renders an image stored in the Image property or field of the current node.
static: Retrieves the image from a static property. The property name must be fully assembly-qualified.
HTML
<img src="static:TestNamespace.Properties.Resources.imageToRender, TestAssembly">
This example renders an image from the imageToRender static property within the type TestNamespace.Properties.Resources, located in the TestAssembly assembly. If the specified image is not found, an empty area is rendered; no error is raised.

dynamic: Renders an image requested via the GetDynamicImage event of the TreeView. The string following dynamic: is passed as the image name to the event arguments.

Performance consideration

The GetDynamicImage event is invoked each time the image needs to be rendered. For optimal performance, consider caching the returned images, especially if they are frequently accessed or computationally expensive to generate.

HTMLC#Visual Basic

<img src="dynamic:closedAccountIcon">

// Assuming 'tree' is your FlexibleTreeView instance
tree.GetDynamicImage += TreeView_GetDynamicImage;

void TreeView_GetDynamicImage(FlexibleTreeView sender, ResolveNodeImageEventArgs e)
{
    if (e.ImageName == "closedAccountIcon")
    {
        // Example: Return different images based on node state
        if (e.Node != null && e.Node.IsFocused)
            e.Image = YourProject.Resources.ClosedAccountIconActive;
        else
            e.Image = YourProject.Resources.ClosedAccountIconInactive;
    }
}

' Assuming 'tree' is your FlexibleTreeView instance
AddHandler tree.GetDynamicImage, AddressOf TreeView_GetDynamicImage

Private Sub TreeView_GetDynamicImage(sender As FlexibleTreeView, e As ResolveNodeImageEventArgs)
    If e.ImageName = "closedAccountIcon" Then
        ' Example: Return different images based on node state
        If e.Node IsNot Nothing AndAlso e.Node.IsFocused Then
            e.Image = YourProject.Resources.ClosedAccountIconActive
        Else
            e.Image = YourProject.Resources.ClosedAccountIconInactive
        End If
    End If
End Sub

In this example, the closedAccountIcon image is requested dynamically by raising the GetDynamicImage event.

Note

The dynamic: source allows for sophisticated scenarios, such as returning different images based on node state (e.g., selected, focused), or other application-specific data.

Treeview themes support#

By default, when drawing HTML tags, Flexible TreeView honors the current treeview theme's text colors. However, by using the  and  tags, you can override the default foreground or background colors of the drawn HTML elements. This provides extensive possibilities for customizing the user experience (UX) and visual appearance of the tree nodes.

HTML text auto-wrapping#

Flexible TreeView supports automatic wrapping of HTML text content. For further details, consult the Text Wrapping documentation.

HTML tag inspection and customization#

Flexible TreeView provides a mechanism to inspect and customize the appearance of HTML tags before they are rendered. This is achieved by implementing the IHtmlTagInspector interface. Its ProcessHtmlTag method allows for fine-grained control over the styling of individual HTML tags.

For instance, to modify the appearance of text within a specific node control:

C#Visual Basic

// Custom node control to render all hyperlinks (<a> tags) as italic.
class NodeTextBoxExtended : NodeTextBox, IHtmlTagInspector
{
    protected override Size MeasureSize(Node node, DrawContext context)
    {
        // Register this instance as the HTML tag inspector for the current rendering pass.
        context.Owner = this;
        // Optionally pass custom data (e.g., the current node) to ProcessHtmlTag.
        context.Parameters = node;

        Size measuredSize = base.MeasureSize(node, context);

        // Reset Owner and Parameters after use.
        context.Owner = null;
        context.Parameters = null;

        return measuredSize;
    }

    protected override void Draw(Node node, DrawContext context)
    {
        context.Owner = this;
        context.Parameters = node;

        base.Draw(node, context);

        context.Owner = null;
        context.Parameters = null;
    }

    // This method is called for each HTML tag encountered within this control.
    public void ProcessHtmlTag(HtmlTextTag tag, DrawContext context)
    {
        // Retrieve the target node from custom parameters.
        Node currentNode = context.Parameters as Node;

        // Example: If rendering "My node" and the tag is a link, make it italic.
        if (currentNode != null && currentNode.Text == "My node" && tag.Link != null)
        {
            tag.Italic = true;
        }
    }
}

// Usage example:
NodeTextBoxExtended customTextBox = new NodeTextBoxExtended();
customTextBox.DataFieldName = "Text";
// Assuming 'tree' is your FlexibleTreeView instance.
customTextBox.AttachTo(tree);

' Custom node control to render all hyperlinks (<a> tags) as italic.
Class NodeTextBoxExtended
    Inherits NodeTextBox
    Implements IHtmlTagInspector

    Protected Overrides Function MeasureSize(node As Node, context As DrawContext) As Size
        ' Register this instance as the HTML tag inspector for the current rendering pass.
        context.Owner = Me
        ' Optionally pass custom data (e.g., the current node) to ProcessHtmlTag.
        context.Parameters = node

        Dim measuredSize As Size = MyBase.MeasureSize(node, context)

        ' Reset Owner and Parameters after use.
        context.Owner = Nothing
        context.Parameters = Nothing

        Return measuredSize
    End Function

    Protected Overrides Sub Draw(node As Node, context As DrawContext)
        context.Owner = Me
        context.Parameters = node

        MyBase.Draw(node, context)

        context.Owner = Nothing
        context.Parameters = Nothing
    End Sub

    ' This method is called for each HTML tag encountered within this control.
    Public Sub ProcessHtmlTag(tag As HtmlTextTag, context As DrawContext) Implements IHtmlTagInspector.ProcessHtmlTag
        ' Retrieve the target node from custom parameters.
        Dim currentNode As Node = TryCast(context.Parameters, Node)

        ' Example: If rendering "My node" and the tag is a link, make it italic.
        If currentNode IsNot Nothing AndAlso currentNode.Text = "My node" AndAlso tag.Link IsNot Nothing Then
            tag.Italic = True
        End If
    End Sub
End Class

' Usage example:
Dim customTextBox As New NodeTextBoxExtended()
customTextBox.DataFieldName = "Text"
' Assuming 'tree' is your FlexibleTreeView instance.
customTextBox.AttachTo(tree)

HTML Support#

Enable HTML support#

Supported HTML tags#

Special characters#

Rendering < and > characters#

Rendering the & character#

IMG tag#

Treeview themes support#

HTML text auto-wrapping#

HTML tag inspection and customization#

Rendering `<` and `>` characters#

Rendering the `&` character#