1 /*
2  * Copyright (C) 2013 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 com.android.camera.filmstrip;
18 
19 import android.view.View;
20 
21 import com.android.camera.app.CameraAppUI;
22 import com.android.camera.data.FilmstripItem;
23 
24 /**
25  * An interface which defines the controller of filmstrip.
26  * A filmstrip has 4 states:
27  * <ol>
28  *     <li>Filmstrip</li>
29  *     Images are scaled down and the user can navigate quickly by swiping.
30  *     Action bar and controls are shown.
31  *     <li>Full-screen</li>
32  *     One single image occupies the whole screen. Action bar and controls are
33  *     hidden.
34  *     <li>Zoom view</li>
35  *     Zoom in to view the details of one single image.
36  * </ol>
37  * Only the following state transitions can happen:
38  * <ol>
39  * <li>filmstrip --> full-screen</li>
40  * <li>full-screen --> filmstrip</li>
41  * <li>full-screen --> full-screen with UIs</li>
42  * <li>full-screen --> zoom view</li>
43  * <li>zoom view --> full-screen</li>
44  * </ol>
45  *
46  * Upon entering/leaving each of the states, the
47  * {@link com.android.camera.filmstrip.FilmstripController.FilmstripListener} will be notified.
48  */
49 public interface FilmstripController {
50 
51     /**
52      * Sets the listener for filmstrip events.
53      *
54      * @param listener
55      */
setListener(FilmstripListener listener)56     public void setListener(FilmstripListener listener);
57 
58     /**
59      * Sets the gap width between each images on the filmstrip.
60      *
61      * @param imageGap The gap width in pixels.
62      */
setImageGap(int imageGap)63     public void setImageGap(int imageGap);
64 
65     /**
66      * @return The ID of the current item, or -1.
67      */
getCurrentAdapterIndex()68     public int getCurrentAdapterIndex();
69 
70     /**
71      * Sets the {@link FilmstripDataAdapter}.
72      */
setDataAdapter(FilmstripDataAdapter adapter)73     public void setDataAdapter(FilmstripDataAdapter adapter);
74 
75     /**
76      * Returns whether the filmstrip is in filmstrip mode.
77      */
inFilmstrip()78     public boolean inFilmstrip();
79 
80     /**
81      * @return Whether the filmstrip is in full-screen mode.
82      */
inFullScreen()83     public boolean inFullScreen();
84 
85     /**
86      * @return Whether the filmstrip is in scaling animation.
87      */
isScaling()88     public boolean isScaling();
89 
90     /**
91      * Scrolls the filmstrip horizontally.
92      *
93      * @param deltaX The distance in pixel The filmstrip will be scrolled by.
94      */
scroll(float deltaX)95     public void scroll(float deltaX);
96 
97     /**
98      * Flings the filmstrip horizontally.
99      *
100      * @param velocity
101      */
fling(float velocity)102     public void fling(float velocity);
103 
104     /**
105      * Scrolls the filmstrip horizontally to a specific position.
106      *
107      * @param position The final position.
108      * @param duration The duration of this scrolling.
109      * @param interruptible Whether this scrolling can be interrupted.
110      */
scrollToPosition(int position, int duration, boolean interruptible)111     public void scrollToPosition(int position, int duration, boolean interruptible);
112 
113     /**
114      * Scrolls the filmstrip horizontally to the center of the next item.
115      *
116      * @return Whether the next item exists.
117      */
goToNextItem()118     public boolean goToNextItem();
119 
120     /**
121      * Scrolls the filmstrip horizontally to the center of the previous item.
122      *
123      * @return Whether the previous item exists.
124      */
goToPreviousItem()125     public boolean goToPreviousItem();
126 
127     /**
128      * Stops the scrolling.
129      *
130      * @param forced Forces to stop even if the scrolling can not be
131      *               interrupted.
132      * @return Whether the scrolling is stopped.
133      */
stopScrolling(boolean forced)134     public boolean stopScrolling(boolean forced);
135 
136     /**
137      * Returns whether the filmstrip is scrolling.
138      * @return
139      */
isScrolling()140     public boolean isScrolling();
141 
142     /**
143      * Puts the first item in the center in full-screen.
144      */
goToFirstItem()145     public void goToFirstItem();
146 
147     /**
148      * Scales down to filmstrip mode. If the current item is camera preview,
149      * scrolls to the next item.
150      */
goToFilmstrip()151     public void goToFilmstrip();
152 
153     /**
154      * Scales up to full-screen mode.
155      */
goToFullScreen()156     public void goToFullScreen();
157 
158     /**
159      * Returns true if the supplied element is present and its view reports
160      * {@link View#VISIBLE}, such that it would be visible if onscreen. Note
161      * the filmstrip view itself might not be visible, if caller needs to check
162      * whether the filmstrip is visible, see
163      * {@link CameraAppUI#getFilmstripVisibility()}.
164      *
165      * @param data an item which can be present in the filmstrip.
166      * @return true if the view corresponding to the item has visibility of
167      *              {@link View#VISIBLE}, false otherwise.
168      */
isVisible(FilmstripItem data)169     public boolean isVisible(FilmstripItem data);
170 
171     /**
172      * An interface which defines the FilmStripView UI action listener.
173      */
174     interface FilmstripListener {
175 
176         /**
177          * Callback when the data item is promoted. A data is promoted if the user
178          * swipe up a data vertically.
179          *
180          * @param adapterIndex The ID of the promoted data.
181          */
onFocusedDataPromoted(int adapterIndex)182         public void onFocusedDataPromoted(int adapterIndex);
183 
184         /**
185          * Callback when the data item is demoted. A data is promoted if the user
186          * swipe down a data vertically.
187          *
188          * @param adapterIndex The ID of the demoted data.
189          */
onFocusedDataDemoted(int adapterIndex)190         public void onFocusedDataDemoted(int adapterIndex);
191 
192         /**
193          * Callback when the data item is long-pressed.
194          *
195          * @param adapterIndex The ID of the long-pressed data.
196          */
onFocusedDataLongPressed(int adapterIndex)197         public void onFocusedDataLongPressed(int adapterIndex);
198 
199         /**
200          * Called when all the data has been reloaded.
201          */
onDataReloaded()202         public void onDataReloaded();
203 
204         /**
205          * Called when data is updated.
206          *
207          * @param adapterIndex The ID of the updated data.
208          */
onDataUpdated(int adapterIndex)209         public void onDataUpdated(int adapterIndex);
210 
211         /**
212          * The callback when the item enters augmented full-screen state.
213          *
214          * @param adapterIndex The ID of the current focused image data.
215          */
onEnterFullScreenUiShown(int adapterIndex)216         public void onEnterFullScreenUiShown(int adapterIndex);
217 
218         /**
219          * The callback when the item leaves augmented full-screen.
220          *
221          * @param adapterIndex The ID of the current focused image data.
222          */
onLeaveFullScreenUiShown(int adapterIndex)223         public void onLeaveFullScreenUiShown(int adapterIndex);
224 
225         /**
226          * The callback when the filmstrip enters no UI full-screen.
227          *
228          * @param adapterIndex The ID of the current focused image data.
229          */
onEnterFullScreenUiHidden(int adapterIndex)230         public void onEnterFullScreenUiHidden(int adapterIndex);
231 
232         /**
233          * The callback when the filmstrip leaves no UI full-screen.
234          *
235          * @param adapterIndex The ID of the current focused image data.
236          */
onLeaveFullScreenUiHidden(int adapterIndex)237         public void onLeaveFullScreenUiHidden(int adapterIndex);
238 
239         /**
240          * The callback when the item enters filmstrip.
241          *
242          * @param adapterIndex The ID of the current focused image data.
243          */
onEnterFilmstrip(int adapterIndex)244         public void onEnterFilmstrip(int adapterIndex);
245 
246         /**
247          * The callback when the item leaves filmstrip.
248          *
249          * @param adapterIndex The ID of the current focused image data.
250          */
onLeaveFilmstrip(int adapterIndex)251         public void onLeaveFilmstrip(int adapterIndex);
252 
253         /**
254          * The callback when the item enters zoom view.
255          *
256          * @param adapterIndex
257          */
onEnterZoomView(int adapterIndex)258         public void onEnterZoomView(int adapterIndex);
259 
260         /**
261          * Called when current item or zoom level has changed.
262          *
263          * @param adapterIndex The ID of the current focused image data.
264          * @param zoom Zoom level.
265          */
onZoomAtIndexChanged(int adapterIndex, float zoom)266         public void onZoomAtIndexChanged(int adapterIndex, float zoom);
267 
268         /**
269          * The callback when the data focus changed.
270          *
271          * @param prevIndex The ID of the previously focused data or {@code -1} if
272          *                   none.
273          * @param newIndex The ID of the focused data of {@code -1} if none.
274          */
onDataFocusChanged(int prevIndex, int newIndex)275         public void onDataFocusChanged(int prevIndex, int newIndex);
276 
277         /**
278          * The callback when we scroll.
279          *
280          * @param firstVisiblePosition The position of the first rendered item
281          *                             (may be slightly offscreen depending on
282          *                             the orientation of the device).
283          * @param visibleItemCount The total number of rendered items.
284          * @param totalItemCount The total number of items in the filmstrip.
285          */
onScroll(int firstVisiblePosition, int visibleItemCount, int totalItemCount)286         public void onScroll(int firstVisiblePosition, int visibleItemCount, int totalItemCount);
287     }
288 }
289