This method initiates the display of a tooltip. It comes in two overloaded versions common to all tooltip components. Each tooltip component implements at least another two overloaded versions which are specific for the component. These are documented in the section on "Component-specific members".
[Visual Basic]
Public Overloads Sub Start()
Public Overloads Sub Start(ByVal control As Control)
[C#]
public void Start();
public void Start(Control control);
Parameters
control
The control, for which to display the tooltip.
Description
Start() initiates the display of a tooltip. It has the same effect as moving the mouse over a control (which fires the MouseEnter-event), for which the tooltip should be displayed.
Usually this method is used in scenarios, where the tooltip has to be started and stopped (reset) by the hosting application. This can often be the case, where the automatic activation/deactivation of the tooltip, which is triggered by the MouseEnter- and MouseLeave-events of a control, does not give the desired results.
An example for this kind of situations is the use of the tooltips with complex controls, such as grid- or tree-controls, where a finer granularity is desired. Many of this complex controls expose events to notify the hosting application that the mouse has entered or left a defined region or element inside of the control (e.g. grid-cells, tree-nodes etc.). This events are usually good places to start respectively reset the corresponding tooltip component.
This issues are discussed and illustrated with working examples in the section with the "Task-based tutorials" and - more specifically - in its subsection on "How to use ToolTips with grid-controls".
If the parameter-less version of Start() is used, it behaves exactly as if the mouse has entered the client-area of a control and - if there is tooltip content specified for the control, over which the cursor is hovering - this content will be displayed in the tooltip. Now, there are two ways, how tooltip content can be assigned to a control:
- The desired static content is assigned at design-time through the provided property (see "Provided properties"). In this case it doesn't make sense to start the tooltip-display in the control's MouseEnter event-handler. This activation is done automatically by the tooltip components and no additional programming is needed.
- The content is dynamically assigned at run-time. This is always the case, when the tooltip-content to be displayed can not be defined at design-time and has to be computed when the application is already executing.
There are two approaches to assign tooltip content to a control at runtime. One approach is to get access to the tooltip content through the Get...Tooltip()-function provided by each tooltip component (see "Provided properties" and the corresponding reference on the Get...Tooltip()-functions described in "Component-specific members". This approach is representatively shown for the SingleLineToolTip in Example 1.
The overloaded version Start(control) is declared with public visibilty, but it should not be used by hosting applications. It is used internally by the tooltip components and its use can lead to strange "special effects" such as tooltips with wrong content showing up over the wrong control or more then one tooltip popping-up over the same control. Therefore it is strongly recommended to avoid the use of this method.
Example 1
The following code starts and stops (resets) the tooltip for Button1 through the MouseEnter- and MouseLeave-events. This is a good way to display tooltip content that could not be assigned at design-time and needs to be updated each time the tooltip is displayed again:
'As soon as the mouse enters the control...
Private Sub Button1_MouseEnter(ByVal sender As Object, _ByVal e As System.EventArgs) Handles Button1.MouseEnter
'...we format the current universal time as a string...
Dim utcTime As String = Date.Now.ToUniversalTime.ToShortTimeString
'...and set it as new content for the SingleLineToolTip on Button1.
Me.SingleLineTip.GetSingleLineToolTip(Me.Button1) _
.Text = "UTC: " & utcTime
'Now the tooltip is ready to be displayed....
Me.SingleLineTip.Start
End Sub
'As soon as the mouse leaves the control...
Private Sub Button1_MouseLeave(ByVal sender As Object, _ByVal e As System.EventArgs) Handles Button1.MouseLeave
'...we should shut down the tooltip.
Me.SingleLineTip.Reset()
End Sub