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 20character
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
printerspecific 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