C H A P T E R    9 Microsoft Office 97/Visual Basic Programmer's Guide

Microsoft Office Assistant


Contents

Microsoft Office 97 uses the Office Assistant to provide a single source for online Help. The Office Assistant can offer tips on the task you're performing, answer questions specific to the Office application you're using, and deliver messages from the application. You can use the Office Assistant in your own Visual Basic application to deliver information, guide the user through a task, and even run your procedures in response to the user's selecting a control in the Office Assistant balloon. You control the Office Assistant, the balloon, and all of the items inside the balloon by using the Assistant portion of the Microsoft Office object model.

Note   The Office Assistant isn't available in Microsoft Access 97 applications you build using the run­time version of Microsoft Access.

Using the Microsoft Office Assistant

In an Office application, the user chooses which Assistant he or she wants to see and then specifies the circumstances under which the Assistant is to be displayed. In a Visual Basic application, you can make the Assistant visible, animate it, move its window to a different location on the screen, and display balloons that contain various kinds of information and controls.

Note   You cannot record the Assistant's animation or balloon actions, and you cannot record options selected in the Office Assistant dialog box.

The first step in implementing the Assistant in your Visual Basic application is to determine how involved your user wants the Assistant to be in delivering information. On the Options tab in the Office Assistant dialog box, the user sets his or her preferences for the placement of the Assistant, the type of Help topics that the Assistant is to offer, and the Assistant's response to the F1 key.

You can use properties of the Assistant object to determine the choices the user has made regarding the Assistant. Each of the user's preferences corresponds to a property of the Assistant object. For example, the AssistWithHelp property returns True if the user has selected the Respond to F1 key option on the Options tab in the Office Assistant dialog box.

If the user's preferences indicate that he or she wants the Assistant's help, you can program your application to make full use of the Assistant by displaying text or prompts inside a balloon that would otherwise be displayed in a message box or input box, and you can make the Assistant available to offer tips that are automatically sent from the application.

There are 34 different animations available for the Assistant. You can program the Assistant to respond to a particular circumstance with a particular animation by assigning one of the MsoAnimationType constants to the Animation property of the Assistant object. Depending on the Assistant the user has chosen, setting the Animation property may or may not result in any obvious animation. However, the MsoAnimationType constants are valid for all Assistants.

Note   You can assign one of the msoAminationType constants to the Balloon object as well. If you do this, the Assistant will perform the specified animation when the balloon is displayed. For more information, see "Using the Microsoft Office Assistant Balloon" later in this chapter.

The following example has the Assistant display a message if the Display alerts option is selected on the Options tab in the Office Assistant dialog box, or displays a standard message box if this option isn't selected. The Assistant is animated when it displays the message, and after the user closes the balloon, the Visible property of the Assistant is set to the value it had before the example ran.

hdng = "Empty field"
msg = "You need to enter a part number " _
       & "before you can proceed."
If Assistant.AssistWithAlerts = True Then
    With Assistant
    userState = .Visible
    .Visible = True
    Set bln = .NewBalloon
    With bln
       .Mode = msoModeModal
       .Button = msoButtonSetOK
       .Heading = hdng
       .Text = msg
       .Animation = msoAnimationGetAttentionMinor
       ret = .Show
    End With
   .Visible = userState
   End With
Else
   ret = MsgBox(msg, vbOKOnly, hdng)
End If

Using the Microsoft Office Assistant Balloon

The Balloon object is the most important part of the Office Assistant object model. You use balloons to deliver messages to your user or to request information from the user that you can use in your Visual Basic application. There are several types of balloons, each of which can contain labels and check boxes, as well as certain types of graphics. Only one balloon can be visible at a time, but you can create multiple Balloon objects and store them in variables for use at any time, and you can reuse any Balloon object by resetting its properties.

Creating Balloons

To create a balloon, you use the NewBalloon property of the Assistant object. The balloon that's returned by the property is blank. Use the Mode property to specify how you want the balloon to respond to the user's actions. To add a heading to the balloon, you use the Heading property, and to add text to the body of the balloon, you use the Text property. You can also add controls or graphics if you want. Finally, you use the Show method to display the balloon you've designed. The Show method displays the balloon as it exists (that is, as you've designed it) at that point in time; therefore, it's important to use the Show method after you've set or changed any balloon properties.

There are several types of balloons you can display; the type of balloon a Balloon object represents is determined by the Mode property, which you can set to one of the following MsoModeType constants: msoModeModal, msoModeAutoDown, or msoModeModeless.

