IVCmdMenu::Activate

This method activates a voice menu so that its commands can be recognized.

Syntax

HRESULT Activate( HWND hWndListening, DWORD dwFlags);

Parameters

hWndListening

[in] Handle to the window associated with the voice menu. Whenever this window is the foreground window, the voice menu is automatically activated. Otherwise, it is deactivated. If this parameter is NULL, the voice menu is global; that is, it remains active regardless of the foreground window, until the application explicitly deactivates it.

For the Auto PC, set this parameter to NULL. The application has to activate and deactivate the voice menu manually when the focus switches.

dwFlags

[in] Specifies how the menu should be active. It is one of the following values:

0 or NULL: The voice menu is active only when speech recognition is awake.
VWGFLAG_ASLEEP: The menu is active only when speech recognition is asleep and is automatically deactivated when speech recognition is awake.
VWGFLAG_BALLOON: This is a balloon grammar.

Most applications set this parameter to zero. Typically, a sleep menu contains a command to resume speech recognition, such as “Wake up.”

Return Values

NOERROR: Although this value indicates success, the voice command menu is not necessarily active. The menu is active only when speech recognition is enabled and put in the correct asleep or awake mode.
E_INVALIDARG: The argument is invalid.
VCMDERR_CANTCREATEDATASTRUCTURES: The internal data structures needed to build a grammar cannot be created.
VCMDERR_CANTINITDATASTRUCTURES: The internal data structures needed to build a grammar cannot be initialized.
VCMDERR_CANTXTRACTWORDS: The unique words needed by the engine grammar object cannot be extracted.
VCMDERR_INVALIDWINDOW: The window is invalid.
VCMDERR_MENUACTIVE: The menu is currently active and cannot be deleted.
VCMDERR_MENUTOOCOMPLEX: The menu is too complex to use.
VCMDERR_MENUWRONGLANGUAGE: The language is not supported by the speech recognition engine.
VCMDERR_NOCACHEDATA: There is no internal cache entry for this menu.
VCMDERR_NOCOMMANDS: The menu is active, but the menu does not yet contain any commands.
VCMDERR_NOENGINE: No speech recognition engine is active.
VCMDERR_NOGRAMMARINTERFACE: No engine grammar object is available.
VCMDERR_OUTOFMEM: There is no more memory.
VCMDERR_TOOMANYMENUS: There are too many active menus.

Remarks

If you set the VWGFLAG_BALLOON bit in dwFlags, this method activates the menu normally. The menu is automatically deactivated, however, after the speech recognition engine recognizes a word or after speech recognition enters sleep. The application does not need to deactivate the menu or check for notifications from IVCmdNotifySink::CommandOther once the automatic deactivation has occurred.

Only one balloon menu may be active at any time.