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
18package com.android.mail.ui;
19
20import android.app.Dialog;
21import android.content.Intent;
22import android.content.res.Configuration;
23import android.os.Bundle;
24import android.view.DragEvent;
25import android.view.KeyEvent;
26import android.view.Menu;
27import android.view.MenuItem;
28import android.view.MotionEvent;
29
30import com.android.mail.ConversationListContext;
31import com.android.mail.browse.ConversationCursor.ConversationListener;
32import com.android.mail.browse.ConversationListFooterView;
33import com.android.mail.providers.Account;
34import com.android.mail.providers.Folder;
35import 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 */
59public 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