A modal balloon (msoModeModal) demands the user's complete attention because keyboard or mouse activity is restricted to the balloon while the balloon is displayed. A modal balloon is best used for alerts or critical messages. The following example uses a modal balloon to prompt the user to confirm whether the active file should be closed without changes being saved. You can use the value of the button that's clicked (which is assigned to ret) to determine whether or not the event should continue. You can use this example as part of an event procedure that runs whenever a file is closed, or you can use it in a series of balloons leading the user through a process.

Set bln = Assistant.NewBalloon
With bln
    .Mode = msoBalloonModal
   .Heading = "Warning"
   .Text = "If you close this file without saving it, " _
       & "this macro cannot proceed. Close without saving?"
   .Button = msoButtonSetOkCancel
   ret = .Show
End With

An AutoDown balloon (msoModeAutoDown) is dismissed when the user clicks or types anywhere in the application. This type of balloon is best used for quick messages that aren't critical to the task at hand. The following example displays a tip for using a custom dialog box (the code can run in an event procedure for a dialog box control). Because the balloon is an AutoDown balloon, the message disappears as soon as the user clicks anywhere in the dialog box.

hdng = "Selecting a data source"
msg = "In this dialog box, you can specify a workbook " _
       & "or an external table of data to use for input." _
       & "If you use external data, it must contain delimited" _
       & "fields, rather than fixed-length fields."
With Assistant
    Set bln = .NewBalloon
    With bln
       .Mode = msoModeAutoDown
       .Button = msoButtonSetOK
       .Heading = hdng
       .Text = msg
       ret = .Show
    End With
End With

While a modeless balloon (msoModeModeless) is displayed, the user can complete a task in the application; that is, the user can type in the document and use menu and toolbar commands. You can use a modeless balloon to display procedures or tips for using your Visual Basic application, for the benefit of the user.

When the user clicks a control or button in a modeless balloon, a callback procedure is called. Your Visual Basic application must contain a procedure (whose name is assigned to the Callback property) that responds to the action the user takes. For example, if the user clicks the OK button, he or she wants to dismiss the modeless balloon; the callback procedure should respond accordingly by applying the Close method to the balloon. The following example displays a series of steps for the user to follow while the balloon remains displayed. The callback procedure closes the balloon when the user clicks OK.

Sub DisplaySteps()
Set bln = Assistant.NewBalloon
With bln
    .Mode = msoModeModeless
   .Callback = "StepsCallback"
   .BalloonType = msoBalloonTypeNumbers
   .Button = msoButtonSetOK
   .Heading = "To create a new report"
   .Labels(1).Text = "On the File menu, click New Report."
   .Labels(2).Text = "In the New Report dialog box, select the period " _
       & "(monthly, quarterly, or yearly)."
   .Labels(3).Text = "Click the Create button."
   ret = .Show
End With
End Sub

Sub
StepsCallback(bln As Balloon, btn As Long, priv As Long)
   bln.Close
End Sub

For more information about the Callback property and callback procedures, see "Using Callback Procedures" later in this chapter.

Managing Multiple Balloons

There isn't a collection of Balloon objects. Instead, you can create an array to store more than one balloon variable. You can create and store empty balloons, or you can create and store balloons complete with heading, text, and controls. The following example creates an array and adds three Balloon objects, with numbered headings, to the array.

Dim myBlnArray(3) as Balloon

With Assistant
    For i = 1 To 3
       Set myBlnArray(i) = .NewBalloon
       myBlnArray(i).Heading = i
   Next
End With

The following example displays the second balloon in the array.

myBlnArray(2).Show

Alternatively, you can set a separate object variable for each balloon you create; this way, you can reference the variable at any time. If you declare balloon variables globally, you can call them from any procedure in your program.

Adding Text and Controls to Balloons

Every balloon can contain a heading and text. By default, a balloon contains an OK button at the bottom, but it can also contain any of a variety of button combinations, or no buttons at all (although showing no buttons requires a modeless balloon with button labels; for information about button labels, see "Adding and Modifying Labels" later in this section). To provide emphasis or greater detail, you can add an icon to the heading, and you can add bitmaps, Windows metafiles, or Macintosh pict files anywhere text can appear in the balloon. Also, every balloon can contain as many as five numbered, bulleted, or button labels, and as many as five check boxes; you can use these elements to deliver or return detailed information from the user.

Setting the Heading and Text

The most basic elements of a balloon are the heading and the simple text that appear at the top of the balloon. Both the heading and text are optional; you can display a balloon that contains neither one. You set the heading and text by using the Heading and Text properties. You specify which buttons to display at the bottom of the balloon by setting the Button property to one of the MsoButtonSetType constants. The following example displays a simple message in a modal balloon.

Set bln = Assistant.NewBalloon
With bln
    .Mode = msoModeModal
   .Button = msoButtonSetYesNo
   .Heading = "Empty file"
   .Text = "The file you specified does not contain any data. Quit now?"
    ret = .Show
