| Microsoft Office 2000/Visual Basic Programmer's Guide | |
Programming the Assistant is a matter of setting an object variable to the Assistant object and then accessing the properties and methods you need 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 may 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. For an example of how to use a class module to preserve Assistant settings and restore them when your code is finished, see the TestSaveAssistProperties procedure in the modAssistantCode module in AssistantSamples.dot in the ODETools\V9\Samples\OPG\Samples\CH06 subfolder on the Office 2000 Developer CD-ROM.
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 Microsoft Office 2000, 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
The SimpleAnimation procedure is available in the modAssistantCode module in AssistantSamples.dot in the ODETools\V9\Samples\OPG\Samples\CH06 subfolder on the Office 2000 Developer CD-ROM.
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 needed in order to give one animation time to finish before another animation begins. To see the Wait procedure and the custom class object it uses, see the modAssistantCode module in AssistantSamples.dot in the ODETools\V9\Samples\OPG\Samples\CH06 subfolder on the Office 2000 Developer CD-ROM. For more information about custom class objects, see Chapter 9, "Custom Classes and Objects."
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. You can also create your own character files by using the Microsoft Agent ActiveX control's character editor. For more information about the Agent control and the character editor, see the Microsoft Agent Web site at http://www.microsoft.com/intdev/agent.
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
The ChangeCharacter procedure is available in the modAssistantCode module in AssistantSamples.dot in the ODETools\V9\Samples\OPG\Samples\CH06 subfolder on the Office 2000 Developer CD-ROM.
Note If you are using a character supplied by Office, you don't need 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 can't 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.