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