IAgentBalloon

IAgentBalloon defines an interface that allows applications to query properties for the Microsoft Agent word balloon.

Initial defaults for a character's word balloon are set in the Microsoft Agent Character Editor, but once the application is running, the user may override the Enabled and font properties. If a user changes the balloon's properties, the change affects all characters.

Methods in Vtable Order

IAgentBalloon::GetBackColor

HRESULT GetBackColor(
   long * plBGColor  // address of variable for background color displayed
);                   // in word balloon

Retrieves the value for the background color displayed in a word balloon.

• Returns S_OK to indicate the operation was successful.

plBGColor

The address of a variable that receives the color setting for the balloon background.

The background color used in a character word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application. However, the user can change the background color of the word balloons for all characters through the Microsoft Agent property sheet.

See also IAgentBalloon::GetForeColor

IAgentBalloon::GetBorderColor

HRESULT GetBorderColor (
  long * plBorderColor// address of variable for border color displayed
);                    // for word balloon

Retrieves the value for the border color displayed for a word balloon.

• Returns S_OK to indicate the operation was successful.

plBorderColor

The address of a variable that receives the color setting for the balloon border.

The border color for a character word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application. However, the user can change the border color of the word balloons for all characters through the Microsoft Agent property sheet.

See also IAgentBalloon::GetBackColor, IAgentBalloon::GetForeColor

IAgentBalloon::GetEnabled

HRESULT GetEnabled(
  long * pbEnabled  // address of variable for Enabled setting 
);                  // for word balloon

Retrieves the value of the Enabled property for a word balloon.

• Returns S_OK to indicate the operation was successful.

pbEnabled

The address of a variable that receives TRUE when the word balloon is enabled and FALSE when it is disabled.

The Microsoft Agent server automatically displays the word balloon for spoken output, unless it is disabled. The word balloon can be disabled for a character in the Microsoft Agent Character Editor, or for all characters by the user, in the Microsoft Agent property sheet. If the user disables the word balloon, the client cannot restore it.

IAgentBalloon::GetFontBold

HRESULT GetFontBold(
   long * pbFontBold  // address of variable for bold setting for
);                    // font displayed in word balloon 

Indicates whether the font used in a word balloon is bold.

• Returns S_OK to indicate the operation was successful.

pbFontBold

The address of a value that receives TRUE if the font is bold and FALSE if not bold.

The font style used in a character word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application. However, the user can override the font settings for all characters through the Microsoft Agent property sheet.

IAgentBalloon::GetFontCharSet

HRESULT GetFontCharSet(
   short * psFontCharSet  // character set displayed in word balloon
); 

Indicates the character set of the font displayed in a word balloon.

• Returns S_OK to indicate the operation was successful.

psFontCharSet

The address of a value that receives the font's character set. The following are some common settings for value:

For other character set values, consult the Microsoft Win32® documentation.

The default character set used in a character's word balloon is defined in the Microsoft Agent Character Editor. You can change it using IAgentBalloon::SetFontCharSet. However, the user can override the character set setting for all characters using the Microsoft Agent property sheet.

See also IAgentBalloon::SetFontCharSet

IAgentBalloon::GetFontItalic

HRESULT GetFontItalic(
   long * pbFontItalic  // address of variable for italic setting for 
);                      // font displayed in word balloon 

Indicates whether the font used in a word balloon is italic.

• Returns S_OK to indicate the operation was successful.

pbFontItalic

The address of a value that receives TRUE if the font is italic and FALSE if not italic.

The font style used in a character's word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application. However, the user can override the font settings for all characters through the Microsoft Agent property sheet.

IAgentBalloon::GetFontName

HRESULT GetFontName(
   BSTR * pbszFontName  // address of variable for font displayed 
);                      // in word balloon
                   

Retrieves the value for the font displayed in a word balloon.

• Returns S_OK to indicate the operation was successful.

pbszFontName

The address of a BSTR that receives the font name displayed in a word balloon.

The default font used in a character word balloon is defined in the Microsoft Agent Character Editor. You can change it with IAgentBalloon::SetFontName. The user can override the font setting for all characters using the Microsoft Agent property sheet.

IAgentBalloon::GetFontSize

HRESULT GetFontSize(
   long * plFontSize  // address of variable for font size 
);                    // for font displayed in word balloon 

Retrieves the value for the size of the font displayed in a word balloon.

• Returns S_OK to indicate the operation was successful.

plFontSize

The address of a value that receives the size of the font.

The default font size used in a character word balloon is defined in the Microsoft Agent Character Editor. You can change it with IAgentBalloon::SetFontSize. However, the user can override also the font size settings for all characters using the Microsoft Agent property sheet.

IAgentBalloon::GetFontStrikethru

HRESULT GetFontStrikethru(
   long * pbFontStrikethru  // address of variable for strikethrough setting 
);                          // for font displayed in word balloon 

Indicates whether the font used in a word balloon has the strikethrough style set.

