Builder
class Builder
kotlin.Any | |
↳ | androidx.media.AudioFocusRequestCompat.Builder |
Builder class for AudioFocusRequestCompat
objects.
See AudioFocusRequestCompat
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 |
AudioAttributesCompat |
attributes with usage set to AudioAttributesCompat#USAGE_MEDIA |
pauses on duck | false |
supports delayed focus grant | false |
In contrast to a AudioFocusRequest
, attempting to build()
an without an AudioManager.OnAudioFocusChangeListener
will throw an IllegalArgumentException
, because the listener is required for all API levels up to API 26.
Summary
Public constructors | |
---|---|
Constructs a new |
|
<init>(@NonNull requestToCopy: AudioFocusRequestCompat) Constructs a new |
Public methods | |
---|---|
AudioFocusRequestCompat! |
build() Builds a new |
AudioFocusRequestCompat.Builder |
setAudioAttributes(@NonNull attributes: AudioAttributesCompat) Sets the |
AudioFocusRequestCompat.Builder |
setFocusGain(focusGain: Int) Sets the type of focus gain that will be requested. |
AudioFocusRequestCompat.Builder |
setOnAudioFocusChangeListener(@NonNull listener: OnAudioFocusChangeListener) Sets the listener called when audio focus changes after being requested with |
AudioFocusRequestCompat.Builder |
setOnAudioFocusChangeListener(@NonNull listener: OnAudioFocusChangeListener, @NonNull handler: Handler) Sets the listener called when audio focus changes after being requested with |
AudioFocusRequestCompat.Builder |
setWillPauseWhenDucked(pauseOnDuck: Boolean) Declare the intended behavior of the application with regards to audio ducking. |
Public constructors
<init>
Builder(focusGain: Int)
Constructs a new Builder
, and specifies how audio focus will be requested. Valid values for focus requests are AudioManagerCompat#AUDIOFOCUS_GAIN
, AudioManagerCompat#AUDIOFOCUS_GAIN_TRANSIENT
, and
, and
. AudioManagerCompat#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE
is converted to AudioManagerCompat#AUDIOFOCUS_GAIN_TRANSIENT
on API levels previous to API 19.
By default there is no focus change listener, delayed focus is not supported, ducking is suitable for the application, and the AudioAttributesCompat
have a usage of AudioAttributes#USAGE_MEDIA
.
Parameters | |
---|---|
focusGain |
Int: the type of audio focus gain that will be requested |
Exceptions | |
---|---|
IllegalArgumentException |
thrown when an invalid focus gain type is used |
<init>
Builder(@NonNull requestToCopy: AudioFocusRequestCompat)
Constructs a new Builder
with all the properties of the AudioFocusRequestCompat
passed as parameter. Use this method when you want a new request to differ only by some properties.
Parameters | |
---|---|
requestToCopy |
AudioFocusRequestCompat: the non-null AudioFocusRequestCompat to duplicate. |
Exceptions | |
---|---|
IllegalArgumentException |
thrown when a null AudioFocusRequestCompat is used. |
Public methods
build
fun build(): AudioFocusRequestCompat!
Builds a new AudioFocusRequestCompat
instance combining all the information gathered by this Builder
's configuration methods.
Return | |
---|---|
AudioFocusRequestCompat! |
the AudioFocusRequestCompat instance qualified by all the properties set on this Builder . |
Exceptions | |
---|---|
IllegalStateException |
thrown when attempting to build a focus request without a focus change listener set. |
setAudioAttributes
@NonNull fun setAudioAttributes(@NonNull attributes: AudioAttributesCompat): AudioFocusRequestCompat.Builder
Sets the AudioAttributesCompat
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 AudioAttributesCompat
as used for playback, see for example
in MediaPlayer
or
in AudioTrack
.
Parameters | |
---|---|
attributes |
AudioAttributesCompat: the AudioAttributesCompat for the focus request. |
Return | |
---|---|
AudioFocusRequestCompat.Builder |
this Builder instance. |
Exceptions | |
---|---|
NullPointerException |
thrown when using null for the attributes. |
setFocusGain
@NonNull fun setFocusGain(focusGain: Int): AudioFocusRequestCompat.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 AudioFocusRequestCompat
instance.
Parameters | |
---|---|
focusGain |
Int: the type of audio focus gain that will be requested. |
Return | |
---|---|
AudioFocusRequestCompat.Builder |
this Builder instance |
Exceptions | |
---|---|
IllegalArgumentException |
thrown when an invalid focus gain type is used |
setOnAudioFocusChangeListener
@NonNull fun setOnAudioFocusChangeListener(@NonNull listener: OnAudioFocusChangeListener): AudioFocusRequestCompat.Builder
Sets the listener called when audio focus changes after being requested with
, and until being abandoned with AudioManagerCompat#abandonAudioFocusRequest(AudioManager, * AudioFocusRequestCompat)
. 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 main thread.
Parameters | |
---|---|
listener |
OnAudioFocusChangeListener: the listener receiving the focus change notifications. |
Return | |
---|---|
AudioFocusRequestCompat.Builder |
this Builder instance. |
Exceptions | |
---|---|
NullPointerException |
thrown when a null focus listener is used. |
setOnAudioFocusChangeListener
@NonNull fun setOnAudioFocusChangeListener(
@NonNull listener: OnAudioFocusChangeListener,
@NonNull handler: Handler
): AudioFocusRequestCompat.Builder
Sets the listener called when audio focus changes after being requested with
, and until being abandoned with AudioManagerCompat#abandonAudioFocusRequest(AudioManager, * AudioFocusRequestCompat)
. 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 |
OnAudioFocusChangeListener: the listener receiving the focus change notifications. |
handler |
Handler: the Handler for the thread on which to execute the notifications. |
Return | |
---|---|
AudioFocusRequestCompat.Builder |
this Builder instance. |
Exceptions | |
---|---|
NullPointerException |
thrown when a null focus listener or handler is used. |
setWillPauseWhenDucked
@NonNull fun setWillPauseWhenDucked(pauseOnDuck: Boolean): AudioFocusRequestCompat.Builder
Declare the intended behavior of the application with regards to audio ducking. See more details in the AudioFocusRequest
class documentation. Setting pauseOnDuck to true will only have an effect on android.os.Build.VERSION_CODES#O
and later.
Parameters | |
---|---|
pauseOnDuck |
Boolean: use true if the application intends to pause audio playback when losing focus with AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK . |
Return | |
---|---|
AudioFocusRequestCompat.Builder |
this Builder instance. |