Spotlight on the ToolTip Control

The Spotlight on Controls series describes the controls, that is, the objects in the System.Windows.Forms namespace, so you can use them effectively when building GUI apps in PowerShell Studio and PrimalScript.

Each post focuses on one control and lists its most important properties, methods, and events, including the default event that PowerShell Studio adds to your script when you double-click the control. The posts include many examples written in Windows PowerShell, so you can use them right away.

Read more: Spotlight on Controls: Common properties and methods

This post describes the ToolTip control.

ToolTip [System.Windows.Forms.ToolTip]

Represents a small rectangular pop-up window that typically displays help for the feature. The tooltip appears when the mouse hovers over the control.

Use a ToolTip to display help information about a control with minimal configuration.

 

Important Properties

Active Turns the ToolTip on and off
AutomaticDelay Determines three tooltip delay property values
InitialDelay Sets and changes the time before the ToolTip appears
IsBalloon Changes the Tooltip from rectangular to balloon-shaped
ReshowDelay Sets the time between the display of each tooltip
ToolTipIcon Adds an icon to the ToolTip text
ToolTipTitle Adds a title to the Tooltip window
ToolTipTitle Adds a title to the Tooltip window

NOTES:

  • The BackColor and ForeColor properties of the ToolTip have no effect unless you are using the OwnerDraw property of the ToolTip to override the appearance set by the operating system.
  • The ToolTip control does not have a Text property. To set the text of a ToolTip, use the SetToolTip method.

Important Methods

SetToolTip Associates a tooltip with a control and specifies its text.

How to Create a ToolTip

To begin, add a ToolTip to a form. The ToolTip control appears at the bottom of the Designer window. You do not place the ToolTip on the form.

ToolTipInSPS

When you add a ToolTip to a form, PowerShell Studio adds new dynamic property, ToolTip on <ToolTipName>, to all controls in the Designer, including controls that you add after you add the Tooltip control.

To create a ToolTip for a control, in the ToolTip on <ToolTipName> property of the control (not the property of the ToolTip), type the ToolTip text.

For example, to create a ToolTip for the $buttonStart button, in the Properties pane for the $buttonStart button, in the ToolTip on tooltip1 property, add a string value.

ToolTipProperty

Tip

TIP: As a best practice, keep the ToolTip text short. However, to add multiple lines of text in a ToolTip, use the newline character,`n.

 

You can also set or change the control or text of a ToolTip in your script. This is useful when the text is stored in a variable or you want to change the control or text of a tooltip after the form loads.

To set or change a ToolTip, use the SetToolTip method of the ToolTip. The SetToolTip method takes two arguments, the variable that contains the control and the ToolTip text (or a variable that contains the text).

For example, this statement associates $tooltip1 with $buttonStart and specifies its text.

$tooltip1.SetToolTip($buttonStart, "To start the task, click Start.")

In this example, the statement associates $tooltip1 with $buttonStart and uses the text in a variable. This technique allows you to localize your UI text. For more information, see about_Scripts_Internationalization.

$tipStart = "To start the task, click Start."
$tooltip1.SetToolTip($buttonStart, $tipStart)

To create a ToolTip for another control in the form, you can add another ToolTip or reuse the existing ToolTip. If you reuse the ToolTip, any property changes, such as setting the Active property to $False, affect all instances of the ToolTip.

For example, this script uses the ToolTip in $tooltip1 to create ToolTips for both the Start and Stop buttons.

$tooltip1.SetToolTip($buttonStart, "To start the task, click Start.")
$tooltip1.SetToolTip($buttonStop, "To stop the task, click Stop.")

In contrast, this script uses a separate ToolTip for each of the buttons.

$tooltipButtonStart.SetToolTip($buttonStart, "To start the task, click Start.")
$tooltipButtonStop.SetToolTip($buttonStop, "To stop the task, click Stop.")


Active property: Turns the ToolTip on and off

Use this property to disable and enable tooltips.

For example, this statement disables the ToolTip in $tooltip1.

$tooltip1.Active = $False

AutomaticDelay property: Determines three tooltip delay property values

Use this property to coordinate the ToolTip delay property values, instead of setting each delay property individually.

The AutomaticDelay property sets the following values:

  • AutoPopupDelay = AutomaticDelay x 10
  • InitialDelay = AutomaticDelay
  • ReshowDelay = AutomaticDelay / 5

InitialDelay property: The elapsed time before the ToolTip appears, in milliseconds

Use this property to determine the number of milliseconds between the time the user hovers places the cursor over the control and the time that the Tooltip appears.

If the delay is too short, the tooltip appears when the user is passing over, not hovering, and becomes annoying. If the delay is too long, the user moves on and does not discover the tooltip.

You can set this delay independently, or use the AutomaticDelay property to coordinate the values of the Tooltip delay properties.

IsBalloon property: Determines whether the Tooltip is balloon-shaped or rectangular

Use the IsBalloon property to change the shape of the Tooltip.

 

False

image

True

image

ReshowDelay property: Time between tooltips

Use the ReshowDelay property to set the length of time, in milliseconds, that elapses before subsequent ToolTip windows appear as the cursor moves from one control to another.

You can set the ReshowDelay property or, to coordinate the Tooltip delays, adjust the AutomaticDelay property.

ToolTipIcon property: Adds an icon to the ToolTip text.

Valid values are:

Error

image

Info

image

None

image

Warning

image

ToolTipTitle property: Adds a title to the Tooltip window

Use this property to add, remove, or change the Tooltip title.

For example, this tooltip has the title: ToolTip Title

image


 

SetToolTip method: Associates a ToolTip with a control and sets its text

Use this method to create a ToolTip for a control or replace the existing tooltip for the control.

SYNTAX: $tooltip.SetToolTip($control, $text)

For example, this statement associates the ToolTip in the $tooltipTest variable with the button in $button1 and sets its text to “This is a button”.

$tooltipTest.SetToolTip($button1, "This is a button")

You can also store the text in a variable and specify the variable in the method call.

$tooltip1Text = "This is a button"
$tooltipTest.SetToolTip($button1, $tooltipText)