Edit

Language Bar (Text Services)

  • Article

Implementing the Language Bar Object

To support adding an item to the language bar, a text service must implement an object that supports the ITfSource interface and one of the ITfLangBarItem control elements. When the item is installed, the language bar installs an ITfLangBarItemSink sink by calling the item's ITfSource::AdviseSink with IID_ITfLangBarItemSink. The item uses the ITfLangBarItemSink interface to notify the language bar of changes, for example when the item is hidden, shown, enabled, or disabled.

Four types of language bar items can be installed and each of the required interfaces is created from ITfLangBarItem. The following are possible ITfLangBarItem control elements.

Element Description
Button A language bar button functions as a command button, toggle control, or a menu on the language bar. The object must support the ITfLangBarItemButton interface.
Balloon A language bar balloon functions as a pop-up notification on the language bar. The object must support the ITfLangBarItemBalloon interface.
Bitmap A language bar bitmap functions as a static element on the language bar that displays a bitmap. The object must support the ITfLangBarItemBitmap interface.
Bitmap Button A language bar bitmap button functions as a button element on the language bar that displays text and a bitmap. The object must support the ITfLangBarItemBitmapButton interface.

 

Button Styles

A button element can function as any of the following. The function of the button item is determined by the flags set in the dwStyle member of the TF_LANGBARITEMINFO structure in the ITfLangBarItem::GetInfo method.

Element Description
Button The button functions as a standard command button. This button style is identified by the TF_LBI_STYLE_BTN_BUTTON style. ITfLangBarItemButton::OnClick is called when the item is clicked. ITfLangBarItemButton::InitMenu and ITfLangBarItemButton::OnMenuSelect are not used.
Toggle Button The button functions as a toggle control that can maintain a clicked state, similar to a check box. This button style is identified by the TF_LBI_STYLE_BTN_TOGGLE style. ITfLangBarItemButton::OnClick is called when the item is clicked. ITfLangBarItemButton::InitMenu and ITfLangBarItemButton::OnMenuSelect are not used.
Menu The button functions as a drop-down menu. This button style is identified by the TF_LBI_STYLE_BTN_MENU style. ITfLangBarItemButton::InitMenu is called when the button is clicked. When the user selects an item in the menu, the language bar calls ITfLangBarItemButton::OnMenuSelect with the identifier of the selected menu item. ITfLangBarItemButton::OnClickis not used.

 

Implementing a Menu Button

When the user clicks a menu button, the language bar calls ITfLangBarItemButton::InitMenu. The item adds items to the menu using the ITfMenu interface passed to InitMenu.

To add a submenu to the menu, call ITfMenu::AddMenuItem with TF_LBMENUF_SUBMENU. When this is done, a new ITfMenu object that represents the submenu is returned in the ppMenu parameter of AddMenuItem. This new menu object is used to add items to the submenu.

When the user selects an item in the menu, the language bar calls ITfLangBarItemButton::OnMenuSelect with the identifier of the selected menu item.

Adding Items to the Language Bar

A text service should add its items to the language bar when its ITfTextInputProcessor::Activate method is called and remove them when its ITfTextInputProcessor::Deactivate is called.

To add an item to the language bar, the text service obtains an ITfLangBarItemMgr interface by calling ITfThreadMgr::QueryInterface with IID_ITfLangBarItemMgr. The text service then calls ITfLangBarItemMgr::AddItem with the pointer to the language bar item object.

The text service must remove the item when deactivated. The text service either uses the same ITfLangBarItemMgr interface used to add the items or obtains another instance of the interface. The text service then calls ITfLangBarItemMgr::RemoveItem with the interface pointer of the item to remove.

Extending System Language Bar Items

TSF provides the ability to add menu items to existing language bar menus. This enables a text service to add items to the menu of another text service without having to add a separate button to the toolbar. This also enables the menu items to be organized into logical groups. For example, a text service that provides additional features to the standard speech text service can add items to the speech text service menu rather than adding its own top-level menu button.

A text service provides a language bar menu extension by implementing an object that supports the ITfSystemLangBarItemSink interface. This interface works exactly like the ITfLangBarItemButton interface for a menu button. When the menu is displayed, the text service being extended calls ITfSystemLangBarItemSink::InitMenu. The extension adds items to the menu using the ITfMenu interface passed to InitMenu. When the user selects an item added by the extension, the text service being extended calls ITfSystemLangBarItemSink::OnMenuSelect with the identifier of the selected menu item.

To install a language bar menu extension, the text service completes the following steps.

  1. Obtain the ITfLangBarItem interface for the item to extend by calling ITfLangBarItemMgr::GetItem with the GUID for the item to be extended.
  2. Obtain the ITfSource interface for the item to extend by calling ITfLangBarItem::QueryInterface with IID_ITfSource.
  3. Call ITfSource::AdviseSink with IID_ITfSystemLangBarItemSink and the pointer to the ITfSystemLangBarItemSink object. If ITfSource::AdviseSink fails, the text service does not support menu extensions.

ITfSource::UnadviseSinkITfSource::AdviseSink

Supporting Language Bar Menu Extensions

A text service can enable other text services to add items to its language bar menus as shown above. The text service that must publish its GUID so that the item can be obtained by calling ITfLangBarItemMgr::GetItem.

To support menu extensions, the text service must support the ITfSource interface. The following steps enable support for one or more menu extensions.

  1. When ITfSource::AdviseSink with IID_ITfSystemLangBarItemSink is called, the text service must store the ITfSystemLangBarItemSink interface and return a cookie value that will identify the extension.
  2. When ITfLangBarItemButton::InitMenu is called, the text service calls the extension's ITfSystemLangBarItemSink::InitMenu method. The text service must implement a way to identify the menu items added by the extension as opposed to the items added by the text service itself.
  3. When ITfLangBarItemButton::OnMenuSelect is called with a menu item identifier that belongs to an extension, the text service calls the extensions's ITfSystemLangBarItemSink::OnMenuSelect method.
  4. When ITfSource::UnadviseSink is called with the appropriate cookie, the text service removes the menu extension.

How To Set Up Text Services Framework

Language Bar (Applications)