Tooltips

  • 11 minutes to read

A tooltip automatically pops up when a user hovers over a control or its child element. Most of DevExpress WinForms controls use the same mechanism to display tooltips (hints) - the ToolTipController component. This component manages hints for all controls in an application, and allows you to customize the tooltip behavior and appearance. For example, you can customize the foreground color, position, time interval passed before a tooltip is shown or hidden. The controller also allows you to assign tooltips to standard or third-party controls.

TIP

Run the Tooltip Controller demo to try out tooltips.

Default Tooltip Controller

The default controller manages tooltips for all controls in the application. The DefaultToolTipController component is a toolbox component that allows you to access the default controller in the designer — drop the DefaultToolTipController component onto the component tray. Use the Properties window to customize tooltips.

You can use the static (Shared in VB) ToolTipController.DefaultController property to access the default controller in code.

NOTE

You do not necessarily need to place the default controller to the form in order to enable tooltips. You can do it to access the controller — customize settings, add event handlers, etc.

Custom Tooltip Controller

DevExpress controls that support tooltips expose the ToolTipController property. The property specifies the controller that manages tooltips for that particular control. If you assign a custom controller to this property, it is used instead of the default controller. You can assign a single controller to multiple controls — the controller manages tooltips for all these controls. Drop the ToolTipController component from the toolbox onto the component tray and assign it to a control.

NOTE

You do not necessarily need to assign a custom controller to a control. You can do it to customize settings for that particular control. If the control is not bound to a custom controller, the default controller manages tooltips.

Tooltip Types

The tooltip controller supports different tooltip types: regular, flyout, and super tooltips. The ToolTipController.ToolTipType property allows you to specify the type of shown tooltips:

  • SuperTip — a tooltip that consists of a title, content, separator, and footer. You can also display a custom icon in the content area.

    This type supports skins — tooltips have the same look and feel as the owner control.

    See Super Tooltips below for more information.

  • Standard — a regular tooltip that consists of a title and content. You can also display one of the predefined icons, or a custom icon.

    Regular tooltips do not support skins. To display tooltips according to the current skin, you can change the tooltip type from Standard to SuperTip. The controller automatically converts the tooltips.

    See Regular Tooltips below for more information.

  • Flyout — a tooltip that can display any control in a flyout window.

    See Flyout Tooltips below for more information.

Super Tooltips

DevExpress controls expose the SuperTip property that allows you to assign a super tooltip to a control. The SuperToolTip Editor allows you to create super tooltips in the designer. To invoke the editor, click a control's SuperTip ellipsis button in the Properties window.

The editor allows you to add tooltip items: title, content, and separators. You can also remove/reorder the added items. When an item is selected, you can set its properties. The text editor allows you to enter the item's content and format it using HTML tags (note that the AllowHtmlText option should be enabled).

Create a Super Tooltip in Code

The SuperToolTip class represents a super tooltip. A super tooltip consists of multiple regions (items): title, content, separator, and footer. Items are arranged one under another, each item can display an image and text. A tooltip can contain any combination of items.

CD_ToolTips_SampleSuperToolTip

CD_ToolTips_SampleSuperToolTip2

Use the SuperToolTip.Items property to access/add/remove regions in the super tooltip:

  • ToolTipItem — the main region in a super tooltip that displays text and/or image.
  • ToolTipTitleItem — a region displayed at the top (title) or bottom (footer) of a tooltip. This region differs from the main region in default appearance settings.
  • ToolTipSeparatorItem — a horizontal line in a tooltip.

SuperTooltip_Struct

Text

Use the ToolTipItem object's following properties to specify the text:

Image

The ToolTipItem.ImageOptions provide access to the following properties that allow you to specify the image displayed in the item:

You can also use the ToolTipItem.Icon property to specify the item's icon. The Icon property has priority over ImageOptions.

Layout

Use the ToolTipItem.LeftIndent property to specify the indentation of the content from the tooltip's left edge.

You can also use the SuperToolTip.FixedTooltipWidth, MaxWidth, Padding, and DistanceBetweenItems properties to customize the layout.

Appearance

The item's Appearance property provides access to appearance settings that specify the font, border and foreground colors. The default settings depend on the current skin. This property allows you to change the skin's appearance settings.

Example: How to Create a Super Tooltip in Code

Create a SuperToolTip object and populate the Items collection with ToolTipItem, ToolTipTitleItem, and ToolTipSeparatorItem objects.

The code below displays the following tooltip.

using DevExpress.Utils;

// The component used to load images from a form's resources.
System.ComponentModel.ComponentResourceManager resources = 
  new System.ComponentModel.ComponentResourceManager(typeof(Form1));
// The image to display within a super tooltip.
Image resImage = ((System.Drawing.Image)(resources.GetObject("resource.Image1")));

