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