HTML-inspired Text Formatting

  • 14 minutes to read

A number of DevExpress controls allow you use simplified HyperText Markup Language (HTML) tags to format display text strings. This document describes available HTML-inspired tags, and lists all controls that support them.

NOTE

When the HTML Text Formatting feature is enabled for a certain control or its visual element, its text is painted in left-to-right mode, regardless of the RightToLeft option.

Supported Tags

Tags are enclosed with the '<' and '>' symbols, and typically have a corresponding end tag. If a tag is not matched by its ending counterpart, all text that follows the tag will be formatted accordingly.

NOTE

Note that if you need to use angle brackets ('<' and '>') in the text of the controls that support HTML text formatting, you need to use an additional '<' bracket at the beginning. For example, to get "<some text>" you should assign "<<some text>" to the corresponding property.

"Br" Tag

Inserts a single line break.

Sub-Sup-tags

To use this tag, you should enable word wrap with the TextOptions.WordWrap option of a corresponding appearance object.

Control or Control Element

Property that provides access to appearance settings

GridControl

GridViewAppearances.HeaderPanel
GridColumn.AppearanceHeader
BandedViewAppearances.BandPanel
GridBand.AppearanceHeader

TreeList

TreeListAppearanceCollection.HeaderPanel
TreeListColumn.AppearanceHeader

LabelControl

LabelControl.Appearance

CheckEdit

RepositoryItem.Appearance

LayoutControlItem

BaseLayoutItem.AppearanceItemCaption

  • Syntax: <br>

  • Example: First Name<br>Last Name

"Color" and "Backcolor" Tags

Specify text foreground and background colors.

Sub-Sup-tags

Syntax: <color=value></color> <backcolor=value></backcolor>

Examples:

  • <color=red>Text</color>, <backcolor=red>Text</backcolor>
  • <color=0,255,0>Text</color>, <backcolor=0,255,0>Text</backcolor>
  • <color=255,0,255,0>Text</color> <backcolor=255,0,255,0>Text</backcolor>
  • <color=#0000FF>Text</color>" <backcolor=#0000FF>Text</backcolor>"

The "Color" tag overrides Appearance forecolors. "Backcolor" blends with Appearance back colors if its alpha transparency key is less than 255 (40 in the example below).

simpleButton1.AllowHtmlDraw = DevExpress.Utils.DefaultBoolean.True;
simpleButton1.Appearance.ForeColor = Color.Maroon;
simpleButton1.Text = "Maroon <color=green>Green</color> Maroon";

simpleButton2.AllowHtmlDraw = DevExpress.Utils.DefaultBoolean.True;
simpleButton2.Appearance.BackColor = Color.DimGray;
simpleButton2.Text = "<backcolor=40,255,255,255>Light Gray</backcolor>";

"Size" Tag

Specifies the font size.

Sub-Sup-tags

Syntax: <size=value></size>

Examples:

  • <size=10>10pt text</size>
  • <size=+4>Larger text</size>
  • <size=-4>Smaller text</size>

Text Format Tags ("b", "i", "s", "u", "r")

Allow you to create bold, italic, underlined and strikethrough strings.

The "r" tag applies normal text formatting. This resets any existing bold, italic, underlined and strikethrough formats, including those applied in control Appearance settings.

Sub-Sup-tags

Syntax: <b></b>, <i></i>, <s></s>, <u></u>, <r>

Examples:

  • <b>Bold text</b>
  • <i>Italic text</i>
  • <s>Strikethrough text</s>
  • <u>Underlined text</u>
  • <b>Bold-<u>UnderlinedBold-</u><r>Normal</b>

If the static DevExpress.Utils.Text.StringParser.KeepFontStyle property is false, a text block that has font style HTML tags (font family, font weight, etc.) ignores AppearanceObject font style settings. Otherwise, both font style sets are applied.

