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
17package 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 */
44public interface FilmstripController {
45
46    /**
47     * Sets the listener for filmstrip events.
48     *
49     * @param l
50     */
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     */
58    public void setImageGap(int imageGap);
59
60    /**
61     * @return The ID of the current item, or -1.
62     */
63    public int getCurrentId();
64
65    /**
66     * Sets the {@link DataAdapter}.
67     */
68    public void setDataAdapter(DataAdapter adapter);
69
70    /**
71     * Returns whether the filmstrip is in filmstrip mode.
72     */
73    public boolean inFilmstrip();
74
75    /**
76     * @return Whether the filmstrip is in full-screen mode.
77     */
78    public boolean inFullScreen();
79
80    /**
81     * @return Whether the current view in filmstrip is camera preview.
82     */
83    public boolean isCameraPreview();
84
85    /**
86     * @return Whether the filmstrip is in full-screen camrea preview.
87     */
88    public boolean inCameraFullscreen();
89
90    /**
91     * @return Whether the filmstrip is in scaling animation.
92     */
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     */
100    public void scroll(float deltaX);
101
102    /**
103     * Flings the filmstrip horizontally.
104     *
105     * @param velocity
106     */
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     */
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     */
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     */
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     */
139    public boolean stopScrolling(boolean forced);
140
141    /**
142     * Returns whether the filmstrip is scrolling.
143     * @return
144     */
145    public boolean isScrolling();
146
147    /**
148     * Puts the first item in the center in full-screen.
149     */
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     */
156    public void goToFilmstrip();
157
158    /**
159     * Scales up to full-screen mode.
160     */
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         */
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         */
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         */
189        public void onFocusedDataLongPressed(int dataID);
190
191        /**
192         * Called when all the data has been reloaded.
193         */
194        public void onDataReloaded();
195
196        /**
197         * Called when data is updated.
198         *
199         * @param dataId The ID of the updated data.
200         */
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         */
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         */
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         */
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         */
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         */
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         */
243        public void onLeaveFilmstrip(int dataId);
244
245        /**
246         * The callback when the item enters zoom view.
247         *
248         * @param dataID
249         */
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         */
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         */
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         */
278        public void onScroll(int firstVisiblePosition, int visibleItemCount, int totalItemCount);
279    }
280}
281