Telerik UI for Windows Phone by Progress

RadToolTip is used via an easy to use API defined in the RadToolTipService class. It contains only attached properties that define how the tooltip will open and how it will look. Users have the ability to choose an open gesture, to provide a custom content template or to completely re-style or re-template the tooltip for a specific UI element.

Using the Attached Properties

In order to use RadToolTip users have to set attached properties to the visual parts that need to have a tooltip. This section demonstrates how to use all attached properties defined by the RadToolTipService class.

ToolTip

The ToolTip property is the entry point for using RadToolTip. If an object has a non-null set for the ToolTip property, this object will be displayed as accurately as possible when the tooltip is triggered by the show gesture. If the ToolTip is set to null, the tooltip functionality will for that element will be turned off. Here is an example:

CopyXAML
<Rectangle x:Name="rectangle"
           Fill="White"
           Width="100"
           Height="100"
           telerikPrimitives:RadToolTipService.ToolTip="This is a rectangle."/>
CopyC#
RadToolTipService.SetToolTip(this.rectangle, null);

Template

The Template property can be set in order to create a completely customized content template for the tooltip. The data context of this template will be the value of the ToolTip property set on the target element. Here is an example of a custom content template that visualizes a custom tool tip object:

CopyXAML
<Rectangle Width="100"
           Height="100"
           Fill="White">
    <telerikPrimitives:RadToolTipService.ToolTip>
        <local:ToolTipData Name="Rectangle"
                           Description="A rectangle UIElement that inherits from Shape."/>
    </telerikPrimitives:RadToolTipService.ToolTip>

    <telerikPrimitives:RadToolTipService.Template>
        <DataTemplate>
            <StackPanel>
                <TextBlock Text="{Binding Name}"/>
                <TextBlock Text="{Binding Description}"/>
            </StackPanel>
        </DataTemplate>
    </telerikPrimitives:RadToolTipService.Template>
</Rectangle>
CopyC#
public class ToolTipData
{
    public string Name
    {
        get;
        set;
    }

    public string Description
    {
        get;
        set;
    }
}

Style

RadToolTip can be completely restyled by creating a custom Style object and targeting the RadToolTip class. RadToolTip is a public class with public properties but has an internal constructor because it should be created and manipulated only by RadToolTipService. Below is an example of a custom tooltip style:

CopyXAML
<Rectangle Width="100"
           Height="100"
           Fill="White">
    <telerikPrimitives:RadToolTipService.Style>
        <Style TargetType="telerikPrimitives:RadToolTip">
            <Setter Property="Background"
                Value="Khaki"/>
            <Setter Property="Foreground"
                Value="Red"/>
            <Setter Property="OpenAnimation">
                <Setter.Value>
                    <telerikCore:RadFadeAnimation StartOpacity="0" 
                                              EndOpacity="1" 
                                              Duration="0:0:0.3"/>
                </Setter.Value>
            </Setter>
        </Style>
    </telerikPrimitives:RadToolTipService.Style>
</Rectangle>

ShowGesture

The ShowGesture property can be used customize the gesture that triggers the tooltip to open. Valid values are Tap, DoubleTap and Hold.

CopyXAML
<Rectangle Fill="White"
           Width="100"
           Height="100"
           telerikPrimitives:RadToolTipService.ShowGesture="Hold"/>

RelativeElement

The RelativeElement property allows users to show a tooltip over an arbitrary UI element but display data for a different element. This gives the flexibility to position the tooltip at different positions, not just over the associated element. Example:

CopyXAML
<Rectangle Fill="Orange"
           Width="100"
           Height="100"
           x:Name="AnotherRectangle"
           HorizontalAlignment="Right"/>

<Rectangle Fill="White"
           Width="100"
           Height="100"
           telerikPrimitives:RadToolTipService.ToolTip="This is the tooltip for the white rectangle."
           telerikPrimitives:RadToolTipService.RelativeElement="{Binding ElementName=AnotherRectangle}"/>

IsClosedAfterHold

The IsClosedAfterHold property is relevant only when the tooltip show gesture is set to Hold. When this is so, IsClsoedAfterHold determines if the tooltip will automatically close after the hold gesture finishes, that is, after the user lifts her finger off the tooltip owner.

Timeout

The Timeout property determines the time interval (TimeSpan) after which the tooltip will be closed automatically. For example if the tooltip is opened with a timeout of 3 seconds, after being displayed for 3 seconds it will be closed without intaraction from the user.

Methods

RadToolTipService exposes a method with an overload that allows the tooltip to be shown programmatically. This method is called Open.

The first overload accepts one argument and this is the owner of the tooltip. When it is called the tooltip for that element is shown with all settings that are specified with the attached properties.

CopyC#
RadToolTipService.Open(this.rectangle);

There is also another overload that allows users to show a completely new tooltip by specifying completely new settings and therefore overriding all attached properties of the tooltip owner. This overload can be called with a minimum of two arguments and these are the tooltip owner and the tooltip itself.

CopyC#
RadToolTipService.Open(this.rectangle, "A different tooltip");

Additionally, the tooltip may be closed programmatically by invoking the Close() method. It accepts no arguments and closes the tooltip if it is shown. Calling Close() when the tooltip is closed has no effect.

CopyC#
RadToolTipService.Close();

Events

RadToolTipService provides four events which encompass the tooltip's lifecycle. These are:

  • ToolTipOpening
  • ToolTipOpened
  • ToolTipClosing
  • ToolTipClosed
The only thing worth mentioning about the events is that the Closing and Opening events provide means to cancel the open or close operation via the event arguments' Cancel property.