Displaying a Custom Balloon

In the following example you'll create a balloon in the Assistant to display Help information. The balloon's function is very similar to that of the MsgBox function built into the Visual Basic for Applications language. This example also explains the difference between the procedure you create here and the one that displays a functionally equivalent message box using the MsgBox function.

  1. Start any Office application, open the Visual Basic Editor, and insert a new code module.

  2. In the Properties window, change the name of the newly added code module to modAssistant.

  3. Create a new procedure in the code module modAssistant by typing Sub DisplayOfficeAssistant.

  4. Type the following declaration as the first line:

    5. Dim bln As Office.Balloon

    You declare the variable bln as type Office.Balloon, and in the following step you'll set it to a new Balloon object returned by the NewBalloon method. When you typed the word Office and then typed a period (.), you should have seen the Auto List Members drop-down list display the Balloon item. By default, Microsoft Word, Microsoft Excel, Microsoft PowerPoint, and Microsoft Outlook automatically reference the Microsoft Office 9.0 Object Library, which contains the Assistant and Balloon objects. In Microsoft Access, you need to set a Reference to the Microsoft Office 9.0 Object Library using the References dialog box in the Visual Basic Editor.

NOTE
If you didn't see the Auto List Members drop-down list, you may not have the Office Object Library referenced, or the Auto List Members feature may not be selected in the Options dialog box. To reference the Office Object Library, on the Tools menu in the Editor, click References, and then select the check box next to the Microsoft Office 9.0 Object Library item in the list. To turn on the Auto List Members feature, on the Tools menu, click Options, and then select Auto List Members on the Editor tab.

  1. To assign the object variable bln to a balloon object, type the following Set statement:

    2. Set bln = Assistant.NewBalloon

    The NewBalloon method of the Assistant object returns a Balloon object, which is assigned to the bln object variable.

  2. After the Set statement, type the following With…End block:

    3. With bln
End With

  3. Within the With…End block, type the following lines to set the Heading and Text properties of the newly created Assistant Balloon object:

    4. .Heading = "File Search"
.Text = "To conduct a file search, " & _
    "follow the steps outlined below."

    You use the Heading property for the bold text displayed at the top of the balloon. The Text property is assigned to text that's displayed just below the heading, but isn't bold.

  4. To set the type of buttons that will appear at the bottom of the balloon, type the following before the End With statement added in step 6:

    5. .Button = msoButtonSetOK

    You can set the Button property to a wide range of predefined buttons and combinations of buttons. They include OK, Cancel, Yes, No, Next, Previous, and others. In this case, you set the Button property to the OK button. (To see the full list of button combinations you can set to the Button property, scroll down the Auto List Members drop-down list that you see after you type the equal sign (=), or refer to the Balloon Elements table at the beginning of this chapter.)

  5. After setting the Button property, type the following before the End With statement to set the balloon mode:

    6. .Mode = msoModeModal

    The Assistant's balloon can be in one of three modes:

    When you specify that the balloon is Modeless (by setting the Mode property to msoModeModeless), you must set a value for the Callback property. The Callback property value is the name of a procedure that's called just after you close the balloon. By default, if you don't explicitly set the Mode property, msoModeModal is used.

IMPORTANT
You can't create a modeless balloon with a COM add-in. If you create a COM add-in, which is described in Chapters 13 and 14, you can display only a modal balloon that requires the user to close it before continuing to work with the Office application or the COM add-in form.

  1. To display the balloon on the screen, type the following Show method before the End With statement:

    2. .Show

  2. Place the cursor in the DisplayOfficeAssistant procedure and press F5 to run it. You'll see the Assistant along with a balloon containing a heading, text, and a button.

    3. The complete procedure for displaying this custom balloon is as follows:

    Sub DisplayOfficeAssistant()
    Dim bln As Office.Balloon
    Set bln = Assistant.NewBalloon
    With bln
        .Heading = "File Search"
        .Text = "To conduct a file search, " & _
            "follow the steps outlined below."
        .Button = msoButtonSetOK
        .Mode = msoModeModal
        .Show
    End With
End Sub

    The procedure for displaying a functionally equivalent message box is as follows:

    Sub DisplayMessageBox()
    Dim sHeading As String, sText As String
    sHeading = "File Search"
    sText = "To conduct a file search, " & _
        "follow the steps outlined below."
    MsgBox Prompt:=sText, Buttons:=vbOKOnly, Title:=sHeading
End Sub

To make the message box code easier to read, you declare the variables sHeading and sText as being assigned to the Title and Prompt parameters, respectively, of the MsgBox function. The Heading, Text, and Button properties of the Assistant's Balloon object are equivalent to the MsgBox function's Title, Prompt, and Buttons parameters. Setting the Icon property of the Balloon object, described later in this chapter, is equivalent to assigning a value like vbInformation, vbCritical, vbExclamation, or vbQuestion to the Buttons parameter of the MsgBox function. The Buttons parameter allows you to set both the button set and icon displayed in the message box:

