MediaControlView
open class MediaControlView : MediaViewGroup
androidx.media2.widget.MediaControlView |
A View that contains the controls for MediaController
or SessionPlayer
. It provides a wide range of buttons that serve the following functions: play/pause, rewind/fast-forward, skip to next/previous, select subtitle track, enter/exit full screen mode, select audio track, and adjust playback speed.
For simple use cases not requiring communication with MediaSession
, apps need to create a SessionPlayer
(e.g. androidx.media2.player.MediaPlayer
) and set it to this view by calling setPlayer
. For more advanced use cases that require MediaSession
(e.g. handling media key events, integrating with other MediaSession apps as Assistant), apps need to create a MediaController
attached to the MediaSession
and set it to this view by calling setMediaController
.
The easiest way to use a MediaControlView is by creating a VideoView
, which internally creates a MediaControlView instance and handles all the commands from buttons inside MediaControlView. It is also possible to create a MediaControlView programmatically and add it to a custom video view. For more information, refer to VideoView
.
By default, each button in the MediaControlView is visible only when its corresponding SessionCommand
is included in the active SessionCommandGroup
. For more details, refer to MediaSession#setAllowedCommands
.
UI transitions
The UI of an app can be in one of three modes:- In full mode all the views, such as progress bar, title, transport controls, and other icons are visible.
- In progress-bar only mode the progress bar is the only visible element. The title, transport controls, and other icons are hidden.
- In None mode all the views are hidden.
VideoView#setMediaControlView(MediaControlView, long)
.
User actions can change the scheduled transition during the delay interval according to the following logic:
- In Full mode
- If a touch/trackball event is received during the interval, the UI changes to None mode.
- If no touch/trackball event is received during the interval, the UI changes to progress-bar only mode.
- In Progress-bar only mode
- If a touch/trackball event is received, the UI changes to Full mode.
- If no touch/trackball event is received, the UI changes to None mode.
- In None mode, if a touch/trackball event is received, the UI changes to Full mode.
Customization
The following customizations are supported:- Set focus to the play/pause button by calling
requestPlayButtonFocus()
. - Set full screen behavior by calling
setOnFullScreenListener(OnFullScreenListener)
. Calling this method will also show the full screen button.
Displaying metadata
MediaControlView supports displaying metadata by callingMediaItem#setMetadata(MediaMetadata)
. Metadata display is different for two different media types: video (with or without sound) and audio(sound only, no video)
The following table shows the metadata displayed on VideoView and the default values assigned if the keys are not set:
For video media, MediaMetadata#METADATA_KEY_TITLE
metadata is supported. If the value is not set, the following default value will be shown: androidx.media2.widget.R.string#mcv2_non_music_title_unknown_text
Summary
Nested classes | |
---|---|
abstract |
Interface definition of a callback to be invoked to inform the fullscreen mode is changed. |
Public constructors | |
---|---|
<init>(@NonNull context: Context, @Nullable attrs: AttributeSet?) |
|
<init>(@NonNull context: Context, @Nullable attrs: AttributeSet?, defStyleAttr: Int) |
Public methods | |
---|---|
open CharSequence! | |
open Boolean |
onTouchEvent(ev: MotionEvent!) |
open Boolean |
onTrackballEvent(ev: MotionEvent!) |
open Unit |
Requests focus for the play/pause button. |
open Unit |
setMediaController(@NonNull controller: MediaController) Sets |
open Unit |
setOnFullScreenListener(@Nullable listener: MediaControlView.OnFullScreenListener?) Sets a listener to be called when the fullscreen mode should be changed. |
open Unit |
setPlayer(@NonNull player: SessionPlayer) Sets |
Protected methods | |
---|---|
open Unit | |
open Unit | |
open Unit | |
open Unit |
Public constructors
<init>
MediaControlView(@NonNull context: Context)
<init>
MediaControlView(
@NonNull context: Context,
@Nullable attrs: AttributeSet?)
<init>
MediaControlView(
@NonNull context: Context,
@Nullable attrs: AttributeSet?,
defStyleAttr: Int)
Public methods
getAccessibilityClassName
open fun getAccessibilityClassName(): CharSequence!
onTouchEvent
open fun onTouchEvent(ev: MotionEvent!): Boolean
onTrackballEvent
open fun onTrackballEvent(ev: MotionEvent!): Boolean
requestPlayButtonFocus
open fun requestPlayButtonFocus(): Unit
Requests focus for the play/pause button.
setMediaController
open fun setMediaController(@NonNull controller: MediaController): Unit
Sets MediaController
to control playback with this view. Setting a MediaController will unset any MediaController or SessionPlayer that was previously set.
It will throw IllegalStateException
if this MediaControlView belongs to a VideoView
by androidx.media2.widget.R.attr#enableControlView
or by VideoView#setMediaControlView
. Use VideoView#setMediaController
instead.
Note that MediaControlView allows controlling playback through its UI components, but calling the corresponding methods (e.g. MediaController#play()
, MediaController#pause()
) will work as well.
Parameters | |
---|---|
controller |
MediaController: the controller |
See Also
setOnFullScreenListener
open fun setOnFullScreenListener(@Nullable listener: MediaControlView.OnFullScreenListener?): Unit
Sets a listener to be called when the fullscreen mode should be changed. A non-null listener needs to be set in order to display the fullscreen button.
Parameters | |
---|---|
listener |
MediaControlView.OnFullScreenListener?: The listener to be called. A value of null removes any existing listener and hides the fullscreen button. |
setPlayer
open fun setPlayer(@NonNull player: SessionPlayer): Unit
Sets SessionPlayer
to control playback with this view. Setting a SessionPlayer will unset any MediaController or SessionPlayer that was previously set.
It will throw IllegalStateException
if this MediaControlView belongs to a VideoView
by androidx.media2.widget.R.attr#enableControlView
or by VideoView#setMediaControlView
. Use VideoView#setPlayer
instead.
Note that MediaControlView allows controlling playback through its UI components, but calling the corresponding methods (e.g. SessionPlayer#play()
, SessionPlayer#pause()
) will work as well.
Parameters | |
---|---|
player |
SessionPlayer: the player |
See Also
Protected methods
onAttachedToWindow
protected open fun onAttachedToWindow(): Unit
onDetachedFromWindow
protected open fun onDetachedFromWindow(): Unit
onLayout
protected open fun onLayout(
changed: Boolean,
left: Int,
top: Int,
right: Int,
bottom: Int
): Unit