Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 309a61bd authored by Santiago Seifert's avatar Santiago Seifert
Browse files

Converge documentation around media session key

As a collateral effect, this change also fixes some javadocs.

Bug: 237533067
Test: N/A. Javadoc only change.
Change-Id: I960e719cba66056c0ae6db3a265550ac9c17c905
parent 4cc92f8d
Loading
Loading
Loading
Loading
+17 −2
Original line number Diff line number Diff line
@@ -1990,8 +1990,23 @@ public class KeyEvent extends InputEvent implements Parcelable {
    }

    /**
     * Returns whether this key will be sent to the
     * {@link android.media.session.MediaSession.Callback} if not handled.
     * Returns whether this key will be sent to the {@link
     * android.media.session.MediaSession.Callback} if not handled.
     *
     * <p>The following key codes are considered {@link android.media.session.MediaSession} keys:
     *
     * <ul>
     *   <li>{@link #KEYCODE_MEDIA_PLAY}
     *   <li>{@link #KEYCODE_MEDIA_PAUSE}
     *   <li>{@link #KEYCODE_MEDIA_PLAY_PAUSE}
     *   <li>{@link #KEYCODE_HEADSETHOOK}
     *   <li>{@link #KEYCODE_MEDIA_STOP}
     *   <li>{@link #KEYCODE_MEDIA_NEXT}
     *   <li>{@link #KEYCODE_MEDIA_PREVIOUS}
     *   <li>{@link #KEYCODE_MEDIA_REWIND}
     *   <li>{@link #KEYCODE_MEDIA_RECORD}
     *   <li>{@link #KEYCODE_MEDIA_FAST_FORWARD}
     * </ul>
     */
    public static final boolean isMediaSessionKey(int keyCode) {
        switch (keyCode) {
+7 −19
Original line number Diff line number Diff line
@@ -941,27 +941,15 @@ public class AudioManager {
    }

    /**
     * Sends a simulated key event for a media button.
     * To simulate a key press, you must first send a KeyEvent built with a
     * {@link KeyEvent#ACTION_DOWN} action, then another event with the {@link KeyEvent#ACTION_UP}
     * action.
     * Sends a simulated key event for a media button. To simulate a key press, you must first send
     * a KeyEvent built with a {@link KeyEvent#ACTION_DOWN} action, then another event with the
     * {@link KeyEvent#ACTION_UP} action.
     *
     * <p>The key event will be sent to the current media key event consumer which registered with
     * {@link AudioManager#registerMediaButtonEventReceiver(PendingIntent)}.
     * @param keyEvent a {@link KeyEvent} instance whose key code is one of
     *     {@link KeyEvent#KEYCODE_MUTE},
     *     {@link KeyEvent#KEYCODE_HEADSETHOOK},
     *     {@link KeyEvent#KEYCODE_MEDIA_PLAY},
     *     {@link KeyEvent#KEYCODE_MEDIA_PAUSE},
     *     {@link KeyEvent#KEYCODE_MEDIA_PLAY_PAUSE},
     *     {@link KeyEvent#KEYCODE_MEDIA_STOP},
     *     {@link KeyEvent#KEYCODE_MEDIA_NEXT},
     *     {@link KeyEvent#KEYCODE_MEDIA_PREVIOUS},
     *     {@link KeyEvent#KEYCODE_MEDIA_REWIND},
     *     {@link KeyEvent#KEYCODE_MEDIA_RECORD},
     *     {@link KeyEvent#KEYCODE_MEDIA_FAST_FORWARD},
     *     {@link KeyEvent#KEYCODE_MEDIA_CLOSE},
     *     {@link KeyEvent#KEYCODE_MEDIA_EJECT},
     *     or {@link KeyEvent#KEYCODE_MEDIA_AUDIO_TRACK}.
     *
     * @param keyEvent a media session {@link KeyEvent}, as defined by {@link
     *     KeyEvent#isMediaSessionKey}.
     */
    public void dispatchMediaKeyEvent(KeyEvent keyEvent) {
        MediaSessionLegacyHelper helper = MediaSessionLegacyHelper.getHelper(getContext());
+13 −25
Original line number Diff line number Diff line
@@ -220,33 +220,21 @@ import java.util.List;
        return -1;
    }


    /**
     * Send a simulated key event for a media button to be received by the current client.
     * To simulate a key press, you must first send a KeyEvent built with
     * a {@link KeyEvent#ACTION_DOWN} action, then another event with the {@link KeyEvent#ACTION_UP}
     * action.
     * <p>The key event will be sent to the registered receiver
     * (see {@link AudioManager#registerMediaButtonEventReceiver(PendingIntent)}) whose associated
     * {@link RemoteControlClient}'s metadata and playback state is published (there may be
     * none under some circumstances).
     * @param keyEvent a {@link KeyEvent} instance whose key code is one of
     *     {@link KeyEvent#KEYCODE_MUTE},
     *     {@link KeyEvent#KEYCODE_HEADSETHOOK},
     *     {@link KeyEvent#KEYCODE_MEDIA_PLAY},
     *     {@link KeyEvent#KEYCODE_MEDIA_PAUSE},
     *     {@link KeyEvent#KEYCODE_MEDIA_PLAY_PAUSE},
     *     {@link KeyEvent#KEYCODE_MEDIA_STOP},
     *     {@link KeyEvent#KEYCODE_MEDIA_NEXT},
     *     {@link KeyEvent#KEYCODE_MEDIA_PREVIOUS},
     *     {@link KeyEvent#KEYCODE_MEDIA_REWIND},
     *     {@link KeyEvent#KEYCODE_MEDIA_RECORD},
     *     {@link KeyEvent#KEYCODE_MEDIA_FAST_FORWARD},
     *     {@link KeyEvent#KEYCODE_MEDIA_CLOSE},
     *     {@link KeyEvent#KEYCODE_MEDIA_EJECT},
     *     or {@link KeyEvent#KEYCODE_MEDIA_AUDIO_TRACK}.
     * Send a simulated key event for a media button to be received by the current client. To
     * simulate a key press, you must first send a KeyEvent built with a {@link
     * KeyEvent#ACTION_DOWN} action, then another event with the {@link KeyEvent#ACTION_UP} action.
     *
     * <p>The key event will be sent to the registered receiver (see {@link
     * AudioManager#registerMediaButtonEventReceiver(PendingIntent)}) whose associated {@link
     * RemoteControlClient}'s metadata and playback state is published (there may be none under some
     * circumstances).
     *
     * @param keyEvent a media session {@link KeyEvent}, as defined by {@link
     *     KeyEvent#isMediaSessionKey}.
     * @return true if the event was successfully sent, false otherwise.
     * @throws IllegalArgumentException
     * @throws IllegalArgumentException If the provided {@link KeyEvent} is not a media session key,
     *     as defined by {@link KeyEvent#isMediaSessionKey}.
     */
    public boolean sendMediaKeyEvent(KeyEvent keyEvent) throws IllegalArgumentException {
        if (!KeyEvent.isMediaSessionKey(keyEvent.getKeyCode())) {
+4 −17
Original line number Diff line number Diff line
@@ -117,24 +117,11 @@ public abstract class MediaKeyDispatcher {

    /**
     * Gets the map of key code -> {@link KeyEventType} that have been overridden.
     * <p>
     * The list of valid key codes are the following:
     * <ul>
     * <li> {@link KeyEvent#KEYCODE_MEDIA_PLAY}
     * <li> {@link KeyEvent#KEYCODE_MEDIA_PAUSE}
     * <li> {@link KeyEvent#KEYCODE_MEDIA_PLAY_PAUSE}
     * <li> {@link KeyEvent#KEYCODE_MUTE}
     * <li> {@link KeyEvent#KEYCODE_HEADSETHOOK}
     * <li> {@link KeyEvent#KEYCODE_MEDIA_STOP}
     * <li> {@link KeyEvent#KEYCODE_MEDIA_NEXT}
     * <li> {@link KeyEvent#KEYCODE_MEDIA_PREVIOUS}
     * <li> {@link KeyEvent#KEYCODE_VOLUME_UP}
     * <li> {@link KeyEvent#KEYCODE_VOLUME_DOWN}
     * <li> {@link KeyEvent#KEYCODE_VOLUME_MUTE}
     * </ul>
     * @see {@link KeyEvent#isMediaSessionKey(int)}
     *
     * <p>For the list of relevant key codes, see {@link KeyEvent#isMediaSessionKey(int)}.
     */
    @KeyEventType Map<Integer, Integer> getOverriddenKeyEvents() {
    @KeyEventType
    Map<Integer, Integer> getOverriddenKeyEvents() {
        return mOverriddenKeyEvents;
    }