Task-based Tutorials - How to use dynamically created Animations with AnimationToolTips

This article shows, how ToolTipsFactory Animations can be dynamically created and how they can be used with the ToolTipsFactory AnimationToolTip component. This article is based on the article on "How to use dynamically created Images with ImageToolTips", because it is going to show, how the same techniques used to dynamically create images for the ImageToolTips, can be applied to the AnimationToolTip component. The sample-application used to demonstrate the topics discussed in this article is actually a derived version of the application used in the article mentioned above. With only small changes to this original sample application and an additional function, we are going to show, how easy an complete ToolTipsFactory movie-clip (Animation) can be rendered and assigned to the tooltip of a control.

Also for the AnimationToolTip component, it makes no difference, if the Animation to be displayed in the ToolTip of a control is loaded from file at design-time (see the example in the "Quick-start tutorial - Part IV"), loaded from file at run-time or dynamically created by the application itself at run-time. The latter approach opens the possibility for application developers, to create any kind of animated content to be assigned to the AnimationToolTip of a control. This can be dynamically rendered rotating views of 3D-models, periodical snapshots (still images) automatically taken by a camera over a long period of time, dynamically assembled into an Animation, or just some dynamically created animated strings or symbols. 

Exactly as the "DynamicImageToolTip1" sample-application, this sample-application renders a given text in a way, which is not supported by the Single- and MultiLineToolTips, by drawing the text directly on a new empty image. But instead of creating only one single image to be displayed by an ImageToolTip, this sample-application lets the given text scroll over the "canvas" and renders an image for each position of the scrolling text. These images are then combined to a ToolTipsFactory Animation, which can be played by the AnimationToolTip component. 

The source-code and the corresponding Visual Studio project for this sample can be found in the "<ToolTipsFactoryHomeDir>.\Samples\DynamicAnimationToolTip1"-directory.

The front-end of this sample-application and its handling are identical to the one of the "DynamicImageToolTip1" application described in the corresponding article. 

How new content (in this case an Animation) is assigned to the tooltip of a specific control has been extensively covered in other sections of the ToolTipsFactory documentation. The only difference in the sample is that the Animation is not loaded from a file (or from the application resources) but generated at run-time by a function. 

The central part of the application, where all this happens is listed below

Private Sub cmdApply_Click(ByVal sender As System.Object, _ 
ByVal e As System.EventArgs) _ 
Handles cmdApply.Click

    'This procedure calls a function to render a new
    'scrolling text animation, based on the current settings
    'of the front-end form and assigns this animation to
    'the provided tooltip property of the control, which
    'should display the new animation as a tooltip.

    'get the desired tooltip-width from the corresponding field.
    Dim width As Integer = CInt(Me.txtWidth.Text)

    'Because the text will be rendered as Sine-curve, the height
'the resulting frame-images must be a multiple of the selected
Dim height As Integer = mSelectedFont.Size * 3

    'This defines a nice linear gradient brush....
Dim br As Brush 
    br =
New LinearGradientBrush(New RectangleF(0, 0, width, height), _
                                 Color.Blue, Color.Red, _

    'This is where the new animation is created and assigned
    'to the tooltip-property of Panel1...
Dim newAni As Animation
    newAni =
BuildAnimatedString(txtTooltipText.Text, _
                                 mSelectedFont, br, _
                                 width, height)
    AnimationTT.GetAnimationToolTip(Panel1).AnimatedSymbol = newAni


    'By assigning the known width of the Animation
'as an Override-value for the AnimationToolTip of Panel1, we
'make sure, that the Animation is not scaled down to the
    'DefaultWidth specified for AnimationTT at the
AnimationTT.GetAnimationToolTip(Panel1).Override.DefaultWidth = width

End Sub

Listing 1

The code in Listing 1 is executed with every click on the Apply-button. The important line is, where the function-call occurs, to create the new Animation based on the current values of the fields in Form1: The called function BuildAnimatedString() returns a new Animation with the text (txtTooltipText.Text) rendered - and scrolled from right to left - along a sinoidal path with the selected font (mSelectedFont) and brush (br).

The resulting Animation is then directly assigned as content for the AnimationToolTip of Panel1. The final - but important - step is, to ensure that the DefaultWidth  specified at the component-level for AnimationTT is overridden with the width used to create the animation-frames, if you don't want the movie-clip to be scaled up or down to the value defined as DefaultWidth

As can be seen from the screen-recording of the sample-application, the drawn text is really scrolling along a sinoidal path. This scrolling-effect is generated in the function BuildAnimatedString(), which controls the scrolling of the string and the generation of the images for each step of the scrolling used to create the Animation.

The single images for each new position or state of the scrolled text are still rendered by the DrawTextAsWave()-function, as it is used by the "DynamicImageToolTip1" application. Because the DrawTextAsWave()-function has already been discussed in the mentioned article, we only need to have a closer look at function that assembles the new Animation:  

Private Function BuildAnimatedString(ByVal text As String, _
ByVal font As Font, _
ByVal brush As Brush, _
ByVal width As Integer, _
ByVal height As Integer) As Animation

    'This function creates a ToolTipsFactory Animation
    '(movie-clip). The text is
scrolled through the image
    'from right to left one character/frame.

'Create a new empty Animation-object
Dim Clip As Animation = New Animation()
'Append some blanks to the text to be scrolled in the animation
Dim orgtext = text & " "
'We need to know the length of the text to be scrolled.
Dim txtlen As Integer = orgtext.Length
'This variable will hold the string for the currently processed frame.
Dim anitext As String
'We need an AnimationFrame variable to assign created frames.
Dim frame As AnimationFrame
'This is the cursor we need to make the string scroll.
Dim i As Integer

    'We let i move through the text and for each step we
'split it into a left and a right string. These left and
'right substrings are then exchanged and concatenated again.
'The resulting string (anistring) is then used to render
'an image of this string mapped onto a sine-wave.
'The resulting image is then used to create an Animation-frame.
For i = 0 To txtlen - 1
     Dim tmptxt_left, tmptxt_right As String
     'get left part of the string (the letters scrolled out
     'of the image on the left side.
     tmptxt_left = orgtext.Substring(0, i)
     'get right part of the string (the letters scrolled
     'into the image from the right side.
     tmptxt_right = orgtext.Substring(i, txtlen - i - 1)
     'concatenate the substrings in reversed order
     anitext = tmptxt_right & tmptxt_left

     'This is where the new frame-image is rendered.
     Dim img As Image
       img =
Me.DrawTextAsWave(anitext, mSelectedFont, _
                               brush, width, height)

      'Create a new AnimationFrame from this image...
       frame = New AnimationFrame(img)
   '...and define the time, the frame should be visible
      'in the movie.

   frame.DisplayTime = 50

      'finally, the new frame is appended to the Animation.


    'The Animation is complete and can be returned...

    Return Clip

End Function


Listing 2

The code in Listing 2 shows, how easy it is to generate nice animated effects for the AnimationTooltip with only a few lines of code.

In the sample-project, the BackColor is set to Color.Transparent, in order to get the scrolling text floating on top (see screen-recording above). Without any additional coding, just by setting Background=TextureTakeCenter and loading an image as tooltip BackTexture, the tooltip could be changed to look completely different, but still playing the same scrolling text: