Programming the Office Assistant

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Programming the Assistant is a matter of setting an object variable to the Assistant object and then accessing the properties and methods you must have to make the assistant do what you want. You can make the Assistant visible, move it to different locations on the screen, specify the animation you want to run, and display Assistant balloons containing text and controls.

One important thing to remember when you programmatically manipulate the properties of the Assistant is that the user might have set various Assistant properties that you should preserve. Any time you manipulate the Assistant, you should save the properties that existed before you began and then restore those properties when you are finished. For example, if the user normally has the Assistant turned off and you programmatically turn it on to perform some task, you should make sure you turn it off when you are finished using it.

In previous versions of Microsoft® Office, the Assistant is either visible and available or not visible and unavailable, but the Assistant can never be completely turned off. In Office XP, the Assistant has an On property that affects whether the Assistant is available at all.

You use the Assistant's On and Visible properties to determine its initial state. When the On property is set to False, the Visible property is False and any attempt to programmatically manipulate the Assistant (except for a call to the Assistant's Help method) is ignored and no error is raised. When the On property is set to True, the Assistant will be either visible or hidden depending on the Visible property's setting.

Note   When the On property's value is changed from False to True, the Visible property is set to True.

The following example demonstrates how to save the initial settings for the On and Visible properties, how to make the Assistant visible, and a simple animation technique:

Sub SimpleAnimation()
   ' This procedure shows simple Assistant animation
   ' techniques. It calls the Wait procedure between
   ' animations to give the animation time to complete.
   
   Dim blnAssistantVisible       As Boolean
   Dim blnAssistantOn            As Boolean
   
   With Application.Assistant
      blnAssistantOn = .On
      blnAssistantVisible = .Visible
   
      If Not blnAssistantOn Then
         .On = True
      ElseIf Not blnAssistantVisible Then
         .Visible = True
      End If
      .Animation = msoAnimationCheckingSomething
      Call Wait(5000)
      .Animation = msoAnimationEmptyTrash
      Call Wait(7000)
      .Animation = msoAnimationCharacterSuccessMajor
      Call Wait(5000)
      If (Not blnAssistantOn) Or (Not blnAssistantVisible) Then
         .On = blnAssistantOn
         .Visible = blnAssistantVisible
      End If
   End With
End Sub

Note   The Wait procedure used in the previous example is a subroutine that uses a custom class object to wait the number of milliseconds specified in the procedure's argument. When you are stringing Assistant animations together, this procedure is required to give one animation time to finish before another animation begins.

The Assistant's FileName property specifies the animated character that is displayed when the Assistant is visible. Character files use an ".acs" extension, and several characters are supplied with Office. In addition, you can create your own character files by using the Microsoft Agent ActiveX control's character editor.

Characters you create should be stored in the host application's folder or in the C:\Windows\Application Data\Microsoft\Office\Actors subfolder; if multiple users work on the same machine and user profiles have been set up on the machine, store your characters in the host application's folder or in the C:\Windows\Profiles\UserName\Application Data\Microsoft\Office\Actors subfolder. For more information about setting up user profiles, search the Microsoft® Windows® Help index for "user profiles."

You specify which character is displayed by setting the Assistant's FileName property to the name of the .acs file for the character you want to use. For example, the following procedure changes the character to the name of the character specified in the strCharName argument:

Function ChangeCharacter(strCharName As String) As Integer
   ' This procedure changes the existing Assistant
   ' character to the character specified in the
   ' strCharName argument. The procedure's return
   ' values are set by using constants defined in the
   ' Declarations section of this module.
   
   With Application.Assistant
      If UCase(.FileName) = UCase(strCharName) Then
         ChangeCharacter = ASST_CHAR_SAMECHAR
         Exit Function
      End If
      .FileName = strCharName
      ChangeCharacter = ASST_CHAR_CHANGED
   End With
End Function

Note   If you are using a character supplied by Office, you are not required to include the full path to the .acs file you want to use. When you set the FileName property, Visual Basic for Applications (VBA) will look for the file in the host application's folder and then in the C:\Windows\Application Data\Microsoft\Office\Actors subfolder and, if it exists, in the C:\Windows\Profiles\UserName\Application Data\Microsoft\Office\Actors subfolder. If your character files are located somewhere other than the three locations discussed here, you must set the FileName property by using the full path to the file. If the file cannot be found, a message is displayed. If the user clicks OK, the same file-search sequence is executed again. If the user clicks Cancel, the attempt to change the FileName property is ignored and no error occurs.

See Also

Working with Shared Office Components | Working with the Office Assistant | Microsoft Agent ActiveX Control vs. the Office Assistant | Working with Balloon Objects | Using Balloon Controls | Modeless Balloons and the Callback Property | Custom Classes and Objects