Builder
class Builder
kotlin.Any | |
↳ | android.media.AudioFocusRequest.Builder |
Builder class for AudioFocusRequest
objects.
See AudioFocusRequest
for an example of building an instance with this builder.
The default values for the instance to be built are:
focus listener and handler | none |
AudioAttributes |
attributes with usage set to AudioAttributes#USAGE_MEDIA |
pauses on duck | false |
supports delayed focus grant | false |
Summary
Public constructors | |
---|---|
Constructs a new |
|
Builder(requestToCopy: AudioFocusRequest) Constructs a new |
Public methods | |
---|---|
AudioFocusRequest! |
build() Builds a new |
AudioFocusRequest.Builder |
setAcceptsDelayedFocusGain(acceptsDelayedFocusGain: Boolean) Marks this focus request as compatible with delayed focus. |
AudioFocusRequest.Builder |
setAudioAttributes(attributes: AudioAttributes) Sets the |
AudioFocusRequest.Builder |
setFocusGain(focusGain: Int) Sets the type of focus gain that will be requested. |
AudioFocusRequest.Builder |
setForceDucking(forceDucking: Boolean) Marks this focus request as forcing ducking, regardless of the conditions in which the system would or would not enforce ducking. |
AudioFocusRequest.Builder |
Sets the listener called when audio focus changes after being requested with |
AudioFocusRequest.Builder |
setOnAudioFocusChangeListener(listener: AudioManager.OnAudioFocusChangeListener, handler: Handler) Sets the listener called when audio focus changes after being requested with |
AudioFocusRequest.Builder |
setWillPauseWhenDucked(pauseOnDuck: Boolean) Declare the intended behavior of the application with regards to audio ducking. |
Public constructors
Builder
Builder(focusGain: Int)
Constructs a new Builder
, and specifies how audio focus will be requested. Valid values for focus requests are AudioManager#AUDIOFOCUS_GAIN
, AudioManager#AUDIOFOCUS_GAIN_TRANSIENT
, AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK
, and AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE
.
By default there is no focus change listener, delayed focus is not supported, ducking is suitable for the application, and the AudioAttributes
have a usage of AudioAttributes#USAGE_MEDIA
.
Parameters | |
---|---|
focusGain |
Int: the type of audio focus gain that will be requested |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
thrown when an invalid focus gain type is used |
Builder
Builder(requestToCopy: AudioFocusRequest)
Constructs a new Builder
with all the properties of the AudioFocusRequest
passed as parameter. Use this method when you want a new request to differ only by some properties.
Parameters | |
---|---|
requestToCopy |
AudioFocusRequest: the non-null AudioFocusRequest to build a duplicate from. |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
thrown when a null AudioFocusRequest is used. |
Public methods
build
fun build(): AudioFocusRequest!
Builds a new AudioFocusRequest
instance combining all the information gathered by this Builder
's configuration methods.
Return | |
---|---|
AudioFocusRequest! |
the AudioFocusRequest instance qualified by all the properties set on this Builder . |
Exceptions | |
---|---|
java.lang.IllegalStateException |
thrown when attempting to build a focus request that is set to accept delayed focus, or to pause on duck, but no focus change listener was set. |
setAcceptsDelayedFocusGain
fun setAcceptsDelayedFocusGain(acceptsDelayedFocusGain: Boolean): AudioFocusRequest.Builder
Marks this focus request as compatible with delayed focus. See more details about delayed focus in the AudioFocusRequest
class documentation.
Parameters | |
---|---|
acceptsDelayedFocusGain |
Boolean: use true if the application supports delayed focus. If true , note that you must also set a focus listener to be notified of delayed focus gain, with setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener,android.os.Handler) . |
Return | |
---|---|
AudioFocusRequest.Builder |
this Builder instance This value cannot be null . |
setAudioAttributes
fun setAudioAttributes(attributes: AudioAttributes): AudioFocusRequest.Builder
Sets the AudioAttributes
to be associated with the focus request, and which describe the use case for which focus is requested. As the focus requests typically precede audio playback, this information is used on certain platforms to declare the subsequent playback use case. It is therefore good practice to use in this method the same AudioAttributes
as used for playback, see for example MediaPlayer#setAudioAttributes(AudioAttributes)
in MediaPlayer
or AudioTrack.Builder#setAudioAttributes(AudioAttributes)
in AudioTrack
.
Parameters | |
---|---|
attributes |
AudioAttributes: the AudioAttributes for the focus request. This value cannot be null . |
Return | |
---|---|
AudioFocusRequest.Builder |
this Builder instance. This value cannot be null . |
Exceptions | |
---|---|
java.lang.NullPointerException |
thrown when using null for the attributes. |
setFocusGain
fun setFocusGain(focusGain: Int): AudioFocusRequest.Builder
Sets the type of focus gain that will be requested. Use this method to replace the focus gain when building a request by modifying an existing AudioFocusRequest
instance.
Parameters | |
---|---|
focusGain |
Int: the type of audio focus gain that will be requested. |
Return | |
---|---|
AudioFocusRequest.Builder |
this Builder instance This value cannot be null . |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
thrown when an invalid focus gain type is used |
setForceDucking
fun setForceDucking(forceDucking: Boolean): AudioFocusRequest.Builder
Marks this focus request as forcing ducking, regardless of the conditions in which the system would or would not enforce ducking. Forcing ducking will only be honored when requesting AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK with an AudioAttributes
usage of AudioAttributes#USAGE_ASSISTANCE_ACCESSIBILITY
, coming from an accessibility service, and will be ignored otherwise.
Parameters | |
---|---|
forceDucking |
Boolean: true to force ducking |
Return | |
---|---|
AudioFocusRequest.Builder |
this Builder instance This value cannot be null . |
setOnAudioFocusChangeListener
fun setOnAudioFocusChangeListener(listener: AudioManager.OnAudioFocusChangeListener): AudioFocusRequest.Builder
Sets the listener called when audio focus changes after being requested with AudioManager#requestAudioFocus(AudioFocusRequest)
, and until being abandoned with AudioManager#abandonAudioFocusRequest(AudioFocusRequest)
. Note that only focus changes (gains and losses) affecting the focus owner are reported, not gains and losses of other focus requesters in the system.
Notifications are delivered on the Looper
associated with the one of the creation of the AudioManager
used to request focus (see AudioManager#requestAudioFocus(AudioFocusRequest)
).
Parameters | |
---|---|
listener |
AudioManager.OnAudioFocusChangeListener: the listener receiving the focus change notifications. This value cannot be null . |
Return | |
---|---|
AudioFocusRequest.Builder |
this Builder instance. This value cannot be null . |
Exceptions | |
---|---|
java.lang.NullPointerException |
thrown when a null focus listener is used. |
setOnAudioFocusChangeListener
fun setOnAudioFocusChangeListener(
listener: AudioManager.OnAudioFocusChangeListener,
handler: Handler
): AudioFocusRequest.Builder
Sets the listener called when audio focus changes after being requested with AudioManager#requestAudioFocus(AudioFocusRequest)
, and until being abandoned with AudioManager#abandonAudioFocusRequest(AudioFocusRequest)
. Note that only focus changes (gains and losses) affecting the focus owner are reported, not gains and losses of other focus requesters in the system.
Parameters | |
---|---|
listener |
AudioManager.OnAudioFocusChangeListener: the listener receiving the focus change notifications. This value cannot be null . |
handler |
Handler: the Handler for the thread on which to execute the notifications. This value cannot be null . |
Return | |
---|---|
AudioFocusRequest.Builder |
this Builder instance. This value cannot be null . |
Exceptions | |
---|---|
java.lang.NullPointerException |
thrown when a null focus listener or handler is used. |
setWillPauseWhenDucked
fun setWillPauseWhenDucked(pauseOnDuck: Boolean): AudioFocusRequest.Builder
Declare the intended behavior of the application with regards to audio ducking. See more details in the AudioFocusRequest
class documentation.
Parameters | |
---|---|
pauseOnDuck |
Boolean: use true if the application intends to pause audio playback when losing focus with AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK . If true , note that you must also set a focus listener to receive such an event, with setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener,android.os.Handler) . |
Return | |
---|---|
AudioFocusRequest.Builder |
this Builder instance. This value cannot be null . |