1 /******************************************************************************* 2 * Copyright (C) 2012 Google Inc. 3 * Licensed to The Android Open Source Project. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 *******************************************************************************/ 17 18 package com.android.mail.ui; 19 20 import android.app.Dialog; 21 import android.content.Intent; 22 import android.content.res.Configuration; 23 import android.os.Bundle; 24 import android.view.DragEvent; 25 import android.view.KeyEvent; 26 import android.view.Menu; 27 import android.view.MenuItem; 28 import android.view.MotionEvent; 29 30 import com.android.mail.ConversationListContext; 31 import com.android.mail.browse.ConversationCursor.ConversationListener; 32 import com.android.mail.browse.ConversationListFooterView; 33 import com.android.mail.providers.Account; 34 import com.android.mail.providers.Folder; 35 import com.android.mail.ui.ViewMode.ModeChangeListener; 36 37 /** 38 * An Activity controller knows how to combine views and listeners into a functioning activity. 39 * ActivityControllers are delegates that implement methods by calling underlying views to modify, 40 * or respond to user action. 41 * 42 * There are two ways of adding methods to this interface: 43 * <ul> 44 * <li>When the methods pertain to a single logical grouping: consider adding a new 45 * interface and putting all the methods in that interface. As an example, 46 * look at {@link AccountController}. The controller implements this, 47 * and returns itself in 48 * {@link com.android.mail.ui.ControllableActivity#getAccountController()}. This allows 49 * for account-specific methods to be added without creating new methods in this interface 50 * .</li> 51 * <li>Methods that relate to an activity can be added directly. As an example, 52 * look at {@link #onActivityResult(int, int, android.content.Intent)} which is identical to 53 * its declaration in {@link android.app.Activity}.</li> 54 * <li>Everything else. As an example, look at {@link #isDrawerEnabled()}. Try to avoid 55 * this path because an implementation has to provided in many classes: 56 * {@link MailActivity}, {@link FolderSelectionActivity}, and the controllers.</li> 57 * </ul> 58 */ 59 public interface ActivityController extends LayoutListener, 60 ModeChangeListener, ConversationListCallbacks, 61 FolderChangeListener, ConversationSetObserver, ConversationListener, FolderSelector, 62 HelpCallback, UndoListener, 63 ConversationUpdater, ErrorListener, FolderController, AccountController, 64 ConversationPositionTracker.Callbacks, ConversationListFooterView.FooterViewClickListener, 65 RecentFolderController, UpOrBackController, FragmentLauncher { 66 67 // As far as possible, the methods here that correspond to Activity lifecycle have the same name 68 // as their counterpart in the Activity lifecycle. 69 70 /** 71 * Returns the current account. 72 */ 73 Account getCurrentAccount(); 74 75 /** 76 * Returns the current conversation list context. 77 */ 78 ConversationListContext getCurrentListContext(); 79 80 /** 81 * @see android.app.Activity#onActivityResult 82 * @param requestCode 83 * @param resultCode 84 * @param data 85 */ 86 void onActivityResult(int requestCode, int resultCode, Intent data); 87 88 /** 89 * Called by the Mail activity when the back button is pressed. Returning true consumes the 90 * event and disallows the calling method from trying to handle the back button any other way. 91 * 92 * @see android.app.Activity#onBackPressed() 93 * @return true if the back press was handled and the event was consumed. Return false if the 94 * event was not consumed. 95 */ 96 boolean onBackPressed(); 97 98 /** 99 * Called by the Mail activity when the up button is pressed. 100 * @return 101 */ 102 boolean onUpPressed(); 103 104 /** 105 * Called when the root activity calls onCreate. Any initialization needs to 106 * be done here. Subclasses need to call their parents' onCreate method, since it performs 107 * valuable initialization common to all subclasses. 108 * 109 * This was called initialize in Gmail. 110 * 111 * @see android.app.Activity#onCreate 112 * @param savedState 113 * @return true if the controller was able to initialize successfully, false otherwise. 114 */ 115 boolean onCreate(Bundle savedState); 116 117 /** 118 * @see android.app.Activity#onPostCreate 119 */ 120 void onPostCreate(Bundle savedState); 121 122 /** 123 * @see android.app.Activity#onConfigurationChanged 124 */ 125 void onConfigurationChanged(Configuration newConfig); 126 127 /** 128 * @see android.app.Activity#onStart 129 */ 130 void onStart(); 131 132 /** 133 * Called when the the root activity calls onRestart 134 * @see android.app.Activity#onRestart 135 */ 136 void onRestart(); 137 138 /** 139 * @see android.app.Activity#onCreateDialog(int, Bundle) 140 * @param id 141 * @param bundle 142 * @return 143 */ 144 Dialog onCreateDialog(int id, Bundle bundle); 145 146 /** 147 * @see android.app.Activity#onCreateOptionsMenu(Menu) 148 * @param menu 149 * @return 150 */ 151 boolean onCreateOptionsMenu(Menu menu); 152 153 /** 154 * @see android.app.Activity#onKeyDown(int, KeyEvent) 155 * @param keyCode 156 * @param event 157 * @return 158 */ 159 boolean onKeyDown(int keyCode, KeyEvent event); 160 161 /** 162 * Called by Mail activity when menu items are selected 163 * @see android.app.Activity#onOptionsItemSelected(MenuItem) 164 * @param item 165 * @return 166 */ 167 boolean onOptionsItemSelected(MenuItem item); 168 169 /** 170 * Called by the Mail activity on Activity pause. 171 * @see android.app.Activity#onPause 172 */ 173 void onPause(); 174 175 /** 176 * @see android.app.Activity#onDestroy 177 */ 178 void onDestroy(); 179 180 /** 181 * @see android.app.Activity#onPrepareDialog 182 * @param id 183 * @param dialog 184 * @param bundle 185 */ 186 void onPrepareDialog(int id, Dialog dialog, Bundle bundle); 187 188 /** 189 * Called by the Mail activity when menu items need to be prepared. 190 * @see android.app.Activity#onPrepareOptionsMenu(Menu) 191 * @param menu 192 * @return 193 */ 194 boolean onPrepareOptionsMenu(Menu menu); 195 196 /** 197 * Called by the Mail activity on Activity resume. 198 * @see android.app.Activity#onResume 199 */ 200 void onResume(); 201 202 /** 203 * @see android.app.Activity#onRestoreInstanceState 204 */ 205 void onRestoreInstanceState(Bundle savedInstanceState); 206 207 /** 208 * @see android.app.Activity#onSaveInstanceState 209 * @param outState 210 */ 211 void onSaveInstanceState(Bundle outState); 212 213 /** 214 * Begin a search with the given query string. 215 */ 216 void executeSearch(String query); 217 218 /** 219 * Called by the Mail activity on Activity stop. 220 * @see android.app.Activity#onStop 221 */ 222 void onStop(); 223 224 /** 225 * Called by the Mail activity when window focus changes. 226 * @see android.app.Activity#onWindowFocusChanged(boolean) 227 * @param hasFocus 228 */ 229 void onWindowFocusChanged(boolean hasFocus); 230 231 /** 232 * Show the conversation List with the list context provided here. On certain layouts, this 233 * might show more than just the conversation list. For instance, on tablets this might show 234 * the conversations along with the conversation list. 235 * @param listContext context providing information on what conversation list to display. 236 */ 237 void showConversationList(ConversationListContext listContext); 238 239 /** 240 * Show the wait for account initialization mode. 241 */ 242 public void showWaitForInitialization(); 243 244 /** 245 * Handle a touch event. 246 */ 247 void onTouchEvent(MotionEvent event); 248 249 /** 250 * Returns whether the first conversation in the conversation list should be 251 * automatically selected and shown. 252 */ 253 boolean shouldShowFirstConversation(); 254 255 /** 256 * Get the selected set of conversations. Guaranteed to return non-null, this should return 257 * an empty set if no conversation is currently selected. 258 * @return 259 */ 260 public ConversationSelectionSet getSelectedSet(); 261 262 /** 263 * Start search mode if the account being view supports the search capability. 264 */ 265 void startSearch(); 266 267 /** 268 * Exit the search mode, popping off one activity so that the back stack is fine. 269 */ 270 void exitSearchMode(); 271 272 /** 273 * Supports dragging conversations to a folder. 274 */ 275 boolean supportsDrag(DragEvent event, Folder folder); 276 277 /** 278 * Handles dropping conversations to a folder. 279 */ 280 void handleDrop(DragEvent event, Folder folder); 281 282 /** 283 * Load the default inbox associated with the current account. 284 */ 285 public void loadAccountInbox(); 286 287 /** 288 * Return the folder currently being viewed by the activity. 289 */ 290 public Folder getHierarchyFolder(); 291 292 /** 293 * Set the folder currently selected in the folder selection hierarchy fragments. 294 */ 295 void setHierarchyFolder(Folder folder); 296 297 /** 298 * Handles the animation end of the animated adapter. 299 */ 300 void onAnimationEnd(AnimatedAdapter animatedAdapter); 301 302 /** 303 * Called when the user has started a drag/ drop gesture. 304 */ 305 void startDragMode(); 306 307 /** 308 * Called when the user has ended drag/drop. 309 */ 310 void stopDragMode(); 311 312 /** 313 * Called when Accessibility is enabled or disabled. 314 */ 315 void onAccessibilityStateChanged(); 316 317 /** 318 * Called to determine if the drawer is enabled for this controller/activity instance. 319 * Note: the value returned should not change for this controller instance. 320 */ 321 boolean isDrawerEnabled(); 322 323 /** 324 * Called to determine if menu items in the action bar should be hidden. 325 * Currently this is used for when the drawer is open to hide certain 326 * items that are not applicable while the drawer is open. 327 */ 328 public boolean shouldHideMenuItems(); 329 } 330
