loliball/media
1
0
Fork 0
mirror of https://github.com/androidx/media.git synced 2025-05-11 09:39:52 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Explicitly document most Player.Listener methods in terms of getters

Browse Source 
This makes it implicitly clear that if the value of a getter changes due
to a change in command availability then the listener will be invoked,
without needing to explicitly document every command on every listener
method.

#minor-release

PiperOrigin-RevId: 503178383
This commit is contained in:
ibaker 2023-01-19 16:56:32 +00:00 committed by christosts
parent ad51d1ca87
commit aa23920e14
1 changed files with 23 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
library/common/src/main/java/com/google/android/exoplayer2/Player.java
View File

@ -601,9 +601,15 @@ public interface Player {
}
/**
* Listener of all changes in the Player.
* Listener for changes in a {@link Player}.
*
* <p>All methods have no-op default implementations to allow selective overrides.
*
* <p>If the return value of a {@link Player} getter changes due to a change in {@linkplain
* #onAvailableCommandsChanged(Commands) command availability}, the corresponding listener
* method(s) will be invoked. If the return value of a {@link Player} getter does not change
* because the corresponding command is {@linkplain #onAvailableCommandsChanged(Commands) not
* available}, the corresponding listener method will not be invoked.
*/
interface Listener {
@ -613,9 +619,6 @@ public interface Player {
* <p>State changes and events that happen within one {@link Looper} message queue iteration are
* reported together and only after all individual callbacks were triggered.
*
* <p>Only state changes represented by {@linkplain Event events} are reported through this
* method.
*
* <p>Listeners should prefer this method over individual callbacks in the following cases:
*
* <ul>
@ -641,7 +644,7 @@ public interface Player {
default void onEvents(Player player, Events events) {}
/**
* Called when the timeline has been refreshed.
* Called when the value of {@link Player#getCurrentTimeline()} changes.
*
* <p>Note that the current {@link MediaItem} or playback position may change as a result of a
* timeline change. If playback can't continue smoothly because of this timeline change, a
@ -660,9 +663,8 @@ public interface Player {
* Called when playback transitions to a media item or starts repeating a media item according
* to the current {@link #getRepeatMode() repeat mode}.
*
* <p>Note that this callback is also called when the playlist becomes non-empty or empty as a
* consequence of a playlist change or {@linkplain #onAvailableCommandsChanged(Commands) a
* change in available commands}.
* <p>Note that this callback is also called when the value of {@link #getCurrentTimeline()}
* becomes non-empty or empty.
*
* <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
* other events that happen in the same {@link Looper} message queue iteration.
@ -674,7 +676,7 @@ public interface Player {
@Nullable MediaItem mediaItem, @MediaItemTransitionReason int reason) {}
/**
* Called when the tracks change.
* Called when the value of {@link Player#getCurrentTracks()} changes.
*
* <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
* other events that happen in the same {@link Looper} message queue iteration.
@ -684,14 +686,7 @@ public interface Player {
default void onTracksChanged(Tracks tracks) {}
/**
* Called when the combined {@link MediaMetadata} changes.
*
* <p>The provided {@link MediaMetadata} is a combination of the {@link MediaItem#mediaMetadata
* MediaItem metadata}, the static metadata in the media's {@link Format#metadata Format}, and
* any timed metadata that has been parsed from the media and output via {@link
* Listener#onMetadata(Metadata)}. If a field is populated in the {@link
* MediaItem#mediaMetadata}, it will be prioritised above the same field coming from static or
* timed metadata.
* Called when the value of {@link Player#getMediaMetadata()} changes.
*
* <p>This method may be called multiple times in quick succession.
*
@ -703,7 +698,7 @@ public interface Player {
default void onMediaMetadataChanged(MediaMetadata mediaMetadata) {}
/**
* Called when the playlist {@link MediaMetadata} changes.
* Called when the value of {@link Player#getPlaylistMetadata()} changes.
*
* <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
* other events that happen in the same {@link Looper} message queue iteration.
@ -869,10 +864,10 @@ public interface Player {
PositionInfo oldPosition, PositionInfo newPosition, @DiscontinuityReason int reason) {}
/**
* Called when the current playback parameters change. The playback parameters may change due to
* a call to {@link #setPlaybackParameters(PlaybackParameters)}, or the player itself may change
* them (for example, if audio playback switches to passthrough or offload mode, where speed
* adjustment is no longer possible).
* Called when the value of {@link #getPlaybackParameters()} changes. The playback parameters
* may change due to a call to {@link #setPlaybackParameters(PlaybackParameters)}, or the player
* itself may change them (for example, if audio playback switches to passthrough or offload
* mode, where speed adjustment is no longer possible).
*
* <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
* other events that happen in the same {@link Looper} message queue iteration.
@ -931,7 +926,7 @@ public interface Player {
default void onAudioSessionIdChanged(int audioSessionId) {}
/**
* Called when the audio attributes change.
* Called when the value of {@link #getAudioAttributes()} changes.
*
* <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
* other events that happen in the same {@link Looper} message queue iteration.
@ -941,7 +936,7 @@ public interface Player {
default void onAudioAttributesChanged(AudioAttributes audioAttributes) {}
/**
* Called when the volume changes.
* Called when the value of {@link #getVolume()} changes.
*
* <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
* other events that happen in the same {@link Looper} message queue iteration.
@ -971,7 +966,7 @@ public interface Player {
default void onDeviceInfoChanged(DeviceInfo deviceInfo) {}
/**
* Called when the device volume or mute state changes.
* Called when the value of {@link #getDeviceVolume()} or {@link #isDeviceMuted()} changes.
*
* <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
* other events that happen in the same {@link Looper} message queue iteration.
@ -1015,7 +1010,7 @@ public interface Player {
default void onRenderedFirstFrame() {}
/**
* Called when there is a change in the {@linkplain Cue cues}.
* Called when the value of {@link #getCurrentCues()} changes.
*
* <p>Both this method and {@link #onCues(CueGroup)} are called when there is a change in the
* cues. You should only implement one or the other.
@ -1029,7 +1024,7 @@ public interface Player {
default void onCues(List<Cue> cues) {}
/**
* Called when there is a change in the {@link CueGroup}.
* Called when the value of {@link #getCurrentCues()} changes.
*
* <p>Both this method and {@link #onCues(List)} are called when there is a change in the cues.
* You should only implement one or the other.
@ -1393,7 +1388,7 @@ public interface Player {
/**
* Commands that indicate which method calls are currently permitted on a particular {@code
* Player} instance, and which corresponding {@link Player.Listener} methods will be invoked.
* Player} instance.
*
* <p>The currently available commands can be inspected with {@link #getAvailableCommands()} and
* {@link #isCommandAvailable(int)}.