Task-based Tutorials - Set/change ToolTip-content at run-time

This article discusses how to change the tooltip-content dynamically at run-time.

In most cases, the content for the tooltip of a control is usually assigned at design-time to the corresponding provided property in the property-page of the control. This is the preferred (and most practical) way to assign static content to a control's tooltip (see the "Quick-start tutorial".)

But already for static tooltip-content, there are situations, where the static content can only be determined and assigned to the tooltip of a control when the application is running, because the static content has to be computed or retrieved from a database first.

(Picture 1)

The same applies to applications, where some controls need to constantly update the content of the tooltip while it is being displayed: 

(Picture 2)


Both cases share the same problem: The tooltip-content can not be "hard-coded" into the application at design-time. It has to be assigned to the tooltips when the program is already executing. The consequence is, that some coding is needed in order to bring the content to the tooltips. And that's what we are going to show in the following paragraphs.

The two cases mentioned above seem to be quite different and to require completely different approaches, but actually they differ only in when and where - in terms of the executing program - the new tooltip-content has to be set or changed. The way (the code) how the new content is assigned to the tooltip of the specific controls is almost identical, the only thing that's really different is the location in the program-source where this should happen.

Because we now know that the assignment of tooltip-content at run-time is always done the same way, we should now have a closer look on how this is done in terms of real code. We'll do this by taking the first hypothetical example, where the Logout-button displays the name of the database to which the program is currently connected. (This example assumes that a SingleLineToolTip-component has been dropped on the corresponding form and was named SingleLineTT.)

As application developers, we all know, that before an application can have an open connection to a database (as the tooltip in Picture 1 suggests), this connection must first be established. In terms of the tooltip for the Logout-button (cmdLogout) it means that the "Connected to <database>"-string should only become visible after a connection to a database has been established and the name of the database is known. With this considered, we know where in the program the tooltip-content can be changed from "Not connected!" to "Connected to...". This can only happen after a connection has been successfully established. For our example we assume that there is a command-button (cmdConnect) which triggers the connection. The code to handle the click on the cmdConnect is shown below:


Private Sub cmdConnect_Click(ByVal sender As System.Object, _

                             ByVal e As System.EventArgs) _

                     Handles cmdConnect.Click

Dim status As Boolean

Dim db As DictionaryEntry


'Get the selected database from lbDatabases

db = lbDatabases.SelectedItem

'Connect to the selected database

status = ConnectToDB(db.Key)


If status = True Then

    'We have successfully connected to a db...

    '...and reflect this in the tooltip.

    Me.SingleLineTT.GetSingleLineToolTip(Me.cmdLogout) _

    .Text = "Connected to:" & db.Key


    'The connection did not succeed and we set the tooltip-

    'content accordingly.

    Me.SingleLineTT.GetSingleLineToolTip(Me.cmdLogout) _

    .Text = "Not connected!"

End If

End Sub

The interesting lines in this code are the lines, where the new content is assigned to the tooltip of the Logout-button. The function GetSingleLineToolTip()  gives access to the object provided to the control (specified by the passed parameter, cmdLogout) as an extended property.

The content for the tooltip can then be changed by simply assigning a new value to the main content property of the object returned by GetSingleLineToolTip(). For the SingleLineToolTip used in the sample it is the Text-property.

This example was only about the SingleLineToolTip-component, but the principle is the same for all other tooltip-components as well. Only the name of the function, to get a reference to the object provided to a control as an extended property, and the name of the main content-property of this object are different. For completeness they are  listed in the table below:


Component Access-function Main content property
ToolTipsFactoryAnimation GetAnimationToolTip() AnimatedSymbol
ToolTipsFactoryImage GetImageToolTip() Image
ToolTipsFactoryMultiLine GetMultiLineToolTip() Text
ToolTipsFactorySingleLine GetSingleLineToolTip() Text


Now we'll have a closer look on how the tooltip in Picture 2 gets its content, which consists of the current cursor-position over the displayed image. The coordinates displayed by the tooltip are updated constantly while the mouse is moving over the image. (This example assumes that a MulitLineToolTip-component has been dropped on the corresponding form and was named MultiLineTT.)

We can already imagine, how the specific line of code will look, where the content is updated. All we have to do, is to figure out, what would be a good location in the code to feed the changing coordinates to the tooltip.

Because the displayed coordinates depend on the moving mouse-pointer, it is almost obvious that the MouseMove-event of the control, that holds the image, would be a good place:

Sub PicBox_MouseMove(ByVal sender As Object, _

                     ByVal e As MouseEventArgs) Handles PicBox.MouseMove     

'Build the new coordinates-string and assign it to the tooltip

'of PicBox (sender). The current coordinates are taken from

'the MouseEventArgs (e).

Me.MultiLineTT.GetMultiLineToolTip(sender) _

.Text = "X=" & e.X.ToString & vbCrLf & " Y=" & e.Y.ToString

End Sub

This single line of code in the MouseMove event-handler of the PictureBox-control will feed the new coordinates to the tooltip whenever the mouse is moved over it. One important prerequisite for this code to work correctly, is the right setting of the FollowPointer-property. With FollowPointer = False, the ToolTip would not update the displayed content while it is already visible. FollowPointer = True makes sure that the tooltip itself will update its displayed content with any MouseMove-event.