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