More TransportMediator documentation.
Change-Id: I9e905384461e0786c7b439776ccdd453cd1b34c0
diff --git a/v4/java/android/support/v4/media/TransportController.java b/v4/java/android/support/v4/media/TransportController.java
index e78629b..fdbb3f8 100644
--- a/v4/java/android/support/v4/media/TransportController.java
+++ b/v4/java/android/support/v4/media/TransportController.java
@@ -17,28 +17,76 @@
package android.support.v4.media;
/**
- * Base interface to controlling a media transport.
+ * Base interface to controlling a media transport. This is the
+ * interface for implementing things like on-screen controls: it
+ * allows them to request changes in playback, retrieve the current
+ * playback state, and monitor for changes to the playback state.
*/
public abstract class TransportController {
+ /**
+ * Start listening to changes in playback state.
+ */
public abstract void registerStateListener(TransportStateListener listener);
+ /**
+ * Stop listening to changes in playback state.
+ */
public abstract void unregisterStateListener(TransportStateListener listener);
+ /**
+ * Request that the player start its playback at its current position.
+ */
public abstract void startPlaying();
+ /**
+ * Request that the player pause its playback and stay at its current position.
+ */
public abstract void pausePlaying();
+ /**
+ * Request that the player stop its playback; it may clear its state in whatever
+ * way is appropriate.
+ */
public abstract void stopPlaying();
+ /**
+ * Retrieve the total duration of the media stream, in milliseconds.
+ */
public abstract int getDuration();
+ /**
+ * Retrieve the current playback location in the media stream, in milliseconds.
+ */
public abstract int getCurrentPosition();
+ /**
+ * Move to a new location in the media stream.
+ * @param pos Position to move to, in milliseconds.
+ */
public abstract void seekTo(int pos);
+ /**
+ * Return whether the player is currently playing its stream.
+ */
public abstract boolean isPlaying();
+ /**
+ * Retrieve amount, in percentage (0-100), that the media stream has been buffered
+ * on to the local device. Return 100 if the stream is always local.
+ */
public abstract int getBufferPercentage();
+ /**
+ * Retrieve the flags for the media transport control buttons that this transport supports.
+ * Result is a combination of the following flags:
+ * {@link TransportMediator#FLAG_KEY_MEDIA_PREVIOUS},
+ * {@link TransportMediator#FLAG_KEY_MEDIA_REWIND},
+ * {@link TransportMediator#FLAG_KEY_MEDIA_PLAY},
+ * {@link TransportMediator#FLAG_KEY_MEDIA_PLAY_PAUSE},
+ * {@link TransportMediator#FLAG_KEY_MEDIA_PAUSE},
+ * {@link TransportMediator#FLAG_KEY_MEDIA_STOP},
+ * {@link TransportMediator#FLAG_KEY_MEDIA_FAST_FORWARD},
+ * {@link TransportMediator#FLAG_KEY_MEDIA_NEXT}
+ */
public abstract int getTransportControlFlags();
}
diff --git a/v4/java/android/support/v4/media/TransportMediator.java b/v4/java/android/support/v4/media/TransportMediator.java
index a3fba9a..8ea16a9 100644
--- a/v4/java/android/support/v4/media/TransportMediator.java
+++ b/v4/java/android/support/v4/media/TransportMediator.java
@@ -35,6 +35,15 @@
* is represented by a single {@link TransportPerformer} that must be supplied to
* this class. On-screen controls that want to control and show the state of the
* player should do this through calls to the {@link TransportController} interface.
+ *
+ * <p>Here is a simple but fairly complete sample of a video player that is built
+ * around this class. Note that the MediaController class used here is not the one
+ * included in the standard Android framework, but a custom implementation. Real
+ * applications often implement their own transport controls, or you can copy the
+ * implementation here out of Support4Demos.</p>
+ *
+ * {@sample development/samples/Support4Demos/src/com/example/android/supportv4/media/TransportControllerActivity.java
+ * complete}
*/
public class TransportMediator extends TransportController {
final Context mContext;
diff --git a/v4/java/android/support/v4/media/TransportPerformer.java b/v4/java/android/support/v4/media/TransportPerformer.java
index ba55ed2..98bbbaa 100644
--- a/v4/java/android/support/v4/media/TransportPerformer.java
+++ b/v4/java/android/support/v4/media/TransportPerformer.java
@@ -20,26 +20,58 @@
import android.view.KeyEvent;
/**
- * Class through which you receive information about media transport actions.
- * These may either come from key events dispatched directly to your UI, or
+ * Implemented by the playback side of the media system, to respond to
+ * requests to perform actions and to retrieve its current state. These
+ * requests may either come from key events dispatched directly to your UI, or
* events sent over a media button event receiver that this class keeps active
* while your window is in focus.
*/
public abstract class TransportPerformer {
+ /**
+ * Request to start playback on the media, resuming from whatever current state
+ * (position etc) it is in.
+ */
public abstract void onStart();
- public abstract void onStop();
-
+ /**
+ * Request to pause playback of the media, staying at the current playback position
+ * and other state so a later call to {@link #onStart()} will resume at the same place.
+ */
public abstract void onPause();
+ /**
+ * Request to completely stop playback of the media, clearing whatever state the
+ * player thinks is appropriate.
+ */
+ public abstract void onStop();
+
+ /**
+ * Request to return the duration of the current media, in milliseconds.
+ */
public abstract int onGetDuration();
+ /**
+ * Request to return the current playback position, in milliseconds.
+ */
public abstract int onGetCurrentPosition();
+ /**
+ * Request to move the current playback position.
+ * @param pos New position to move to, in milliseconds.
+ */
public abstract void onSeekTo(int pos);
+ /**
+ * Request to find out whether the player is currently playing its media.
+ */
public abstract boolean onIsPlaying();
+ /**
+ * Request to find out how much of the media has been buffered on the local device.
+ * @return Return a percentage (0-100) indicating how much of the total data
+ * has been buffered. The default implementation returns 100, meaning the content
+ * is always on the local device.
+ */
public int onGetBufferPercentage() {
return 100;
}
@@ -114,7 +146,7 @@
}
/**
- * Report that a media button has been pressed. This is like
+ * Report that a media button has been released. This is like
* {@link KeyEvent.Callback#onKeyUp(int, android.view.KeyEvent)} but
* will only deliver media keys. The default implementation does nothing.
* @param keyCode The code of the media key.
diff --git a/v4/java/android/support/v4/media/TransportStateListener.java b/v4/java/android/support/v4/media/TransportStateListener.java
index 2a23f75..384cca2 100644
--- a/v4/java/android/support/v4/media/TransportStateListener.java
+++ b/v4/java/android/support/v4/media/TransportStateListener.java
@@ -1,5 +1,25 @@
+/*
+ * Copyright (C) 2013 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
package android.support.v4.media;
+/**
+ * A listener for playback changes that can be registered with
+ * {@link TransportController}.
+ */
public class TransportStateListener {
/**
* The play state of the transport changed. Use