Buttons:=vbOKOnly + vbInformation

On the other hand, in the Assistant's Balloon object, you specify the button set and icon separately, with two different properties (Button and Icon).

Determine Whether to Display the Assistant or a Message Box

You can use the combination of the Assistant object's Visible and On properties to determine if the Assistant is both turned on and visible. Office uses the Assistant's visible and on state in order to determine whether an alert should be displayed through the Assistant's balloon or a message box.

A user's right-clicking the Assistant, clicking Options from the shortcut menu, or clearing "Use The Office Assistant" on the Options tab can turn off the Assistant. If the user turns it off, clicking the "Show the Office Assistant" command on the Help menu of any Office application will turn it back on. To hide the Assistant but not turn it off, the user clicks the "Hide the Office Assistant" command on the Help menu.

The following procedure allows you to mimic this Office functionality in your Visual Basic programs by using an If…Then…Else condition block to determine whether you should have the program display a given message with the Assistant or a message box. (Using a Boolean to store the state of the Assistant may be useful, but you should note that the state of the Assistant may change if the user decides to turn the Assistant on or make it visible.) Your code might look similar to the following:

Sub CheckIfAssistantIsVisible()
    If Assistant.On And Assistant.Visible Then
        ' Display Office Assistant
    Else
        ' Display message box
    End If
End Sub

Using a Generic Function to Display Messages

An efficient way to structure your code is to create a single custom function that displays messages to the user, whether it's through the Assistant's balloon or the MsgBox function. Every time you need to display a message, your code calls the generic function, which then determines how the message is displayed. For example, the following TestDisplay-OKMessage procedure calls the custom function Display-OKMessage.

Sub TestDisplayOKMessage()
    DisplayOKMessage "TIP", "Use a generic function."
End Sub

Function DisplayOKMessage(sHeading As String, _
      sText As String)
    If Assistant.On And Assistant.Visible Then
        Dim bln As Office.Balloon
        Set bln = Assistant.NewBalloon
        With bln
            .Heading = sHeading
            .Text = sText
            .Button = msoButtonSetOK
            .Show
        End With
    Else
        MsgBox Prompt:=sText, Buttons:=vbOKOnly, _
             Title:=sHeading
    End If
End Function

You can call the DisplayOKMessage function anywhere in your code without duplicating the functionality of checking whether the Assistant is on and visible. This custom function is very simple, although it doesn't handle the case where the button that's set in the Assistant's balloon or message box can be something other than an OK button.

However, you can expand this custom function to include the most common button sets. You'll need to write a custom function that maps the Assistant's MsoButtonSetType constants to button constants that are supported in the MsgBox function built into the Visual Basic for Applications language. In the Chapter 12 practice folder, the file modAssnt.bas contains the custom function DisplayMessage along with the custom function ButtonSet that maps an MsoButtonSetType constant to the equivalent VbMsgBoxStyle constant used in the Buttons argument of the MsgBox function. Use the TestDisplayMessage procedure to test the custom functions.

Determining Which Button Gets Clicked

Both the MsgBox function and the Show method of the Balloon object return a value that depends on the button set that's defined. In the following two procedures, you declare the variable lReturn as type Long and assign it to the value returned by the MsgBox function and Show method, respectively. The first procedure displays a message box that's functionally equivalent to the Assistant's balloon displayed in the second procedure.

Sub DisplayMessageBoxWithOKCancelButtons()
    Dim lReturn As Long
    lReturn = MsgBox(Prompt:="Test", Buttons:=vbOKCancel)
    Select Case lReturn
        Case 1
            Debug.Print "OK"
        Case 2
            Debug.Print "Cancel"
    End Select
End Sub

Sub DisplayOfficeAssistantWithOKCancelButtons()
    Dim lReturn As Long
    With Assistant.NewBalloon
        .Text = "Test"
        .Button = msoButtonSetOkCancel
        lReturn = .Show
    End With
    Select Case lReturn
        Case msoBalloonButtonOK
            Debug.Print "OK"
        Case msoBalloonButtonCancel
            Debug.Print "Cancel"
    End Select
End Sub

The return value of the Show method is one of the MsoBalloonButtonType constants:

msoBalloonButtonAbort msoBalloonButtonCancel
msoBalloonButtonIgnore msoBalloonButtonNo
msoBalloonButtonOK msoBalloonButtonRetry
msoBalloonButtonSnooze msoBalloonButtonYes
msoBalloonButtonBack msoBalloonButtonClose
msoBalloonButtonNext msoBalloonButtonNull
msoBalloonButtonOptions msoBalloonButtonSearch
msoBalloonButtonTips msoBalloonButtonYesToAll

These values represent the possible buttons that can be displayed in the balloon, depending on the value assigned to the Button property.