C H A P T E R 9 | Microsoft Office 97/Visual Basic Programmer's Guide |
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
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.
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.
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.
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.
The following example displays the second balloon in the array.
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.
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.
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.
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 20character
width and inserts it as the heading in a balloon.
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.
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.
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.
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.
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
printerspecific code and then closes the balloon.
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
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
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
Dim myBlnArray(3) as Balloon
With Assistant
For i = 1 To 3
Set myBlnArray(i) = .NewBalloon
myBlnArray(i).Heading = i
Next
End With
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.
myBlnArray(2).Show
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
Set bln = Assistant.NewBalloon
With bln
.Mode = msoModeModal
.Heading = "Attention Please"
.Text = "That command is not available now."
.Icon = msoIconAlert
.Show
End With
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
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
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
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 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
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
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
Sub MyCallback(bln As Balloon, btn As Long, priv As Long)
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