// Create an object that represents a super tooltip.
SuperToolTip sTooltip1 = new SuperToolTip();
// Create an object that represents the title.
ToolTipTitleItem titleItem1 = new ToolTipTitleItem();
titleItem1.Text = "Edit Popup Menu";
// Create an object that represents the content.
ToolTipItem item1 = new ToolTipItem();
item1.ImageOptions.Image = resImage;
item1.Text = "Show the Edit popup menu";
// Add the items to the SuperTooltip.Items collection.
sTooltip1.Items.Add(titleItem1);
sTooltip1.Items.Add(item1);

// Assign the created SuperToolTip to a BarItem.
barItem1.SuperTip = sTooltip1;

You can also use the SuperToolTip.Setup method to create a super tooltip in code.

using DevExpress.Utils;

// Create an object that represents a super tooltip.
SuperToolTip sTooltip2 = new SuperToolTip();
// Create an object that initializes tooltip regions.
SuperToolTipSetupArgs args = new SuperToolTipSetupArgs();
args.Title.Text = "Edit Popup Menu";
args.Contents.Text = "Show the Edit popup menu";
args.Contents.ImageOptions.Image = resImage;
sTooltip2.Setup(args);

// Assign the created SuperToolTip to a BarItem.
barItem2.SuperTip = sTooltip2;

Regular Tooltips

A DevExpress control allows you to display a regular tooltip. The regular tooltip can contain the main message, title, and one of the predefined icons.

You can also handle the BeforeShow event to update a tooltip dynamically. For example, you can display the current time instead of the static text, or display a custom vector image.

How to Assign a Regular Tooltip to a Control

DevExpress controls expose the following properties that allow you to specify a regular tooltip:

Text

  • ToolTip — a regular tooltip's content. If the content is not specified, the tooltip is not displayed even if the title is specified. You can use line breaks in regular tooltips.
  • ToolTipTitle — a regular tooltip's title. If the title is not specified, it is not displayed.
  • AllowHtmlTextInToolTip — whether to parse HTML tags in the text. HTML tags allow you to format the text: size, style, hyperlinks, etc. This property overrides the controller's AllowHtmlText setting.

Appearance

Use the controller's AppearanceTitle and Appearance properties to specify the appearance settings applied to the text in the title and content regions. The default font style for the title is bold.

Image

  • ToolTipIconType — a regular tooltip's predefined image. To specify the image size, use the controller's IconSize property.

To display a custom image in all regular tooltips, use the controller's ImageList and ImageIndex properties.

To display a custom image in a particular regular tooltip, handle the BeforeShow event. Use the ImageOptions event argument to assign a raster or vector image to the processed tooltip.

Change Tooltip Type from Regular to Super

Super tooltips are painted according to the current skin, while regular tooltips look the same in all paint schemes.

CD_ToolTip_ToolTipAppearance

To replace regular tooltips with super tooltips, set the ToolTipController.ToolTipType property to SuperTip. The controller automatically converts regular tooltips to super tooltips.

Flyout Tooltips

To display a flyout tooltip, do the following:

using DevExpress.Utils;

ToolTipController.DefaultController.CloseOnClick = DefaultBoolean.False;
ToolTipController.DefaultController.KeepWhileHovered = true;

private void OnGetActiveObjectInfo(object sender, ToolTipControllerGetActiveObjectInfoEventArgs e) {
   if(e.Info == null) {
       e.Info = new ToolTipControlInfo() { Object = e.SelectedControl, ToolTipType = ToolTipType.Flyout };
       if(radioGroupExamples.SelectedIndex == 0)
           e.Info.FlyoutControl = ClockLabelControl;
       else
           e.Info.FlyoutControl = TimerControl;
    }
}
NOTE

Refer to How to use a custom UserControl as a tooltip for an alternative example.

IMPORTANT

If a flyout tooltip displays a focusable control, use the XtraForm or RibbonForm as a parent. Otherwise, the tooltip will be immediately hidden when the control is focused.

Assign a Tooltip to a Third-Party Control

The tooltip controller is an IExtenderProvider object and provides the following extending properties for third-party controls:

  • SuperTip — a super tooltip.
  • Title — a regular tooltip's title.
  • ToolTip — a regular tooltip's content.
  • ToolTipIconType — a regular tooltip's icon.
  • AllowHtmlText — specifies whether to parse HTML tags in the tooltip's text. HTML tags allow you to format the text: size, style, hyperlinks, etc. See How to: Display a Hyperlink in a Tooltip for an example.

Specify Tooltips in the Visual Studio Designer

To access the extending properties in the Visual Studio designer, drop the DefaultToolTipController or ToolTipController component onto the component tray. Select a control on the form — the properties are accessible in the Properties window.

You can also use the controller's properties and events to customize the content, appearance, and behavior.

Specify Tooltips in Code

To assign tooltips to third-party controls in code, use the DefaultToolTipController or ToolTipController component's following methods:

The code below shows how to assign a regular tooltip to the standard text box and specify tooltip properties.

using DevExpress.Utils;

// Access the default tooltip controller.
ToolTipController defController = ToolTipController.DefaultController;
// Customize the controller's settings.
defController.Appearance.BorderColor = Color.Red;
defController.ShowBeak = true;
// Set a tooltip for the TextBox control.
defController.SetToolTip(textBox1, "Enter the full name");

Examples