• Returns S_OK to indicate the operation was successful.

pbFontStrikethru

The address of a value that receives TRUE if the font strikethrough style is set and FALSE if not.

The font style used in a character word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application. However, the user can override the font settings for all characters using the Microsoft Agent property sheet.

IAgentBalloon::GetFontUnderline

HRESULT GetFontUnderline(
   long * pbFontUnderline  // address of variable for underline setting
);                         // for font displayed in word balloon 

Indicates whether the font used in a word balloon has the underline style set.

• Returns S_OK to indicate the operation was successful.

pbFontUnderline

The address of a value that receives TRUE if the font underline style is set and FALSE if not.

The font style used in a character word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application. However, the user can override the font settings for all characters using the Microsoft Agent property sheet.

IAgentBalloon::GetForeColor

HRESULT GetForeColor(
   long * plFGColor // address of variable for foreground color displayed
);                  // in word balloon

Retrieves the value for the foreground color displayed in a word balloon.

• Returns S_OK to indicate the operation was successful.

plFGColor

The address of a variable that receives the color setting for the balloon foreground.

The foreground color used in a character word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application. However, the user can override the foreground color of the word balloons for all characters through the Microsoft Agent property sheet.

See also IAgentBalloon::GetBackColor

IAgentBalloon::GetNumCharsPerLine

HRESULT GetNumCharsPerLine(
   long * plCharsPerLine  // address of variable for characters per line
);                        // displayed in word balloon

Retrieves the value for the average number of characters per line displayed in a word balloon.

• Returns S_OK to indicate the operation was successful.

pbCharsPerLine

The address of a variable that receives the number of characters per line.

The Microsoft Agent server automatically scrolls the lines displayed for spoken output in the word balloon. The average number of characters per line for a character's word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application.

See also IAgentBalloon::GetNumLines

IAgentBalloon::GetNumLines

HRESULT GetNumLines(
   long * pbcLines  // address of variable for number of lines 
);                  // displayed in word balloon

Retrieves the value of the number of lines displayed in a word balloon.

• Returns S_OK to indicate the operation was successful.

pbcLines

The address of a variable that receives the number of lines displayed.

The Microsoft Agent server automatically scrolls the lines displayed for spoken output in the word balloon. The number of lines for a character word balloon is defined in the Microsoft Agent Character Editor. It cannot be changed by an application.

See also IAgentBalloon::GetNumCharsPerLine

IAgentBalloon::GetVisible

HRESULT GetVisible(
   long * pbVisible  // address of variable for word balloon
);                   // Visible setting

Determines whether the word balloon is visible or hidden.

• Returns S_OK to indicate the operation was successful.

pbVisible

Address of a variable that receives TRUE if the word balloon is visible and FALSE if hidden.

See also IAgentBalloon::SetVisible

IAgentBalloon::SetFontCharSet

HRESULT SetFontCharSet(
   short sFontCharSet  // character set displayed in word balloon
); 

Sets the character set of the font displayed in the word balloon.

• Returns S_OK to indicate the operation was successful.

sFontCharSet

The character set of the font. The following are some common settings for value:

For other character set values, consult the Microsoft Win32 documentation.

The default character set used in a character's word balloon is defined in the Microsoft Agent Character Editor. You can change it with IAgentBalloon::SetFontCharSet. However, the user can override the character set setting for all characters using the Microsoft Agent property sheet.

See also IAgentBalloon::GetFontCharSet

IAgentBalloon::SetFontName

HRESULT SetFontName(
   BSTR bszFontName  // font displayed in word balloon
);
                   

Sets the font displayed in the word balloon.

• Returns S_OK to indicate the operation was successful.

bszFontName

A BSTR that sets the font displayed in the word balloon.

The default font used in a character's word balloon is defined in the Microsoft Agent Character Editor. You can change it with IAgentBalloon::SetFontName. However, the user can override the font setting for all characters using the Microsoft Agent property sheet.

See also IAgentBalloon::GetVisible

IAgentBalloon::SetFontSize

HRESULT SetFontSize(
   long lFontSize  // font size displayed in word balloon
); 

Sets the size of the font displayed in the word balloon.

• Returns S_OK to indicate the operation was successful.

lFontSize

The size of the font.

The default font size used in a character's word balloon is defined in the Microsoft Agent Character Editor. You can change it with IAgentBalloon::SetFontSize. However, the user can override the font size setting for all characters using the Microsoft Agent property sheet.

See also IAgentBalloon::GetFontSize

IAgentBalloon::SetVisible

HRESULT SetVisible(
   long bVisible  // word balloon Visible setting 
);

Sets the Visible property for the word balloon.

• Returns S_OK to indicate the operation was successful.

bVisible

Visible property setting. A value of TRUE displays the word balloon; a value of FALSE hides it.

See also IAgentBalloon::GetVisibleEvents

Microsoft Agent provides several events for tracking user interaction and server states. This section describes the event methods exposed by the IAgentNotifySink interface.