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
19import android.view.View;
20
21import com.android.camera.app.CameraAppUI;
22import 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 */
49public interface FilmstripController {
50
51    /**
52     * Sets the listener for filmstrip events.
53     *
54     * @param listener
55     */
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     */
63    public void setImageGap(int imageGap);
64
65    /**
66     * @return The ID of the current item, or -1.
67     */
68    public int getCurrentAdapterIndex();
69
70    /**
71     * Sets the {@link FilmstripDataAdapter}.
72     */
73    public void setDataAdapter(FilmstripDataAdapter adapter);
74
75    /**
76     * Returns whether the filmstrip is in filmstrip mode.
77     */
78    public boolean inFilmstrip();
79
80    /**
81     * @return Whether the filmstrip is in full-screen mode.
82     */
83    public boolean inFullScreen();
84
85    /**
86     * @return Whether the filmstrip is in scaling animation.
87     */
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     */
95    public void scroll(float deltaX);
96
97    /**
98     * Flings the filmstrip horizontally.
99     *
100     * @param velocity
101     */
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     */
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     */
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     */
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     */
134    public boolean stopScrolling(boolean forced);
135
136    /**
137     * Returns whether the filmstrip is scrolling.
138     * @return
139     */
140    public boolean isScrolling();
141
142    /**
143     * Puts the first item in the center in full-screen.
144     */
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     */
151    public void goToFilmstrip();
152
153    /**
154     * Scales up to full-screen mode.
155     */
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     */
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         */
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         */
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         */
197        public void onFocusedDataLongPressed(int adapterIndex);
198
199        /**
200         * Called when all the data has been reloaded.
201         */
202        public void onDataReloaded();
203
204        /**
205         * Called when data is updated.
206         *
207         * @param adapterIndex The ID of the updated data.
208         */
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         */
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         */
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         */
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         */
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         */
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         */
251        public void onLeaveFilmstrip(int adapterIndex);
252
253        /**
254         * The callback when the item enters zoom view.
255         *
256         * @param adapterIndex
257         */
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         */
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         */
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         */
286        public void onScroll(int firstVisiblePosition, int visibleItemCount, int totalItemCount);
287    }
288}
289