End With

The Show method returns a value that indicates which button was clicked to close the balloon. You can use the return value to make a decision about what action to take next. In the preceding example, if the Show method set the value of ret to msoBalloonButtonYes, the example can proceed to quit the running macro as the user requested.

Adding Icons and Bitmaps

To get the user's attention, you can add icons and bitmaps to Office Assistant balloons. Icons are displayed at the top of the balloon, to the left of the heading text, whereas bitmaps can be displayed anywhere in the balloon. To add an icon, assign one of the msoIconType constants to the Icon property of the Balloon object. The following example displays a simple alert balloon.

Set bln = Assistant.NewBalloon
With bln
    .Mode = msoModeModal
   .Heading = "Attention Please"
   .Text = "That command is not available now."
   .Icon = msoIconAlert
   .Show
End With

To add a Windows or Macintosh bitmap to a balloon, specify the type (.bmp) and the path of the bitmap. You can insert a bitmap can be inserted the balloon text, the balloon heading, or a label. You can also include braces around text if you format the text as shown in the following example. This example inserts a Windows bitmap file into the text of a balloon; this will produce a balloon error if Circles.bmp doesn't exist in the specified folder. For information about handling balloon errors, see "BalloonError Property" in Help.

myBmp = "{bmp c:\Windows\circles.bmp}"
myText1 = "This text is before the picture,"
myText2 = " and this text is after the picture."
myText3 = " {{This is text in braces.}"
Set bln = Assistant.NewBalloon
With bln
    .Mode = msoModeAutoDown
    .Heading = "Displaying a Bitmap."
    .Text = myText1 & myBmp & myText2 & myText3
    .Show
End With

You can specify a graphic you want displayed by using the following syntax: {type location sizing_factor}. In this syntax, type indicates the type of graphic that will be added to the balloon, location should be the complete path and can be a network location (\\server\folder\picture.bmp) or a local hard drive (C:\folder\picture.bmp), and sizing_factor represents the width (in characters) of the Windows metafile or the Macintosh picture (it has no effect on a .bmp file). If proportional fonts are being used, sizing_factor represents the average character width. You can use sizing_factor to reduce a large graphic to fit your balloon, or to enlarge a small graphic to enhance the image. The following example reduces the displayed size of the Windows metafile Clouds.wmf to a 20­character width and inserts it as the heading in a balloon.

Set myBln = Assistant.NewBalloon
myWmf = "{wmf c:\graphics\clouds.wmf 20}"
With myBln
    .Mode = msoModeAutoDown
   .Heading = myWmf
    .Text = "Balloon with .wmf in heading"
   .Show
End With

Adding and Modifying Labels

There are three types of labels you can add to a balloon: numbered labels, bulleted labels, and button labels. You can add as many as five labels to a given balloon, but they must all be of the same type; you cannot mix numbers, bullets, and buttons in the same balloon. To indicate which type of labels you want, you set the BalloonType property of a balloon to one of the following MsoBalloonType constants: msoBalloonTypeNumbers, msoBalloonTypeBullets, or msoBalloonTypeButtons. To return a BalloonLabel object that represents one of the numbered, bulleted, or button labels, you use Labels(index), where index is a number from 1 through 5. You set the Text property of the BalloonLabel object to specify the label's text.

Note   If you try to reference a label greater than 5, an error occurs.

You can use numbered labels and bulleted labels to present related information in a meaningful way. That is, rather than creating a complex string to assign the Text property of a balloon, you can assign simple strings to the Text property of as many as five numbers or bullets. The following example displays a modal balloon with a list of troubleshooting suggestions for a macro.

Set bln = Assistant.NewBalloon
With bln
    .Mode = msoBalloonModal
    .Button = msoButtonSetOK
    .BalloonType = msoBalloonTypeBullets
    .Heading = "Tips for locating output"
    .Text = "If you cannot locate the output log, consider the following:"
    .Labels(1).Text = "Check the current folder name in the Save dialog box."
    .Labels(2).Text = "Make sure you type the file name correctly."
    .Labels(3).Text = "If you saw the Empty File message, no log was created."
   ret = .Show
End With

You use button labels to let the user make choose from a list of two or more possible actions. Using the return value of the Show property (in a modal or AutoDown balloon) or the second argument passed to the callback procedure (in a modeless balloon), you can determine which button label was clicked and take the appropriate action.

