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