simpleButton1.AllowHtmlDraw = DevExpress.Utils.DefaultBoolean.True;
simpleButton1.Appearance.FontStyleDelta = FontStyle.Bold;
simpleButton1.Text = "One <i>Two</i> Three";
//KeepFontStyle = false: "One" and "Three" bold, "Two" is italic
//KeepFontStyle = true: "One" and "Three" are bold, "Two" is bold and italic

parser

The default KeepFontStyle property value is false for versions 19.1 and older, and true for v19.2 and newer.

You can insert closing HTML tags to ignore corresponding Appearance settings.

simpleButton1.AllowHtmlDraw = DevExpress.Utils.DefaultBoolean.True;
simpleButton1.Appearance.FontStyleDelta = FontStyle.Italic | FontStyle.Bold;
simpleButton1.Text = "Bold and Italic </b>Only Italic </i>Regular";

simpleButton2.AllowHtmlDraw = DevExpress.Utils.DefaultBoolean.True;
simpleButton2.Appearance.FontStyleDelta = FontStyle.Underline | FontStyle.Bold;
simpleButton2.Text = "Underline and Bold </u>Only Bold";

"Sub" and "Sup" Tags

Define text that is smaller than neighboring letters, and displayed lower (subscript) or higher (superscript) than the previous character. Note that you cannot change fonts within text blocks that use "sub" and (or) "sup" tags.

Sub-Sup-tags

Syntax: <sub>Text</sub>, <sup>Text</sup>

Examples:

  • Subscript: H<sub>2</sub>O
  • Double subscript: 2<sub>2<sub>2</sub></sub>
  • Superscript: 5<sup>2</sup>=25
  • Double superscript: 5<sup>2<sup>2</sup></sup>

"Font" Tag

Specifies the font family. Can be combined with Color and Size settings inside a single tag.

font

Syntax: <font></font>

Examples:

  • <font=Helvetica>Helvetica</font>
  • <font='Times New Roman'size=15 color=red>Times New Roman</font>

"Image" Tag

Inserts an image from a bound image collection or from project resources. To insert an image from project resources, the image's name must be preceded with the '#' character. The image referenced from project resources will not appear at design time, but will appear at runtime.

NOTE

Project resource images can only be loaded from the Entry Assembly (the startup executable). Thus, if you define images in the resources of your additional class library, these images cannot be loaded using the image tag, even from this library code.

If the image's name is not preceded with '#', it is implied that the image should be loaded by its name from a bound image collection. Use the control's HtmlImages property to provide an image collection (ImageCollection or SvgImageCollection ).

The following attributes for the image tag are supported.

  • size - sets the display size of the image.

  • align - specifies the vertical alignment of the image relative to the text. Possible values: top, bottom and center.

Attributes must be specified after the tag's value, followed by the ";" character. They must be separated with ";", and specified without spaces.

Controls and components that accept the image tag and provide the HtmlImages property are listed below.

Syntax: <image=value>

Examples:

  • <image=UpArrow.png>
  • <image=#LeftArrow>
  • <image=DownArrow.png;size=20,20;align=top>

"P" Tag

Defines a paragraph. Supports the "align" parameter that allows you to arrange a paragraph content. The code below illustrates how to center text and image inside an XtraMessageBox.

image

XtraMessageBoxArgs args = new XtraMessageBoxArgs();
args.AllowHtmlText = DefaultBoolean.True;
svgImageCollection1.ImageSize = new Size(48, 48);
args.HtmlImages = svgImageCollection1;
args.Text = "<p align=center><image=warning><br>" +
    "<b>Something went wrong</b><br>" +
    "We're having technical issues at the moment.<br>" +
    "Please try again later.</p>";
args.Caption = "Warning";
args.Buttons = new DialogResult[] { DialogResult.OK };
XtraMessageBox.Show(args);

"Href" and "a href" Tags

Display a hyperlink. The value string specifies the hyperlink source, and the string between the opening and closing tags is the text to be displayed.

Sub-Sup-tags

Controls that can display hyperlinks raise the HyperlinkClick event when a user clicks a link.

Syntax: <href=value></href> or <a href=value></a>

Example: <href=www.devexpress.com>Our web site</href>, <a href=www.devexpress.com>Our web site</a>

