Android APIs
public abstract class

VoiceInteractionSession

extends Object
implements KeyEvent.Callback
java.lang.Object
   ↳ android.service.voice.VoiceInteractionSession

Class Overview

An active voice interaction session, providing a facility for the implementation to interact with the user in the voice interaction layer. This interface is no shown by default, but you can request that it be shown with showWindow(), which will result in a later call to onCreateContentView() in which the UI can be built

A voice interaction session can be self-contained, ultimately calling finish() when done. It can also initiate voice interactions with applications by calling startVoiceActivity(Intent)

.

Summary

Nested Classes
class VoiceInteractionSession.Caller  
class VoiceInteractionSession.Insets Information about where interesting parts of the input method UI appear. 
class VoiceInteractionSession.Request  
Public Constructors
VoiceInteractionSession(Context context)
VoiceInteractionSession(Context context, Handler handler)
Public Methods
void finish()
Finish the session.
LayoutInflater getLayoutInflater()
Convenience for inflating views.
Dialog getWindow()
Retrieve the window being used to show the session's UI.
void hideWindow()
void onAbortVoice(VoiceInteractionSession.Caller caller, VoiceInteractionSession.Request request, CharSequence message, Bundle extras)
Request to abort the voice interaction session because the voice activity can not complete its interaction using voice.
void onBackPressed()
abstract void onCancel(VoiceInteractionSession.Request request)
Called when the VoiceInteractor has asked to cancel a VoiceInteractionSession.Request that was previously delivered to onConfirm(VoiceInteractionSession.Caller, VoiceInteractionSession.Request, CharSequence, Bundle) or onCommand(VoiceInteractionSession.Caller, VoiceInteractionSession.Request, String, Bundle).
void onCloseSystemDialogs()
Sessions automatically watch for requests that all system UI be closed (such as when the user presses HOME), which will appear here.
abstract void onCommand(VoiceInteractionSession.Caller caller, VoiceInteractionSession.Request request, String command, Bundle extras)
Process an arbitrary extended command from the caller, corresponding to a VoiceInteractor.CommandRequest.
void onComputeInsets(VoiceInteractionSession.Insets outInsets)
Compute the interesting insets into your UI.
abstract void onConfirm(VoiceInteractionSession.Caller caller, VoiceInteractionSession.Request request, CharSequence prompt, Bundle extras)
Request to confirm with the user before proceeding with an unrecoverable operation, corresponding to a VoiceInteractor.ConfirmationRequest.
void onCreate(Bundle args)
Initiatize a new session.
View onCreateContentView()
Hook in which to create the session's UI.
void onDestroy()
Last callback to the session as it is being finished.
boolean[] onGetSupportedCommands(VoiceInteractionSession.Caller caller, String[] commands)
Request to query for what extended commands the session supports.
boolean onKeyDown(int keyCode, KeyEvent event)
Called when a key down event has occurred.
boolean onKeyLongPress(int keyCode, KeyEvent event)
Called when a long press has occurred.
boolean onKeyMultiple(int keyCode, int count, KeyEvent event)
Called when multiple down/up pairs of the same key have occurred in a row.
boolean onKeyUp(int keyCode, KeyEvent event)
Called when a key up event has occurred.
void onTaskFinished(Intent intent, int taskId)
Called when the last activity of a task initiated by startVoiceActivity(android.content.Intent) has finished.
void onTaskStarted(Intent intent, int taskId)
Called when a task initiated by startVoiceActivity(android.content.Intent) has actually started.
void setContentView(View view)
void setTheme(int theme)
You can call this to customize the theme used by your IME's window.
void showWindow()
void startVoiceActivity(Intent intent)
Ask that a new activity be started for voice interaction.
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.view.KeyEvent.Callback

Public Constructors

public VoiceInteractionSession (Context context)

public VoiceInteractionSession (Context context, Handler handler)

Public Methods

public void finish ()

Finish the session.

public LayoutInflater getLayoutInflater ()

Convenience for inflating views.

public Dialog getWindow ()

Retrieve the window being used to show the session's UI.

public void hideWindow ()

public void onAbortVoice (VoiceInteractionSession.Caller caller, VoiceInteractionSession.Request request, CharSequence message, Bundle extras)

Request to abort the voice interaction session because the voice activity can not complete its interaction using voice. Corresponds to VoiceInteractor.AbortVoiceRequest. The default implementation just sends an empty confirmation back to allow the activity to exit.

Parameters
caller Who is making the request.
request The active request.
message The message informing the user of the problem, as per VoiceInteractor.AbortVoiceRequest.
extras Any additional information, as per VoiceInteractor.AbortVoiceRequest.

public void onBackPressed ()

public abstract void onCancel (VoiceInteractionSession.Request request)

Called when the VoiceInteractor has asked to cancel a VoiceInteractionSession.Request that was previously delivered to onConfirm(VoiceInteractionSession.Caller, VoiceInteractionSession.Request, CharSequence, Bundle) or onCommand(VoiceInteractionSession.Caller, VoiceInteractionSession.Request, String, Bundle).

Parameters
request The request that is being canceled.

public void onCloseSystemDialogs ()

