diff --git a/library/src/main/java/com/google/android/exoplayer2/ui/PlaybackControlView.java b/library/src/main/java/com/google/android/exoplayer2/ui/PlaybackControlView.java
index 03ef4e2f33..29772dcc89 100644
--- a/library/src/main/java/com/google/android/exoplayer2/ui/PlaybackControlView.java
+++ b/library/src/main/java/com/google/android/exoplayer2/ui/PlaybackControlView.java
@@ -38,17 +38,109 @@ import java.util.Formatter;
import java.util.Locale;
/**
- * A view to control video playback of an {@link ExoPlayer}.
- *
- * By setting the view attribute {@code controller_layout_id} a layout resource to use can
- * be customized. All views are optional but if the buttons should have an appropriate logic
- * assigned, the id of the views in the layout have to match the expected ids as follows:
+ * A view for controlling {@link ExoPlayer} instances.
+ *
+ * A PlaybackControlView can be customized by setting attributes (or calling corresponding methods),
+ * overriding the view's layout file or by specifying a custom view layout file, as outlined below.
*
+ *
Attributes
+ * The following attributes can be set on a PlaybackControlView when used in a layout XML file:
+ *
*
- * - Playback: {@code exo_play}, {@code exo_pause}, {@code exo_ffwd}, {@code exo_rew}.
- * - Progress: {@code exo_progress}, {@code exo_time_current}, {@code exo_time}.
- * - Playlist navigation: {@code exo_previous}, {@code exo_next}.
+ * - {@code show_timeout} - The time between the last user interaction and the controls
+ * being automatically hidden, in milliseconds. Use zero if the controls should not
+ * automatically timeout.
+ *
+ * - Corresponding method: {@link #setShowTimeoutMs(int)}
+ * - Default: {@link #DEFAULT_SHOW_TIMEOUT_MS}
+ *
+ *
+ * - {@code rewind_increment} - The duration of the rewind applied when the user taps the
+ * rewind button, in milliseconds. Use zero to disable the rewind button.
+ *
+ * - Corresponding method: {@link #setRewindIncrementMs(int)}
+ * - Default: {@link #DEFAULT_REWIND_MS}
+ *
+ *
+ * - {@code fastforward_increment} - Like {@code rewind_increment}, but for fast forward.
+ *
+ * - Corresponding method: {@link #setFastForwardIncrementMs(int)}
+ * - Default: {@link #DEFAULT_FAST_FORWARD_MS}
+ *
+ *
+ * - {@code controller_layout_id} - Specifies the id of the layout to be inflated. See
+ * below for more details.
+ *
+ * - Corresponding method: None
+ * - Default: {@code R.id.exo_playback_control_view}
+ *
+ *
*
+ *
+ * Overriding the layout file
+ * To customize the layout of PlaybackControlView throughout your app, or just for certain
+ * configurations, you can define {@code exo_playback_control_view.xml} layout files in your
+ * application {@code res/layout*} directories. These layouts will override the one provided by the
+ * ExoPlayer library, and will be inflated for use by PlaybackControlView. The view identifies and
+ * binds its children by looking for the following ids:
+ *
+ *
+ * - {@code exo_play} - The play button.
+ *
+ * - Type: {@link View}
+ *
+ *
+ * - {@code exo_pause} - The pause button.
+ *
+ * - Type: {@link View}
+ *
+ *
+ * - {@code exo_ffwd} - The fast forward button.
+ *
+ * - Type: {@link View}
+ *
+ *
+ * - {@code exo_rew} - The rewind button.
+ *
+ * - Type: {@link View}
+ *
+ *
+ * - {@code exo_prev} - The previous track button.
+ *
+ * - Type: {@link View}
+ *
+ *
+ * - {@code exo_next} - The next track button.
+ *
+ * - Type: {@link View}
+ *
+ *
+ * - {@code exo_position} - Text view displaying the current playback position.
+ *
+ * - Type: {@link TextView}
+ *
+ *
+ * - {@code exo_duration} - Text view displaying the current media duration.
+ *
+ * - Type: {@link TextView}
+ *
+ *
+ * - {@code exo_progress} - Seek bar that's updated during playback and allows seeking.
+ *
+ * - Type: {@link SeekBar}
+ *
+ *
+ *
+ *
+ * All child views are optional and so can be omitted if not required, however where defined they
+ * must be of the expected type.
+ *
+ *
Specifying a custom layout file
+ * Defining your own {@code exo_playback_control_view.xml} is useful to customize the layout of
+ * PlaybackControlView throughout your application. It's also possible to customize the layout for a
+ * single instance in a layout file. This is achieved by setting the {@code controller_layout_id}
+ * attribute on a PlaybackControlView. This will cause the specified layout to be inflated instead
+ * of {@code exo_playback_control_view.xml} for only the instance on which the attribute is set.
*/
public class PlaybackControlView extends FrameLayout {
@@ -78,8 +170,8 @@ public class PlaybackControlView extends FrameLayout {
private final View pauseButton;
private final View fastForwardButton;
private final View rewindButton;
- private final TextView time;
- private final TextView timeCurrent;
+ private final TextView durationView;
+ private final TextView positionView;
private final SeekBar progressBar;
private final StringBuilder formatBuilder;
private final Formatter formatter;
@@ -144,8 +236,8 @@ public class PlaybackControlView extends FrameLayout {
componentListener = new ComponentListener();
LayoutInflater.from(context).inflate(controllerLayoutId, this);
- time = (TextView) findViewById(R.id.exo_time);
- timeCurrent = (TextView) findViewById(R.id.exo_time_current);
+ durationView = (TextView) findViewById(R.id.exo_duration);
+ positionView = (TextView) findViewById(R.id.exo_position);
progressBar = (SeekBar) findViewById(R.id.exo_progress);
if (progressBar != null) {
progressBar.setOnSeekBarChangeListener(componentListener);
@@ -215,7 +307,8 @@ public class PlaybackControlView extends FrameLayout {
/**
* Sets the rewind increment in milliseconds.
*
- * @param rewindMs The rewind increment in milliseconds.
+ * @param rewindMs The rewind increment in milliseconds. A non-positive value will cause the
+ * rewind button to be disabled.
*/
public void setRewindIncrementMs(int rewindMs) {
this.rewindMs = rewindMs;
@@ -225,7 +318,8 @@ public class PlaybackControlView extends FrameLayout {
/**
* Sets the fast forward increment in milliseconds.
*
- * @param fastForwardMs The fast forward increment in milliseconds.
+ * @param fastForwardMs The fast forward increment in milliseconds. A non-positive value will
+ * cause the fast forward button to be disabled.
*/
public void setFastForwardIncrementMs(int fastForwardMs) {
this.fastForwardMs = fastForwardMs;
@@ -355,11 +449,11 @@ public class PlaybackControlView extends FrameLayout {
}
long duration = player == null ? 0 : player.getDuration();
long position = player == null ? 0 : player.getCurrentPosition();
- if (time != null) {
- time.setText(stringForTime(duration));
+ if (durationView != null) {
+ durationView.setText(stringForTime(duration));
}
- if (timeCurrent != null && !dragging) {
- timeCurrent.setText(stringForTime(position));
+ if (positionView != null && !dragging) {
+ positionView.setText(stringForTime(position));
}
if (progressBar != null) {
@@ -541,8 +635,8 @@ public class PlaybackControlView extends FrameLayout {
@Override
public void onProgressChanged(SeekBar seekBar, int progress, boolean fromUser) {
- if (fromUser && timeCurrent != null) {
- timeCurrent.setText(stringForTime(positionValue(progress)));
+ if (fromUser && positionView != null) {
+ positionView.setText(stringForTime(positionValue(progress)));
}
}
diff --git a/library/src/main/java/com/google/android/exoplayer2/ui/SimpleExoPlayerView.java b/library/src/main/java/com/google/android/exoplayer2/ui/SimpleExoPlayerView.java
index 90a15da12c..d494ab2a10 100644
--- a/library/src/main/java/com/google/android/exoplayer2/ui/SimpleExoPlayerView.java
+++ b/library/src/main/java/com/google/android/exoplayer2/ui/SimpleExoPlayerView.java
@@ -48,7 +48,110 @@ import com.google.android.exoplayer2.util.Assertions;
import java.util.List;
/**
- * Displays a video stream.
+ * A high level view for {@link SimpleExoPlayer} media playbacks. It displays video, subtitles and
+ * album art during playback, and displays playback controls using a {@link PlaybackControlView}.
+ *
+ * A SimpleExoPlayerView can be customized by setting attributes (or calling corresponding methods),
+ * overriding the view's layout file or by specifying a custom view layout file, as outlined below.
+ *
+ *
Attributes
+ * The following attributes can be set on a SimpleExoPlayerView when used in a layout XML file:
+ *
+ *
+ * - {@code use_artwork} - Whether artwork is used if available in audio streams.
+ *
+ * - Corresponding method: {@link #setUseArtwork(boolean)}
+ * - Default: {@code true}
+ *
+ *
+ * - {@code use_controller} - Whether playback controls are displayed.
+ *
+ * - Corresponding method: {@link #setUseController(boolean)}
+ * - Default: {@code true}
+ *
+ *
+ * - {@code resize_mode} - Controls how video and album art is resized within the view.
+ * Valid values are {@code fit}, {@code fixed_width}, {@code fixed_height} and {@code fill}.
+ *
+ * - Corresponding method: {@link #setResizeMode(int)}
+ * - Default: {@code fit}
+ *
+ *
+ * - {@code surface_type} - The type of surface view used for video playbacks. Valid
+ * values are {@code surface_view}, {@code texture_view} and {@code none}. Using {@code none}
+ * is recommended for audio only applications, since creating the surface can be expensive.
+ * Using {@code surface_view} is recommended for video applications.
+ *
+ * - Corresponding method: None
+ * - Default: {@code surface_view}
+ *
+ *
+ * - {@code player_layout_id} - Specifies the id of the layout to be inflated. See below
+ * for more details.
+ *
+ * - Corresponding method: None
+ * - Default: {@code R.id.exo_simple_player_view}
+ *
+ * - {@code controller_layout_id} - Specifies the id of the layout resource to be
+ * inflated by the child {@link PlaybackControlView}. See below for more details.
+ *
+ * - Corresponding method: None
+ * - Default: {@code R.id.exo_playback_control_view}
+ *
+ * - All attributes that can be set on a {@link PlaybackControlView} can also be set on a
+ * SimpleExoPlayerView, and will be propagated to the inflated {@link PlaybackControlView}.
+ *
+ *
+ *
+ * Overriding the layout file
+ * To customize the layout of SimpleExoPlayerView throughout your app, or just for certain
+ * configurations, you can define {@code exo_simple_player_view.xml} layout files in your
+ * application {@code res/layout*} directories. These layouts will override the one provided by the
+ * ExoPlayer library, and will be inflated for use by SimpleExoPlayerView. The view identifies and
+ * binds its children by looking for the following ids:
+ *
+ *
+ * - {@code exo_content_frame} - A frame whose aspect ratio is resized based on the video
+ * or album art of the media being played, and the configured {@code resize_mode}. The video
+ * surface view is inflated into this frame as its first child.
+ *
+ * - Type: {@link AspectRatioFrameLayout}
+ *
+ *
+ * - {@code exo_shutter} - A view that's made visible when video should be hidden. This
+ * view is typically an opaque view that covers the video surface view, thereby obscuring it
+ * when visible.
+ *
+ * - Type: {@link View}
+ *
+ *
+ * - {@code exo_subtitles} - Displays subtitles.
+ *
+ * - Type: {@link SubtitleView}
+ *
+ *
+ * - {@code exo_artwork} - Displays album art.
+ *
+ * - Type: {@link ImageView}
+ *
+ *
+ * - {@code exo_controller_placeholder} - A placeholder that's replaced with the inflated
+ * {@link PlaybackControlView}.
+ *
+ * - Type: {@link View}
+ *
+ *
+ *
+ *
+ * All child views are optional and so can be omitted if not required, however where defined they
+ * must be of the expected type.
+ *
+ *
Specifying a custom layout file
+ * Defining your own {@code exo_simple_player_view.xml} is useful to customize the layout of
+ * SimpleExoPlayerView throughout your application. It's also possible to customize the layout for a
+ * single instance in a layout file. This is achieved by setting the {@code player_layout_id}
+ * attribute on a SimpleExoPlayerView. This will cause the specified layout to be inflated instead
+ * of {@code exo_simple_player_view.xml} for only the instance on which the attribute is set.
*/
@TargetApi(16)
public final class SimpleExoPlayerView extends FrameLayout {
@@ -145,24 +248,19 @@ public final class SimpleExoPlayerView extends FrameLayout {
}
// Playback control view.
- PlaybackControlView controller = (PlaybackControlView) findViewById(R.id.exo_controller);
- if (controller != null) {
- controller.setRewindIncrementMs(rewindMs);
- controller.setFastForwardIncrementMs(fastForwardMs);
+ View controllerPlaceholder = findViewById(R.id.exo_controller_placeholder);
+ if (controllerPlaceholder != null) {
+ // Note: rewindMs and fastForwardMs are passed via attrs, so we don't need to make explicit
+ // calls to set them.
+ this.controller = new PlaybackControlView(context, attrs);
+ controller.setLayoutParams(controllerPlaceholder.getLayoutParams());
+ ViewGroup parent = ((ViewGroup) controllerPlaceholder.getParent());
+ int controllerIndex = parent.indexOfChild(controllerPlaceholder);
+ parent.removeView(controllerPlaceholder);
+ parent.addView(controller, controllerIndex);
} else {
- View controllerPlaceholder = findViewById(R.id.exo_controller_placeholder);
- if (controllerPlaceholder != null) {
- // Note: rewindMs and fastForwardMs are passed via attrs, so we don't need to make explicit
- // calls to set them.
- controller = new PlaybackControlView(context, attrs);
- controller.setLayoutParams(controllerPlaceholder.getLayoutParams());
- ViewGroup parent = ((ViewGroup) controllerPlaceholder.getParent());
- int controllerIndex = parent.indexOfChild(controllerPlaceholder);
- parent.removeView(controllerPlaceholder);
- parent.addView(controller, controllerIndex);
- }
+ this.controller = null;
}
- this.controller = controller;
this.controllerShowTimeoutMs = controller != null ? controllerShowTimeoutMs : 0;
this.useController = useController && controller != null;
hideController();
diff --git a/library/src/main/res/layout/exo_playback_control_view.xml b/library/src/main/res/layout/exo_playback_control_view.xml
index b5f5022ca9..2cf8b132ac 100644
--- a/library/src/main/res/layout/exo_playback_control_view.xml
+++ b/library/src/main/res/layout/exo_playback_control_view.xml
@@ -53,7 +53,7 @@
android:layout_height="wrap_content"
android:orientation="horizontal">
-
-