MediaControlView2.java revision 6bd3ab6dc6ad4001c387d7f4a4a2ce954be6ca16 
1/*
2 * Copyright (C) 2017 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.widget;
18
19import android.annotation.IntDef;
20import android.annotation.NonNull;
21import android.annotation.Nullable;
22import android.content.Context;
23import android.media.SessionToken2;
24import android.media.session.MediaController;
25import android.media.update.ApiLoader;
26import android.media.update.MediaControlView2Provider;
27import android.media.update.ViewGroupHelper;
28import android.util.AttributeSet;
29import android.view.View;
30
31import java.lang.annotation.Retention;
32import java.lang.annotation.RetentionPolicy;
33
34// TODO: Use link annotation to refer VideoView2 once VideoView2 became unhidden.
35/**
36 * A View that contains the controls for MediaPlayer2.
37 * It provides a wide range of UI including buttons such as "Play/Pause", "Rewind", "Fast Forward",
38 * "Subtitle", "Full Screen", and it is also possible to add multiple custom buttons.
39 *
40 * <p>
41 * <em> MediaControlView2 can be initialized in two different ways: </em>
42 * 1) When VideoView2 is initialized, it automatically initializes a MediaControlView2 instance and
43 * adds it to the view.
44 * 2) Initialize MediaControlView2 programmatically and add it to a ViewGroup instance.
45 *
46 * In the first option, VideoView2 automatically connects MediaControlView2 to MediaController,
47 * which is necessary to communicate with MediaSession2. In the second option, however, the
48 * developer needs to manually retrieve a MediaController instance and set it to MediaControlView2
49 * by calling setController(MediaController controller).
50 *
51 * <p>
52 * There is no separate method that handles the show/hide behavior for MediaControlView2. Instead,
53 * one can directly change the visibility of this view by calling View.setVisibility(int). The
54 * values supported are View.VISIBLE and View.GONE.
55 * In addition, the following customization is supported:
56 * Set focus to the play/pause button by calling requestPlayButtonFocus().
57 *
58 * <p>
59 * It is also possible to add custom buttons with custom icons and actions inside MediaControlView2.
60 * Those buttons will be shown when the overflow button is clicked.
61 * See VideoView2#setCustomActions for more details on how to add.
62 */
63public class MediaControlView2 extends ViewGroupHelper<MediaControlView2Provider> {
64    /** @hide */
65    @IntDef({
66            BUTTON_PLAY_PAUSE,
67            BUTTON_FFWD,
68            BUTTON_REW,
69            BUTTON_NEXT,
70            BUTTON_PREV,
71            BUTTON_SUBTITLE,
72            BUTTON_FULL_SCREEN,
73            BUTTON_OVERFLOW,
74            BUTTON_MUTE,
75            BUTTON_ASPECT_RATIO,
76            BUTTON_SETTINGS
77    })
78    @Retention(RetentionPolicy.SOURCE)
79    public @interface Button {}
80
81    /**
82     * MediaControlView2 button value for playing and pausing media.
83     * @hide
84     */
85    public static final int BUTTON_PLAY_PAUSE = 1;
86    /**
87     * MediaControlView2 button value for jumping 30 seconds forward.
88     * @hide
89     */
90    public static final int BUTTON_FFWD = 2;
91    /**
92     * MediaControlView2 button value for jumping 10 seconds backward.
93     * @hide
94     */
95    public static final int BUTTON_REW = 3;
96    /**
97     * MediaControlView2 button value for jumping to next media.
98     * @hide
99     */
100    public static final int BUTTON_NEXT = 4;
101    /**
102     * MediaControlView2 button value for jumping to previous media.
103     * @hide
104     */
105    public static final int BUTTON_PREV = 5;
106    /**
107     * MediaControlView2 button value for showing/hiding subtitle track.
108     * @hide
109     */
110    public static final int BUTTON_SUBTITLE = 6;
111    /**
112     * MediaControlView2 button value for toggling full screen.
113     * @hide
114     */
115    public static final int BUTTON_FULL_SCREEN = 7;
116    /**
117     * MediaControlView2 button value for showing/hiding overflow buttons.
118     * @hide
119     */
120    public static final int BUTTON_OVERFLOW = 8;
121    /**
122     * MediaControlView2 button value for muting audio.
123     * @hide
124     */
125    public static final int BUTTON_MUTE = 9;
126    /**
127     * MediaControlView2 button value for adjusting aspect ratio of view.
128     * @hide
129     */
130    public static final int BUTTON_ASPECT_RATIO = 10;
131    /**
132     * MediaControlView2 button value for showing/hiding settings page.
133     * @hide
134     */
135    public static final int BUTTON_SETTINGS = 11;
136
137    public MediaControlView2(@NonNull Context context) {
138        this(context, null);
139    }
140
141    public MediaControlView2(@NonNull Context context, @Nullable AttributeSet attrs) {
142        this(context, attrs, 0);
143    }
144
145    public MediaControlView2(@NonNull Context context, @Nullable AttributeSet attrs,
146            int defStyleAttr) {
147        this(context, attrs, defStyleAttr, 0);
148    }
149
150    public MediaControlView2(@NonNull Context context, @Nullable AttributeSet attrs,
151            int defStyleAttr, int defStyleRes) {
152        super((instance, superProvider, privateProvider) ->
153                ApiLoader.getProvider().createMediaControlView2(
154                        (MediaControlView2) instance, superProvider, privateProvider,
155                        attrs, defStyleAttr, defStyleRes),
156                context, attrs, defStyleAttr, defStyleRes);
157        mProvider.initialize(attrs, defStyleAttr, defStyleRes);
158    }
159
160    /**
161     * Sets MediaSession2 token to control corresponding MediaSession2.
162     */
163    public void setMediaSessionToken(SessionToken2 token) {
164        mProvider.setMediaSessionToken_impl(token);
165    }
166
167    /**
168     * Registers a callback to be invoked when the fullscreen mode should be changed.
169     * @param l The callback that will be run
170     */
171    public void setOnFullScreenListener(OnFullScreenListener l) {
172        mProvider.setOnFullScreenListener_impl(l);
173    }
174
175    /**
176     * @hide TODO: remove once the implementation is revised
177     */
178    public void setController(MediaController controller) {
179        mProvider.setController_impl(controller);
180    }
181
182    /**
183     * Changes the visibility state of an individual button. Default value is View.Visible.
184     *
185     * @param button the {@code Button} assigned to individual buttons
186     * <ul>
187     * <li>{@link #BUTTON_PLAY_PAUSE}
188     * <li>{@link #BUTTON_FFWD}
189     * <li>{@link #BUTTON_REW}
190     * <li>{@link #BUTTON_NEXT}
191     * <li>{@link #BUTTON_PREV}
192     * <li>{@link #BUTTON_SUBTITLE}
193     * <li>{@link #BUTTON_FULL_SCREEN}
194     * <li>{@link #BUTTON_MUTE}
195     * <li>{@link #BUTTON_OVERFLOW}
196     * <li>{@link #BUTTON_ASPECT_RATIO}
197     * <li>{@link #BUTTON_SETTINGS}
198     * </ul>
199     * @param visibility One of {@link #VISIBLE}, {@link #INVISIBLE}, or {@link #GONE}.
200     * @hide
201     */
202    public void setButtonVisibility(@Button int button, @Visibility int visibility) {
203        mProvider.setButtonVisibility_impl(button, visibility);
204    }
205
206    /**
207     *  Requests focus for the play/pause button.
208     */
209    public void requestPlayButtonFocus() {
210        mProvider.requestPlayButtonFocus_impl();
211    }
212
213    @Override
214    protected void onLayout(boolean changed, int l, int t, int r, int b) {
215        mProvider.onLayout_impl(changed, l, t, r, b);
216    }
217
218    /**
219     * Interface definition of a callback to be invoked to inform the fullscreen mode is changed.
220     * Application should handle the fullscreen mode accordingly.
221     */
222    public interface OnFullScreenListener {
223        /**
224         * Called to indicate a fullscreen mode change.
225         */
226        void onFullScreen(View view, boolean fullScreen);
227    }
228}
229