public class VoiceInteractionSession extends Object implements KeyEvent.Callback, ComponentCallbacks2
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(android.content.Intent)
Modifier and Type | Class and Description |
---|---|
static class |
VoiceInteractionSession.AbortVoiceRequest
A request to report that the current user interaction can not be completed with voice, as per
VoiceInteractor.AbortVoiceRequest . |
static class |
VoiceInteractionSession.CommandRequest
A generic vendor-specific request, as per
VoiceInteractor.CommandRequest . |
static class |
VoiceInteractionSession.CompleteVoiceRequest
A request to simply inform the user that the voice operation has completed, as per
VoiceInteractor.CompleteVoiceRequest . |
static class |
VoiceInteractionSession.ConfirmationRequest
A request for confirmation from the user of an operation, as per
VoiceInteractor.ConfirmationRequest . |
static class |
VoiceInteractionSession.Insets
Information about where interesting parts of the input method UI appear.
|
static class |
VoiceInteractionSession.PickOptionRequest
A request for the user to pick from a set of option, as per
VoiceInteractor.PickOptionRequest . |
static class |
VoiceInteractionSession.Request
Base class representing a request from a voice-driver app to perform a particular
voice operation with the user.
|
Modifier and Type | Field and Description |
---|---|
static String |
KEY_CONTENT |
static String |
KEY_DATA |
static String |
KEY_RECEIVER_EXTRAS |
static String |
KEY_STRUCTURE |
static int |
SHOW_SOURCE_ACTIVITY
Flag for use with
onShow(android.os.Bundle, int) : indicates that an Activity has invoked the voice
interaction service for a local interaction using
Activity.startLocalVoiceInteraction(Bundle) . |
static int |
SHOW_SOURCE_APPLICATION
Flag for use with
onShow(android.os.Bundle, int) : indicates that the application itself has invoked
the assistant. |
static int |
SHOW_SOURCE_ASSIST_GESTURE
Flag for use with
onShow(android.os.Bundle, int) : indicates that the session has been started from the
system assist gesture. |
static int |
SHOW_WITH_ASSIST
Flag received in
onShow(android.os.Bundle, int) : originator requested that the session be started with
assist data from the currently focused activity. |
static int |
SHOW_WITH_SCREENSHOT
Flag received in
onShow(android.os.Bundle, int) : originator requested that the session be started with
a screen shot of the currently focused activity. |
TRIM_MEMORY_BACKGROUND, TRIM_MEMORY_COMPLETE, TRIM_MEMORY_MODERATE, TRIM_MEMORY_RUNNING_CRITICAL, TRIM_MEMORY_RUNNING_LOW, TRIM_MEMORY_RUNNING_MODERATE, TRIM_MEMORY_UI_HIDDEN
Constructor and Description |
---|
VoiceInteractionSession(Context context) |
VoiceInteractionSession(Context context,
Handler handler) |
Modifier and Type | Method and Description |
---|---|
void |
closeSystemDialogs()
Request that all system dialogs (and status bar shade etc) be closed, allowing
access to the session's UI.
|
void |
dump(String prefix,
FileDescriptor fd,
PrintWriter writer,
String[] args)
Print the Service's state into the given stream.
|
void |
finish()
Finish the session.
|
Context |
getContext() |
int |
getDisabledShowContext()
Equivalent to
VoiceInteractionService.getDisabledShowContext . |
LayoutInflater |
getLayoutInflater()
Convenience for inflating views.
|
int |
getUserDisabledShowContext()
Return which show context flags have been disabled by the user through the system
settings UI, so the session will never get this data.
|
Dialog |
getWindow()
Retrieve the window being used to show the session's UI.
|
void |
hide()
Hide the session's UI, if currently shown.
|
void |
onAssistStructureFailure(Throwable failure)
Called when there has been a failure transferring the
AssistStructure to
the assistant. |
void |
onBackPressed()
Called when the user presses the back button while focus is in the session UI.
|
void |
onCancelRequest(VoiceInteractionSession.Request request)
Called when the
VoiceInteractor has asked to cancel a VoiceInteractionSession.Request
that was previously delivered to onRequestConfirmation(android.service.voice.VoiceInteractionSession.ConfirmationRequest) ,
onRequestPickOption(android.service.voice.VoiceInteractionSession.PickOptionRequest) , onRequestCompleteVoice(android.service.voice.VoiceInteractionSession.CompleteVoiceRequest) , onRequestAbortVoice(android.service.voice.VoiceInteractionSession.AbortVoiceRequest) ,
or onRequestCommand(android.service.voice.VoiceInteractionSession.CommandRequest) . |
void |
onCloseSystemDialogs()
Sessions automatically watch for requests that all system UI be closed (such as when
the user presses HOME), which will appear here.
|
void |
onComputeInsets(VoiceInteractionSession.Insets outInsets)
Compute the interesting insets into your UI.
|
void |
onConfigurationChanged(Configuration newConfig)
Called by the system when the device configuration changes while your
component is running.
|
void |
onCreate()
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(String[] commands)
Request to query for what extended commands the session supports.
|
void |
onHandleAssist(Bundle data,
AssistStructure structure,
AssistContent content)
Called to receive data from the application that the user was currently viewing when
an assist session is started.
|
void |
onHandleAssistSecondary(Bundle data,
AssistStructure structure,
AssistContent content,
int index,
int count)
Called to receive data from other applications that the user was or is interacting with,
that are currently on the screen in a multi-window display environment, not including the
currently focused activity.
|
void |
onHandleScreenshot(Bitmap screenshot)
Called to receive a screenshot of what the user was currently viewing when an assist
session is started.
|
void |
onHide()
Called immediately after stopping to show the session UI.
|
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 a user's interaction with an analog control, such as
flinging a trackball, generates simulated down/up events for the same
key multiple times in quick succession.
|
boolean |
onKeyUp(int keyCode,
KeyEvent event)
Called when a key up event has occurred.
|
void |
onLockscreenShown()
Called when the lockscreen was shown.
|
void |
onLowMemory()
This is called when the overall system is running low on memory, and
actively running processes should trim their memory usage.
|
void |
onRequestAbortVoice(VoiceInteractionSession.AbortVoiceRequest request)
Request to abort the voice interaction session because the voice activity can not
complete its interaction using voice.
|
void |
onRequestCommand(VoiceInteractionSession.CommandRequest request)
Process an arbitrary extended command from the caller,
corresponding to a
VoiceInteractor.CommandRequest . |
void |
onRequestCompleteVoice(VoiceInteractionSession.CompleteVoiceRequest request)
Request to complete the voice interaction session because the voice activity successfully
completed its interaction using voice.
|
void |
onRequestConfirmation(VoiceInteractionSession.ConfirmationRequest request)
Request to confirm with the user before proceeding with an unrecoverable operation,
corresponding to a
VoiceInteractor.ConfirmationRequest . |
void |
onRequestPickOption(VoiceInteractionSession.PickOptionRequest request)
Request for the user to pick one of N options, corresponding to a
VoiceInteractor.PickOptionRequest . |
void |
onShow(Bundle args,
int showFlags)
Called when the session UI is going to be shown.
|
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 |
onTrimMemory(int level)
Called when the operating system has determined that it is a good
time for a process to trim unneeded memory from its process.
|
void |
setContentView(View view) |
void |
setDisabledShowContext(int flags)
Equivalent to
VoiceInteractionService.setDisabledShowContext(int) . |
void |
setKeepAwake(boolean keepAwake)
Set whether this session will keep the device awake while it is running a voice
activity.
|
void |
setTheme(int theme)
You can call this to customize the theme used by your IME's window.
|
void |
show(Bundle args,
int flags)
Show the UI for this session.
|
void |
startVoiceActivity(Intent intent)
Ask that a new activity be started for voice interaction.
|
public static final int SHOW_WITH_ASSIST
onShow(android.os.Bundle, int)
: originator requested that the session be started with
assist data from the currently focused activity.public static final int SHOW_WITH_SCREENSHOT
onShow(android.os.Bundle, int)
: originator requested that the session be started with
a screen shot of the currently focused activity.public static final int SHOW_SOURCE_ASSIST_GESTURE
onShow(android.os.Bundle, int)
: indicates that the session has been started from the
system assist gesture.public static final int SHOW_SOURCE_APPLICATION
onShow(android.os.Bundle, int)
: indicates that the application itself has invoked
the assistant.public static final int SHOW_SOURCE_ACTIVITY
onShow(android.os.Bundle, int)
: indicates that an Activity has invoked the voice
interaction service for a local interaction using
Activity.startLocalVoiceInteraction(Bundle)
.public static final String KEY_DATA
public static final String KEY_STRUCTURE
public static final String KEY_CONTENT
public static final String KEY_RECEIVER_EXTRAS
public VoiceInteractionSession(Context context)
public Context getContext()
public void setDisabledShowContext(int flags)
VoiceInteractionService.setDisabledShowContext(int)
.public int getDisabledShowContext()
VoiceInteractionService.getDisabledShowContext
.public int getUserDisabledShowContext()
VoiceInteractionSession.SHOW_WITH_ASSIST
and
VoiceInteractionSession.SHOW_WITH_SCREENSHOT
. Note that this only tells you about
global user settings, not about restrictions that may be applied contextual based on
the current application the user is in or other transient states.public void show(Bundle args, int flags)
onShow(android.os.Bundle, int)
. This is similar to calling
VoiceInteractionService.showSession
.args
- Arbitrary arguments that will be propagated onShow(android.os.Bundle, int)
.flags
- Indicates additional optional behavior that should be performed. May
be any combination of
VoiceInteractionSession.SHOW_WITH_ASSIST
and
VoiceInteractionSession.SHOW_WITH_SCREENSHOT
to request that the system generate and deliver assist data on the current foreground
app as part of showing the session UI.public void hide()
public void setTheme(int theme)
onCreate()
, so you
will typically call it in your constructor with the resource ID
of your custom theme.public void startVoiceActivity(Intent intent)
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(java.lang.String[])
,
onRequestConfirmation(android.service.voice.VoiceInteractionSession.ConfirmationRequest)
, onRequestPickOption(android.service.voice.VoiceInteractionSession.PickOptionRequest)
,
onRequestCompleteVoice(android.service.voice.VoiceInteractionSession.CompleteVoiceRequest)
, onRequestAbortVoice(android.service.voice.VoiceInteractionSession.AbortVoiceRequest)
,
or onRequestCommand(android.service.voice.VoiceInteractionSession.CommandRequest)
You will receive a call to onTaskStarted(android.content.Intent, int)
when the task starts up
and onTaskFinished(android.content.Intent, int)
when the last activity has finished.
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.public void setKeepAwake(boolean keepAwake)
Passing false here will release the wake lock, and you can call later with
true to re-acquire it. It will also be automatically re-acquired for you each
time you start a new voice activity task -- that is when you call
startVoiceActivity(android.content.Intent)
.
public void closeSystemDialogs()
public LayoutInflater getLayoutInflater()
public Dialog getWindow()
public void finish()
hide()
and allow the system to destroy your session if it needs its RAM.public void onCreate()
onShow(android.os.Bundle, int)
.public void onShow(Bundle args, int showFlags)
onCreateContentView()
(if the session's content UI needed to be created) and
immediately prior to the window being shown. This may be called while the window
is already shown, if a show request has come in while it is shown, to allow you to
update the UI to match the new show arguments.args
- The arguments that were supplied to
VoiceInteractionService.showSession
.showFlags
- The show flags originally provided to
VoiceInteractionService.showSession
.public void onHide()
public void onDestroy()
public View onCreateContentView()
public void setContentView(View view)
public void onAssistStructureFailure(Throwable failure)
AssistStructure
to
the assistant. This may happen, for example, if the data is too large and results
in an out of memory exception, or the client has provided corrupt data. This will
be called immediately before onHandleAssist(android.os.Bundle, android.app.assist.AssistStructure, android.app.assist.AssistContent)
and the AssistStructure supplied
there afterwards will be null.failure
- The failure exception that was thrown when building the
AssistStructure
.public void onHandleAssist(Bundle data, AssistStructure structure, AssistContent content)
SHOW_WITH_ASSIST
, this method will not be called.data
- Arbitrary data supplied by the app through
Activity.onProvideAssistData
.
May be null if assist data has been disabled by the user or device policy.structure
- If available, the structure definition of all windows currently
displayed by the app. May be null if assist data has been disabled by the user
or device policy; will be an empty stub if the application has disabled assist
by marking its window as secure.content
- Additional content data supplied by the app through
Activity.onProvideAssistContent
.
May be null if assist data has been disabled by the user or device policy; will
not be automatically filled in with data from the app if the app has marked its
window as secure.public void onHandleAssistSecondary(Bundle data, AssistStructure structure, AssistContent content, int index, int count)
This method is very similar to
onHandleAssist(android.os.Bundle, android.app.assist.AssistStructure, android.app.assist.AssistContent)
except that it is called
for additional non-focused activities along with an index and count that indicates
which additional activity the data is for. index
will be between 1 and
count
-1 and this method is called once for each additional window, in no particular
order. The count
indicates how many windows to expect assist data for, including the
top focused activity, which continues to be returned via onHandleAssist(android.os.Bundle, android.app.assist.AssistStructure, android.app.assist.AssistContent)
.
To be responsive to assist requests, process assist data as soon as it is received, without waiting for all queued activities to return assist data.
data
- Arbitrary data supplied by the app through
Activity.onProvideAssistData
.
May be null if assist data has been disabled by the user or device policy.structure
- If available, the structure definition of all windows currently
displayed by the app. May be null if assist data has been disabled by the user
or device policy; will be an empty stub if the application has disabled assist
by marking its window as secure.content
- Additional content data supplied by the app through
Activity.onProvideAssistContent
.
May be null if assist data has been disabled by the user or device policy; will
not be automatically filled in with data from the app if the app has marked its
window as secure.index
- the index of the additional activity that this data
is for.count
- the total number of additional activities for which the assist data is being
returned, including the focused activity that is returned via
onHandleAssist(android.os.Bundle, android.app.assist.AssistStructure, android.app.assist.AssistContent)
.public void onHandleScreenshot(Bitmap screenshot)
SHOW_WITH_SCREENSHOT
, this method will not be called.public boolean onKeyDown(int keyCode, KeyEvent event)
KeyEvent.Callback
KeyEvent.startTracking()
to have the framework track the event
through its KeyEvent.Callback.onKeyUp(int, KeyEvent)
and also call your
KeyEvent.Callback.onKeyLongPress(int, KeyEvent)
if it occurs.onKeyDown
in interface KeyEvent.Callback
keyCode
- The value in event.getKeyCode().event
- Description of the key event.public boolean onKeyLongPress(int keyCode, KeyEvent event)
KeyEvent.Callback
KeyEvent.FLAG_CANCELED
and
KeyEvent.FLAG_CANCELED_LONG_PRESS
set. Note that in
order to receive this callback, someone in the event change
must return true from KeyEvent.Callback.onKeyDown(int, android.view.KeyEvent)
and
call KeyEvent.startTracking()
on the event.onKeyLongPress
in interface KeyEvent.Callback
keyCode
- The value in event.getKeyCode().event
- Description of the key event.public boolean onKeyUp(int keyCode, KeyEvent event)
KeyEvent.Callback
onKeyUp
in interface KeyEvent.Callback
keyCode
- The value in event.getKeyCode().event
- Description of the key event.public boolean onKeyMultiple(int keyCode, int count, KeyEvent event)
KeyEvent.Callback
onKeyMultiple
in interface KeyEvent.Callback
keyCode
- The value in event.getKeyCode().count
- Number of pairs as returned by event.getRepeatCount().event
- Description of the key event.public void onBackPressed()
hide()
.public void onCloseSystemDialogs()
hide()
.public void onLockscreenShown()
public void onConfigurationChanged(Configuration newConfig)
ComponentCallbacks
At the time that this function has been called, your Resources object will have been updated to return resource values matching the new configuration.
For more information, read Handling Runtime Changes.
onConfigurationChanged
in interface ComponentCallbacks
newConfig
- The new device configuration.public void onLowMemory()
ComponentCallbacks
You should implement this method to release any caches or other unnecessary resources you may be holding on to. The system will perform a garbage collection for you after returning from this method.
Preferably, you should implement ComponentCallbacks2.onTrimMemory(int)
from
ComponentCallbacks2
to incrementally unload your resources based on various
levels of memory demands. That API is available for API level 14 and higher, so you should
only use this ComponentCallbacks.onLowMemory()
method as a fallback for older versions, which can be
treated the same as ComponentCallbacks2.onTrimMemory(int)
with the ComponentCallbacks2.TRIM_MEMORY_COMPLETE
level.
onLowMemory
in interface ComponentCallbacks
public void onTrimMemory(int level)
ComponentCallbacks2
To retrieve the processes current trim level at any point, you can
use ActivityManager.getMyMemoryState(RunningAppProcessInfo)
.
onTrimMemory
in interface ComponentCallbacks2
level
- The context of the trim, giving a hint of the amount of
trimming the application may like to perform. May be
ComponentCallbacks2.TRIM_MEMORY_COMPLETE
, ComponentCallbacks2.TRIM_MEMORY_MODERATE
,
ComponentCallbacks2.TRIM_MEMORY_BACKGROUND
, ComponentCallbacks2.TRIM_MEMORY_UI_HIDDEN
,
ComponentCallbacks2.TRIM_MEMORY_RUNNING_CRITICAL
, ComponentCallbacks2.TRIM_MEMORY_RUNNING_LOW
,
or ComponentCallbacks2.TRIM_MEMORY_RUNNING_MODERATE
.public void onComputeInsets(VoiceInteractionSession.Insets outInsets)
outInsets.contentInsets.top
to the height
of the window, meaning it should not adjust content underneath. The default touchable
insets are VoiceInteractionSession.Insets.TOUCHABLE_INSETS_FRAME
, meaning it consumes all touch
events within its window frame.outInsets
- Fill in with the current UI insets.public void onTaskStarted(Intent intent, int taskId)
startVoiceActivity(android.content.Intent)
has actually started.intent
- The original Intent
supplied to
startVoiceActivity(android.content.Intent)
.taskId
- Unique ID of the now running task.public void onTaskFinished(Intent intent, int taskId)
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.intent
- The original Intent
supplied to
startVoiceActivity(android.content.Intent)
.taskId
- Unique ID of the finished task.public boolean[] onGetSupportedCommands(String[] commands)
commands
- An array of commands that are being queried.public void onRequestConfirmation(VoiceInteractionSession.ConfirmationRequest request)
VoiceInteractor.ConfirmationRequest
.request
- The active request.public void onRequestPickOption(VoiceInteractionSession.PickOptionRequest request)
VoiceInteractor.PickOptionRequest
.request
- The active request.public void onRequestCompleteVoice(VoiceInteractionSession.CompleteVoiceRequest request)
VoiceInteractor.CompleteVoiceRequest
. The default implementation just sends an empty
confirmation back to allow the activity to exit.request
- The active request.public void onRequestAbortVoice(VoiceInteractionSession.AbortVoiceRequest request)
VoiceInteractor.AbortVoiceRequest
. The default implementation just sends an empty
confirmation back to allow the activity to exit.request
- The active request.public void onRequestCommand(VoiceInteractionSession.CommandRequest request)
VoiceInteractor.CommandRequest
.request
- The active request.public void onCancelRequest(VoiceInteractionSession.Request request)
VoiceInteractor
has asked to cancel a VoiceInteractionSession.Request
that was previously delivered to onRequestConfirmation(android.service.voice.VoiceInteractionSession.ConfirmationRequest)
,
onRequestPickOption(android.service.voice.VoiceInteractionSession.PickOptionRequest)
, onRequestCompleteVoice(android.service.voice.VoiceInteractionSession.CompleteVoiceRequest)
, onRequestAbortVoice(android.service.voice.VoiceInteractionSession.AbortVoiceRequest)
,
or onRequestCommand(android.service.voice.VoiceInteractionSession.CommandRequest)
.request
- The request that is being canceled.public void dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args)
VoiceInteractionSessionService
when its Service
Service.dump(java.io.FileDescriptor, java.io.PrintWriter, java.lang.String[])
method is called.prefix
- Text to print at the front of each line.fd
- The raw file descriptor that the dump is being sent to.writer
- The PrintWriter to which you should dump your state. This will be
closed for you after you return.args
- additional arguments to the dump request.