"Nbsp" Tag

Inserts a non-breaking space character (0xA0).

Sub-Sup-tags

Syntax: <nbsp>

Example: First Name<nbsp>Last Name

Supported Controls

All Controls

Element that supports tags

Editor property that turns HTML-formatting on or off

Tooltips and SuperToolTips

ToolTipController.AllowHtmlText, SuperToolTip.AllowHtmlText, ToolTipItem.AllowHtmlText

Tooltips for BaseControl descendants - the BaseControl.ToolTip property

BaseControl.AllowHtmlTextInToolTip

XtraForm caption - the XtraForm.HtmlText property

n/a

ContextButton text - the ContextButtonBase.Caption property.

ContextButtonBase.AllowHtmlText

ValidationHint texts - the (ValidationHintBaseDefaultProperties.Text and ValidationHintBaseProperties.Text properties

ValidationHintBaseDefaultProperties.AllowHtmlDrawText

ValidationHintBaseProperties.AllowHtmlDrawText

Charts

In ChartControl, you can use HTML-inspired tags to format:

Editors Library

The table below enumerates editors from the DevExpress Editors suite that support tags.

Element that supports tags

Editor property that turns HTML-formatting on or off

LabelControl text - the LabelControl.Text property

LabelControl.AllowHtmlString

CheckEdit and ToggleSwitch text

RepositoryItem.AllowHtmlDraw

SimpleButton text - the (SimpleButton.Text property

SimpleButton.AllowHtmlDraw

Text strings in ButtonEdit descendants whose RepositoryItemButtonEdit.TextEditStyle

property is set to TextEditStyles.DisableTextEditor

RepositoryItem.AllowHtmlDraw

Button texts for ButtonEdit and its descendants

RepositoryItem.AllowHtmlDraw

ListBoxControl and CheckedListBoxControl items

BaseListBoxControl.AllowHtmlDraw

ComboBoxEdit, ImageComboBoxEdit and CheckedComboBoxEdit items

RepositoryItem.AllowHtmlDraw

GroupControl text - the GroupControl.Text property

GroupControl.AllowHtmlText

RatingControl text - the RatingControl.Text property

RepositoryItemRatingControl.AllowHtmlDraw

Data Grid

The GridControl supports HTML tags in the following elements.

Element that supports tags

Property that turns HTML-formatting on or off

View caption - the BaseView.ViewCaption property

n/a

Column captions - the GridColumn.Caption property

GridOptionsView.AllowHtmlDrawHeaders

Band captions - the GridBand.Caption property

GridOptionsView.AllowHtmlDrawHeaders

Cell text. Note that cells with HTML-formatted values cannot be edited at runtime.

There are multiple ways to add HTML tags to cell text strings.

No dedicated property. Use RepositoryItemHypertextLabel as an in-place editor.

Group row texts - handle the GridView.CustomDrawGroupRow event

GridOptionsView.AllowHtmlDrawGroups

column captions in the TileView's Edit Form - the GridColumn.Caption

TileViewOptionsEditForm.AllowHtmlCaptions

WinExplorerView items

WinExplorerViewOptionsView.AllowHtmlText

Tree List

The TreeList supports HTML tags in the following elements.

Element that supports tags

Property that turns HTML-formatting on or off

Column captions - the TreeListColumn.Caption property

TreeListOptionsView.AllowHtmlDrawHeaders

Band captions - the TreeListBand.Caption property

TreeListOptionsView.AllowHtmlDrawHeaders

Cell text. Note that cells with HTML-formatted values cannot be edited at runtime.

There are multiple ways to add HTML tags to cell text strings.

No dedicated property. Use RepositoryItemHypertextLabel as an in-place editor.

Pivot Grid

The PivotGridControl supports HTML tags in the following elements.

Element that supports tags

Property that turns HTML-formatting on or off

Field headers text - the PivotGridFieldBase.Caption property

PivotGridOptionsView.AllowHtmlDrawHeaders

Field values text - the PivotGridControl.FieldValueDisplayText event and

the PivotFieldDisplayTextEventArgs.DisplayText property.

PivotGridOptionsView.AllowHtmlDrawFieldValues

Vertical Grid and Property Grid

The PropertyGridControl is the VGridControl control descendant. Both controls have identical elements that support HTML tags.

Element that supports tags

Property that turns HTML-formatting on or off

Row captions

BaseOptionsView.AllowHtmlText

VGridOptionsRow.AllowHtmlText

CustomDrawRowHeaderCellEventArgs.AllowHtmlText

Cell text. Note that cells with HTML-formatted values cannot be edited at runtime.

There are multiple ways to add HTML tags to cell text strings.

No dedicated property. Use RepositoryItemHypertextLabel as an in-place editor.

Layout Control

The LayoutControl supports HTML tags in the following elements.

Element that supports tags

Property that turns HTML-formatting on or off

Item captions - the BaseLayoutItem.Text property

LayoutControlItem.AllowHtmlStringInCaption

LayoutGroup.AllowHtmlStringInCaption

Item tooltips

BaseLayoutItemOptionsToolTip.AllowHtmlString

BaseLayoutItemOptionsToolTip.IconAllowHtmlString

ToolTipController.AllowHtmlText

Ribbon, Bars and Menus

Element that supports tags

Property that turns HTML-formatting on or off

Item captions and descriptions - the BarItem.Caption and BarItem.Description properties

BarItem.AllowHtmlText

BarItemLink.AllowHtmlText

BarManager.AllowHtmlText

RibbonControl.AllowHtmlText

BackstageViewControl item captions - the BackstageViewItem.Caption property

BackstageViewItem.AllowHtmlString

Gallery item and group items - the GalleryItem.Caption and GalleryItemGroup.Caption properties

BaseGallery.AllowHtmlText

Application UI Manager

The DocumentManager supports HTML tags in the following elements.

Element that supports tags

Property that turns HTML-formatting on or off

Document headers - the BaseDocument.Header property

IDocumentSelectorDefaultProperties.AllowHtmlDrawHeaders

IDocumentSelectorProperties.AllowHtmlDrawHeaders

Document captions - the BaseDocument.Caption property

IDocumentGroupDefaultProperties.AllowHtmlDraw

IDocumentGroupProperties.AllowHtmlDraw

Flyout description and caption - the UIActionPropertiesCore.Caption and

UIActionPropertiesCore.Description properties

IFlyoutDefaultProperties.AllowHtmlDraw

IFlyoutProperties.AllowHtmlDraw

Tile elements

ITileContainerDefaultProperties.AllowHtmlDraw

Content containers' overview screens

OverviewContainerDefaultProperties.AllowHtmlDraw

OverviewContainerProperties.AllowHtmlDraw

Element that supports tags

Property that turns HTML-formatting on or off

OfficeNavigationBar item captions - the NavigationBarItem.Text property

OfficeNavigationBar.AllowHtmlDraw

WindowsUIButton captions

WindowsUIButtonPanel.AllowHtmlDraw

TileControl and TileBar tiles

TileControl.AllowHtmlText

TileItem.AllowHtmlText

NavBarControl item and group texts - the NavElement.Caption property

NavBarControl.AllowHtmlString

NavElement.AllowHtmlString

Navigation Frame, Tab Pane and Navigation Pane pages (both caption and text)

NavigationPageDefaultProperties.AllowHtmlDraw

NavigationPageProperties.AllowHtmlDraw

NavigationPane.AllowHtmlDraw

AccordionControl element headers - the AccordionControlElementBase.Text property

AccordionControl.AllowHtmlText

XtraTabControl page captions

XtraTabControl.AllowHtmlDraw

Gauges

Enable the Label.AllowHTMLString property to format label text strings in the GaugeControl.

Scheduler

To display HTML tags inside appointment subject, description or location, enable the View's AppointmentDisplayOptions.AllowHtmlText setting and handle the SchedulerControl.InitAppointmentDisplayText event.

Map Control

The MapControl supports HTML tags in the following elements.

Element that supports tags

Property that turns HTML-formatting on or off

MapCallout text

MapCallout.AllowHtmlText

MapCustomElement text

MapCustomElement.AllowHtmlText

Dialogs and Wizards

Element that supports tags

Property that turns HTML-formatting on or off

XtraDialog and XtraMessageBox captions

XtraDialog.AllowHtmlText

XtraMessageBox.AllowHtmlText

WizardControl pages' text

WizardControl.AllowHtmlText

AlertControl windows' captions and regular text blocks

AlertControl.AllowHtmlText

Example 1

The following example shows how to format a LabelControl's text using HTML tags. HTML formatting is enabled via the LabelControl.AllowHtmlString property. To respond to an end-user clicking the hyperlink, the LabelControl.HyperlinkClick event is handled. The image below shows the result:

label_HTML_formatting

labelControl1.Text = "<size=14>Size = 14<br>" +
                     "<b>Bold</b> <i>Italic</i> <u>Underline</u><br>" + 
                     "<size=11>Size = 11<br>" + 
                     "<color=255, 0, 0>Sample Text</color></size>" +
                     "<href=www.devexpress.com>Hyperlink</href>";
labelControl1.AllowHtmlString = true;
labelControl1.Appearance.TextOptions.WordWrap = DevExpress.Utils.WordWrap.Wrap;
labelControl1.Appearance.Options.UseTextOptions = true;
labelControl1.AutoSizeMode = DevExpress.XtraEditors.LabelAutoSizeMode.Vertical;

private void labelControl1_HyperlinkClick(object sender, DevExpress.Utils.HyperlinkClickEventArgs e) {
    System.Diagnostics.Process.Start(e.Link);
}

Example 2

This example shows how to create a super tooltip with a hyperlink and assign it to a SimpleButton.

The button's SuperTip property allows you to specify a super tooltip. Use the ToolTipController.AllowHtmlText, SuperToolTip.AllowHtmlText, or ToolTipItem.AllowHtmlText property to enable HTML tags. Handle the ToolTipController.HyperlinkClick event to respond to a click on the hyperlink.

The SuperToolTip Editor allows you to create super tooltips in the designer. To invoke the editor, click the SuperTip property's ellipsis button in the Properties window.

If you create a tooltip in the designer, you still need to handle the HyperlinkClick event in code. Use the Properties window to assign an event handler.

The example below shows how to create a super tooltip in code.

using DevExpress.Utils;
using System.Diagnostics;

private void Form1_Load(object sender, EventArgs e) {
    // Access the controller that manages tooltips for all controls:
    ToolTipController defaultTooltipController = DevExpress.Utils.ToolTipController.DefaultController;

    // Create and customize a SuperToolTip:
    SuperToolTip sTooltip = new SuperToolTip();
    SuperToolTipSetupArgs args = new SuperToolTipSetupArgs();
    args.Title.Text = "Header";
    args.Contents.Text = "This tooltip contains a hyperlink. Visit the <href=http://help.devexpress.com>DevExpress Knowledge Center</href> to learn more.";
    args.ShowFooterSeparator = true;
    args.Footer.Text = "Footer";
    sTooltip.Setup(args);
    // Enable HTML Text Formatting for the created SuperToolTip:
    sTooltip.AllowHtmlText = DefaultBoolean.True;
    //..or enable this feature for all tooltips:
    //defaultTooltipController.AllowHtmlText = true;

    // Respond to clicking hyperlinks in tooltips:
    defaultTooltipController.HyperlinkClick += defaultTooltipController_HyperlinkClick;

    // Assign a SuperToolTip to the button:
    simpleButton1.SuperTip = sTooltip;
}

void defaultTooltipController_HyperlinkClick(object sender, HyperlinkClickEventArgs e) {
    Process process = new Process();
    process.StartInfo.FileName = (e.Link);
    process.StartInfo.Verb = "open";
    process.StartInfo.WindowStyle = ProcessWindowStyle.Normal;
    try {
        process.Start();
    }
    catch { }
}
See Also