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 
17 package androidx.leanback.media;
18 
19 import android.view.View;
20 
21 import androidx.leanback.widget.OnActionClickedListener;
22 import androidx.leanback.widget.PlaybackRowPresenter;
23 import androidx.leanback.widget.PlaybackSeekUi;
24 import 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  */
47 public 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          */
onHostStart()59         public void onHostStart() {
60         }
61 
62         /**
63          * Client triggered once the host(fragment) has stopped.
64          */
onHostStop()65         public void onHostStop() {
66         }
67 
68         /**
69          * Client triggered once the host(fragment) has paused.
70          */
onHostPause()71         public void onHostPause() {
72         }
73 
74         /**
75          * Client triggered once the host(fragment) has resumed.
76          */
onHostResume()77         public void onHostResume() {
78         }
79 
80         /**
81          * Client triggered once the host(fragment) has been destroyed.
82          */
onHostDestroy()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          */
onVideoSizeChanged(int videoWidth, int videoHeight)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          */
onBufferingStateChanged(boolean start)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          */
onError(int errorCode, CharSequence errorMessage)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
setFadingEnabled(boolean enable)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      */
setControlsOverlayAutoHideEnabled(boolean enabled)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      */
isControlsOverlayAutoHideEnabled()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
fadeOut()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      */
isControlsOverlayVisible()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      */
hideControlsOverlay(boolean runAnimation)167     public void hideControlsOverlay(boolean runAnimation) {
168     }
169 
170     /**
171      * Show controls overlay.
172      *
173      * @param runAnimation True to run animation, false otherwise.
174      */
showControlsOverlay(boolean runAnimation)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      */
setOnKeyInterceptListener(View.OnKeyListener onKeyListener)182     public void setOnKeyInterceptListener(View.OnKeyListener onKeyListener) {
183     }
184 
185     /**
186      * Sets the {@link View.OnClickListener} on this fragment.
187      */
setOnActionClickedListener(OnActionClickedListener listener)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      */
setHostCallback(HostCallback callback)195     public void setHostCallback(HostCallback callback) {
196     }
197 
198     /**
199      * Notifies host about a change so it can update the view.
200      */
notifyPlaybackRowChanged()201     public void notifyPlaybackRowChanged() {}
202 
203     /**
204      * Sets {@link PlaybackRowPresenter} for rendering the playback controls.
205      */
setPlaybackRowPresenter(PlaybackRowPresenter presenter)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      */
setPlaybackRow(Row row)212     public void setPlaybackRow(Row row) {}
213 
attachToGlue(PlaybackGlue glue)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      */
getPlayerCallback()229     public PlayerCallback getPlayerCallback() {
230         return null;
231     }
232 
233 }
234