The following example displays a list of three button labels. The variable x is set to the return value of the Show method, which will be 1, 2 or 3, depending on which button the user clicks (there's no OK button). In the example, a simple message box displays the value of the variable x, but you can pass the value to another procedure, or you can use the value in a Select Case statement.

Set b = Assistant.NewBalloon
With b
    .Mode = msoModeModal
    .Button = msoButtonSetNone
    .Heading = "Balloon heading"
    .Text = "Select one of these things:"
    .Labels(1).Text = "Choice One"
    .Labels(2).Text = "Choice Two"
    .Labels(3).Text = "Choice Three"
    x = .Show
End With
MsgBox x

The following example prompts the user to select either a network printer or a local printer before a document is printed. The user can work in the application (because the balloon is a modeless balloon) but is reminded that printing cannot occur until a printer is selected. The ProcessPrinter procedure would determine which button label was clicked, run the appropriate statements, and then close the balloon.
Set bln = Assistant.NewBalloon
With bln
    .Mode = msoModeModeless
    .Button = msoButtonSetNone
    .Heading = "Select A Printer"
    .Text = "You must select a printer before printing."
    .Icon = msoIconAlert
    .Labels(1).Text = "Local printer"
    .Labels(2).Text = "Network printer"
    .Callback = "ProcessPrinter"
    ret = .Show
End With

For more information about the Callback property of a modeless balloon, see "Using Callback Procedures" later in this section.

Adding and Modifying Check Boxes

You use check boxes to let the user select one or more items in a list. By default, each balloon contains five check boxes when it's created; however, you must set the Text property for each check box you want to be visible. To return a BalloonCheckbox object that represents one of the check boxes, you use Checkboxes(index), where index is a number from 1 through 5.

Note   If you try to reference a check box by using a number greater than 5, an error occurs.

If you display a balloon that contains check boxes, the user can select one or more of the check boxes before clicking a button. You can then use the value of each check box (indicated by the Checked property) to control subsequent statements or branching structures in your code. The following example displays a balloon in which the user can select one, two, or three check boxes, or none. A second balloon confirms which check boxes were selected.

Set a = Assistant.NewBalloon
Set b = Assistant.NewBalloon
With a
    .Mode = msoModeModal
    .Button = msoButtonSetOkCancel
    .Heading = "Print Regional Sales Data"
    .Text = "Select the region(s) you want to print."
    For i = 1 To 3
        .CheckBoxes(i).Text = "Region " & i
    Next
End With
retA = a.Show
If retA = msoBalloonButtonOK Then
    s = ""
    For i = 1 To 3
       If a.CheckBoxes(i).Checked = True Then
            If s = "" Then
                s = CStr(i)
            Else 
                s = s & ", " & CStr(i)
            End If
      End If
    Next
    With b
       .Mode = msoModeModal
       .Heading = "Print Regional Sales Data"
       If s <> "" Then
             .Button = msoButtonSetYesNo
             .Text = "Please confirm that you want to print " & _
                "data for the following region(s): " & s
       Else
            .Button = msoButtonSetOK
            .Text = "You did not select any regions to print."
       End If
       retB = .Show
    End With
End If

Using Callback Procedures

If you create a modeless balloon, you must assign to the Callback property the name of a callback procedure. A callback procedure must be written to receive three arguments: the first argument is a Balloon object that represents the balloon that called the procedure; the second argument is a number that indicates the index number or constant of the button label or button that was clicked; and the third argument is a number that's used by wizards to control the Assistant (unless you're developing a custom wizard, you can ignore the third argument). The following example shows a valid declaration for a callback procedure. Note that you can use any argument names you prefer in your declarations.

Sub MyCallback(bln As Balloon, btn As Long, priv As Long)

Note   You must assign the Callback property a string that indicates the correct scope of the callback procedure in relation to the code you're writing, just as if you were writing a statement to call the procedure directly. For example, if you're writing code in a module and the callback procedure is in a Microsoft Excel worksheet (Sheet1) in the same project, you would set the Callback property to "Sheet1.MyCallback."

The following example displays a balloon that contains the names of three printers. The callback procedure runs the appropriate printer­specific code and then closes the balloon.

Sub TestCallback()
Set bln = Assistant.NewBalloon
With bln
   .Mode = msoModeModeless
   .Callback = "ProcessPrinter"
   .Button = msoButtonSetNone
   .BalloonType = msoBalloonTypeButtons
   .Heading = "Select a Printer"
   .Labels(1).Text = "Network Printer"
   .Labels(2).Text = "Local Printer"
   .Labels(3).Text = "Local Color Printer"
   .Show
End With
End Sub

Sub
ProcessPrinter(bln As Balloon, ibtn As Long, _
       iPriv As Long)
    Assistant.Animation = msoAnimationPrinting
   Select Case ibtn
    Case 1
       ' Insert printer-specific code
   Case 2
       ' Insert printer-specific code
   Case 3
       ' Insert printer-specific code
   End Select
    bln.Close
End Sub