1/*
2 * Copyright (C) 2016 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.support.v17.leanback.media;
18
19import android.support.v17.leanback.widget.OnActionClickedListener;
20import android.support.v17.leanback.widget.PlaybackRowPresenter;
21import android.support.v17.leanback.widget.PlaybackSeekUi;
22import android.support.v17.leanback.widget.Row;
23import android.view.View;
24
25/**
26 * This class represents the UI (e.g. Fragment/Activity) hosting playback controls and
27 * defines the interaction between {@link PlaybackGlue} and the host.
28 * PlaybackGlueHost provides the following functions:
29 * <li>Render UI of PlaybackGlue: {@link #setPlaybackRow(Row)},
30 * {@link #setPlaybackRowPresenter(PlaybackRowPresenter)}.
31 * </li>
32 * <li>Client for fragment/activity onStart/onStop: {@link #setHostCallback(HostCallback)}.
33 * </li>
34 * <li>Auto fade out controls after a short period: {@link #setFadingEnabled(boolean)}.
35 * </li>
36 * <li>Key listener and ActionListener. {@link #setOnKeyInterceptListener(View.OnKeyListener)},
37 * {@link #setOnActionClickedListener(OnActionClickedListener)}.
38 * </li>
39 *
40 * Subclass of PlaybackGlueHost may implement optional interfaces:
41 * <li>{@link SurfaceHolderGlueHost} to provide SurfaceView for video playback.</li>
42 * <li>{@link PlaybackSeekUi} to provide seek UI to glue</li>
43 * These optional interfaces should be accessed by glue in
44 * {@link PlaybackGlue#onAttachedToHost(PlaybackGlueHost)}.
45 */
46public abstract class PlaybackGlueHost {
47    PlaybackGlue mGlue;
48
49    /**
50     * Callbacks triggered by the host(e.g. fragment) hosting the video controls/surface.
51     *
52     * @see #setHostCallback(HostCallback)
53     */
54    public abstract static class HostCallback {
55        /**
56         * Client triggered once the host(fragment) has started.
57         */
58        public void onHostStart() {
59        }
60
61        /**
62         * Client triggered once the host(fragment) has stopped.
63         */
64        public void onHostStop() {
65        }
66
67        /**
68         * Client triggered once the host(fragment) has paused.
69         */
70        public void onHostPause() {
71        }
72
73        /**
74         * Client triggered once the host(fragment) has resumed.
75         */
76        public void onHostResume() {
77        }
78
79        /**
80         * Client triggered once the host(fragment) has been destroyed.
81         */
82        public void onHostDestroy() {
83        }
84    }
85
86    /**
87     * Optional Client that implemented by PlaybackGlueHost to respond to player event.
88     */
89    public static class PlayerCallback {
90        /**
91         * Size of the video changes, the Host should adjust SurfaceView's layout width and height.
92         * @param videoWidth
93         * @param videoHeight
94         */
95        public void onVideoSizeChanged(int videoWidth, int videoHeight) {
96        }
97
98        /**
99         * notify media starts/stops buffering/preparing. The Host could start or stop
100         * progress bar.
101         * @param start True for buffering start, false otherwise.
102         */
103        public void onBufferingStateChanged(boolean start) {
104        }
105
106        /**
107         * notify media has error. The Host could show error dialog.
108         * @param errorCode Optional error code for specific implementation.
109         * @param errorMessage Optional error message for specific implementation.
110         */
111        public void onError(int errorCode, CharSequence errorMessage) {
112        }
113    }
114
115    /**
116     * Enables or disables view fading.  If enabled, the view will be faded in when the
117     * fragment starts and will fade out after a time period.
118     * @deprecated Use {@link #setControlsOverlayAutoHideEnabled(boolean)}
119     */
120    @Deprecated
121    public void setFadingEnabled(boolean enable) {
122    }
123
124    /**
125     * Enables or disables controls overlay auto hidden.  If enabled, the view will be faded out
126     * after a time period.
127     * @param enabled True to enable auto hidden of controls overlay.
128     *
129     */
130    public void setControlsOverlayAutoHideEnabled(boolean enabled) {
131        setFadingEnabled(enabled);
132    }
133
134    /**
135     * Returns true if auto hides controls overlay.
136     * @return True if auto hiding controls overlay.
137     */
138    public boolean isControlsOverlayAutoHideEnabled() {
139        return false;
140    }
141
142    /**
143     * Fades out the playback overlay immediately.
144     * @deprecated Call {@link #hideControlsOverlay(boolean)}
145     */
146    @Deprecated
147    public void fadeOut() {
148    }
149
150    /**
151     * Returns true if controls overlay is visible, false otherwise.
152     *
153     * @return True if controls overlay is visible, false otherwise.
154     * @see #showControlsOverlay(boolean)
155     * @see #hideControlsOverlay(boolean)
156     */
157    public boolean isControlsOverlayVisible() {
158        return true;
159    }
160
161    /**
162     * Hide controls overlay.
163     *
164     * @param runAnimation True to run animation, false otherwise.
165     */
166    public void hideControlsOverlay(boolean runAnimation) {
167    }
168
169    /**
170     * Show controls overlay.
171     *
172     * @param runAnimation True to run animation, false otherwise.
173     */
174    public void showControlsOverlay(boolean runAnimation) {
175    }
176
177    /**
178     * Sets the {@link android.view.View.OnKeyListener} on the host. This would trigger
179     * the listener when a {@link android.view.KeyEvent} is unhandled by the host.
180     */
181    public void setOnKeyInterceptListener(View.OnKeyListener onKeyListener) {
182    }
183
184    /**
185     * Sets the {@link View.OnClickListener} on this fragment.
186     */
187    public void setOnActionClickedListener(OnActionClickedListener listener) {}
188
189    /**
190     * Sets the host {@link HostCallback} callback on the host. This method should only be called
191     * by {@link PlaybackGlue}. App should not directly call this method, app should override
192     * {@link PlaybackGlue#onHostStart()} etc.
193     */
194    public void setHostCallback(HostCallback callback) {
195    }
196
197    /**
198     * Notifies host about a change so it can update the view.
199     */
200    public void notifyPlaybackRowChanged() {}
201
202    /**
203     * Sets {@link PlaybackRowPresenter} for rendering the playback controls.
204     */
205    public void setPlaybackRowPresenter(PlaybackRowPresenter presenter) {}
206
207    /**
208     * Sets the {@link Row} that represents the information on control items that needs
209     * to be rendered.
210     */
211    public void setPlaybackRow(Row row) {}
212
213    final void attachToGlue(PlaybackGlue glue) {
214        if (mGlue != null) {
215            mGlue.onDetachedFromHost();
216        }
217        mGlue = glue;
218        if (mGlue != null) {
219            mGlue.onAttachedToHost(this);
220        }
221    }
222
223    /**
224     * Implemented by PlaybackGlueHost for responding to player events. Such as showing a spinning
225     * wheel progress bar when {@link PlayerCallback#onBufferingStateChanged(boolean)}.
226     * @return PlayerEventCallback that Host supports, null if not supported.
227     */
228    public PlayerCallback getPlayerCallback() {
229        return null;
230    }
231
232}
233