Sessions automatically watch for requests that all system UI be closed (such as when the user presses HOME), which will appear here. The default implementation always calls finish().

public abstract void onCommand (VoiceInteractionSession.Caller caller, VoiceInteractionSession.Request request, String command, Bundle extras)

Process an arbitrary extended command from the caller, corresponding to a VoiceInteractor.CommandRequest.

Parameters
caller Who is making the request.
request The active request.
command The command that is being executed, as per VoiceInteractor.CommandRequest.
extras Any additional information, as per VoiceInteractor.CommandRequest.

public void onComputeInsets (VoiceInteractionSession.Insets outInsets)

Compute the interesting insets into your UI. The default implementation uses the entire window frame as the insets. The default touchable insets are TOUCHABLE_INSETS_FRAME.

Parameters
outInsets Fill in with the current UI insets.

public abstract void onConfirm (VoiceInteractionSession.Caller caller, VoiceInteractionSession.Request request, CharSequence prompt, Bundle extras)

Request to confirm with the user before proceeding with an unrecoverable operation, corresponding to a VoiceInteractor.ConfirmationRequest.

Parameters
caller Who is making the request.
request The active request.
prompt The prompt informing the user of what will happen, as per VoiceInteractor.ConfirmationRequest.
extras Any additional information, as per VoiceInteractor.ConfirmationRequest.

public void onCreate (Bundle args)

Initiatize a new session.

Parameters
args The arguments that were supplied to VoiceInteractionService.startSession.

public View onCreateContentView ()

Hook in which to create the session's UI.

public void onDestroy ()

Last callback to the session as it is being finished.

public boolean[] onGetSupportedCommands (VoiceInteractionSession.Caller caller, String[] commands)

Request to query for what extended commands the session supports.

Parameters
caller Who is making the request.
commands An array of commands that are being queried.
Returns
  • Return an array of booleans indicating which of each entry in the command array is supported. A true entry in the array indicates the command is supported; false indicates it is not. The default implementation returns an array of all false entries.

public boolean onKeyDown (int keyCode, KeyEvent event)

Called when a key down event has occurred. If you return true, you can first call KeyEvent.startTracking() to have the framework track the event through its onKeyUp(int, KeyEvent) and also call your onKeyLongPress(int, KeyEvent) if it occurs.

Parameters
keyCode The value in event.getKeyCode().
event Description of the key event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public boolean onKeyLongPress (int keyCode, KeyEvent event)

Called when a long press has occurred. If you return true, the final key up will have FLAG_CANCELED and FLAG_CANCELED_LONG_PRESS set. Note that in order to receive this callback, someone in the event change must return true from onKeyDown(int, KeyEvent) and call startTracking() on the event.

Parameters
keyCode The value in event.getKeyCode().
event Description of the key event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public boolean onKeyMultiple (int keyCode, int count, KeyEvent event)

Called when multiple down/up pairs of the same key have occurred in a row.

Parameters
keyCode The value in event.getKeyCode().
count Number of pairs as returned by event.getRepeatCount().
event Description of the key event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public boolean onKeyUp (int keyCode, KeyEvent event)

Called when a key up event has occurred.

Parameters
keyCode The value in event.getKeyCode().
event Description of the key event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public void onTaskFinished (Intent intent, int taskId)

Called when the last activity of a task initiated by startVoiceActivity(android.content.Intent) has finished. The default implementation calls finish() on the assumption that this represents the completion of a voice action. You can override the implementation if you would like a different behavior.

Parameters
intent The original Intent supplied to startVoiceActivity(android.content.Intent).
taskId Unique ID of the finished task.

public void onTaskStarted (Intent intent, int taskId)

Called when a task initiated by startVoiceActivity(android.content.Intent) has actually started.

Parameters
intent The original Intent supplied to startVoiceActivity(android.content.Intent).
taskId Unique ID of the now running task.

public void setContentView (View view)

public void setTheme (int theme)

You can call this to customize the theme used by your IME's window. This must be set before onCreate(Bundle), so you will typically call it in your constructor with the resource ID of your custom theme.

public void showWindow ()

public void startVoiceActivity (Intent intent)

Ask that a new activity be started for voice interaction. This will create a new dedicated task in the activity manager for this voice interaction session; this means that Intent.FLAG_ACTIVITY_NEW_TASK will be set for you to make it a new task.

The newly started activity will be displayed to the user in a special way, as a layer under the voice interaction UI.

As the voice activity runs, it can retrieve a VoiceInteractor through which it can perform voice interactions through your session. These requests for voice interactions will appear as callbacks on onGetSupportedCommands(VoiceInteractionSession.Caller, String[]), onConfirm(VoiceInteractionSession.Caller, VoiceInteractionSession.Request, CharSequence, Bundle), onCommand(VoiceInteractionSession.Caller, VoiceInteractionSession.Request, String, Bundle), and onCancel(VoiceInteractionSession.Request).

You will receive a call to onTaskStarted(Intent, int) when the task starts up and onTaskFinished(Intent, int) when the last activity has finished.

Parameters
intent The Intent to start this voice interaction. The given Intent will always have Intent.CATEGORY_VOICE added to it, since this is part of a voice interaction.