ActivityController.java revision 4969e0c5f8ab837e1b0d29ea56d220e6404e9250 
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.app.LoaderManager;
22import android.content.Intent;
23import android.database.Cursor;
24import android.os.Bundle;
25import android.view.DragEvent;
26import android.view.KeyEvent;
27import android.view.Menu;
28import android.view.MenuItem;
29import android.view.MotionEvent;
30
31import com.android.mail.ConversationListContext;
32import com.android.mail.browse.ConversationCursor.ConversationListener;
33import com.android.mail.browse.ConversationListFooterView;
34import com.android.mail.providers.Account;
35import com.android.mail.providers.Conversation;
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 */
44public interface ActivityController extends LayoutListener,
45        ModeChangeListener, ConversationListCallbacks,
46        FolderChangeListener, AccountChangeListener, LoaderManager.LoaderCallbacks<Cursor>,
47        ConversationSetObserver, ConversationListener,
48        FolderListFragment.FolderListSelectionListener, HelpCallback, UndoListener,
49        ConversationUpdater, ErrorListener, FolderController, AccountController,
50        ConversationPositionTracker.Callbacks, ConversationListFooterView.FooterViewClickListener {
51
52    // As far as possible, the methods here that correspond to Activity lifecycle have the same name
53    // as their counterpart in the Activity lifecycle.
54
55    /**
56     * Returns the current account.
57     */
58    Account getCurrentAccount();
59
60    /**
61     * Returns the current conversation list context.
62     */
63    ConversationListContext getCurrentListContext();
64
65    /**
66     * @see android.app.Activity#onActivityResult
67     * @param requestCode
68     * @param resultCode
69     * @param data
70     */
71    void onActivityResult(int requestCode, int resultCode, Intent data);
72
73    /**
74     * Called by the Mail activity when the back button is pressed. Returning true consumes the
75     * event and disallows the calling method from trying to handle the back button any other way.
76     *
77     * @see android.app.Activity#onBackPressed()
78     * @return true if the back press was handled and the event was consumed. Return false if the
79     * event was not consumed.
80     */
81    boolean onBackPressed();
82
83    /**
84     * Called by the Mail activity when the up button is pressed.
85     * @return
86     */
87    boolean onUpPressed();
88
89    /**
90     * Called when the root activity calls onCreate. Any initialization needs to
91     * be done here. Subclasses need to call their parents' onCreate method, since it performs
92     * valuable initialization common to all subclasses.
93     *
94     * This was called initialize in Gmail.
95     *
96     * @see android.app.Activity#onCreate
97     * @param savedState
98     * @return true if the controller was able to initialize successfully, false otherwise.
99     */
100    boolean onCreate(Bundle savedState);
101
102    /**
103     * Called when the the root activity calls onRestart
104     * @see android.app.Activity#onRestart
105     */
106    void onRestart();
107
108    /**
109     * @see android.app.Activity#onCreateDialog(int, Bundle)
110     * @param id
111     * @param bundle
112     * @return
113     */
114    Dialog onCreateDialog(int id, Bundle bundle);
115
116    /**
117     * @see android.app.Activity#onCreateOptionsMenu(Menu)
118     * @param menu
119     * @return
120     */
121    boolean onCreateOptionsMenu(Menu menu);
122
123    /**
124     * @see android.app.Activity#onKeyDown(int, KeyEvent)
125     * @param keyCode
126     * @param event
127     * @return
128     */
129    boolean onKeyDown(int keyCode, KeyEvent event);
130
131    /**
132     * Called by Mail activity when menu items are selected
133     * @see android.app.Activity#onOptionsItemSelected(MenuItem)
134     * @param item
135     * @return
136     */
137    boolean onOptionsItemSelected(MenuItem item);
138
139    /**
140     * Called by the Mail activity on Activity pause.
141     * @see android.app.Activity#onPause
142     */
143    void onPause();
144
145    /**
146     * @see android.app.Activity#onDestroy
147     */
148    void onDestroy();
149
150    /**
151     * @see android.app.Activity#onPrepareDialog
152     * @param id
153     * @param dialog
154     * @param bundle
155     */
156    void onPrepareDialog(int id, Dialog dialog, Bundle bundle);
157
158    /**
159     * Called by the Mail activity when menu items need to be prepared.
160     * @see android.app.Activity#onPrepareOptionsMenu(Menu)
161     * @param menu
162     * @return
163     */
164    boolean onPrepareOptionsMenu(Menu menu);
165
166    /**
167     * Called by the Mail activity on Activity resume.
168     * @see android.app.Activity#onResume
169     */
170    void onResume();
171
172    /**
173     * @see android.app.Activity#onRestoreInstanceState
174     */
175    void onRestoreInstanceState(Bundle savedInstanceState);
176
177    /**
178     * @see android.app.Activity#onSaveInstanceState
179     * @param outState
180     */
181    void onSaveInstanceState(Bundle outState);
182
183    /**
184     * @see android.app.Activity#onSearchRequested()
185     */
186    void onSearchRequested(String query);
187
188    /**
189     * Called by the Mail activity on Activity stop.
190     * @see android.app.Activity#onStop
191     */
192    void onStop();
193
194    /**
195     * Called by the Mail activity when window focus changes.
196     * @see android.app.Activity#onWindowFocusChanged(boolean)
197     * @param hasFocus
198     */
199    void onWindowFocusChanged(boolean hasFocus);
200
201    /**
202     * Set the Action Bar icon according to the mode. The Action Bar icon can contain a back button
203     * or not. The individual controller is responsible for changing the icon based on the mode.
204     */
205    void resetActionBarIcon();
206
207    /**
208     * Show the conversation List with the list context provided here. On certain layouts, this
209     * might show more than just the conversation list. For instance, on tablets this might show
210     * the conversations along with the conversation list.
211     * @param listContext context providing information on what conversation list to display.
212     */
213    void showConversationList(ConversationListContext listContext);
214
215    /**
216     * Show the conversation provided here. If the conversation is null, this is a request to pop
217     * <em>out</em> of conversation view mode and head back to conversation list mode, or whatever
218     * should best show in its place.
219     * @param conversation conversation to display, possibly null.
220     */
221    void showConversation(Conversation conversation);
222
223    /**
224     * Show the wait for account initialization mode.
225     */
226    public void showWaitForInitialization();
227
228    /**
229     * Dismiss the wait for account initialization mode.
230     */
231    public void hideWaitForInitialization();
232
233    /**
234     * Update the wait for account initialization mode.
235     */
236    public void updateWaitMode();
237
238    /**
239     * Show the folder list associated with the currently selected account.
240     */
241    void showFolderList();
242
243    /**
244     * Handle a touch event.
245     */
246    void onTouchEvent(MotionEvent event);
247
248    /**
249     * Returns whether the first conversation in the conversation list should be
250     * automatically selected and shown.
251     */
252    boolean shouldShowFirstConversation();
253
254    /**
255     * Get the selected set of conversations. Guaranteed to return non-null, this should return
256     * an empty set if no conversation is currently selected.
257     * @return
258     */
259    public ConversationSelectionSet getSelectedSet();
260
261    /**
262     * Start search mode if the account being view supports the search capability.
263     */
264    void startSearch();
265
266    /**
267     * Exit the search mode, popping off one activity so that the back stack is fine.
268     */
269    void exitSearchMode();
270
271    /**
272     * Supports dragging conversations to a folder.
273     */
274    boolean supportsDrag(DragEvent event, Folder folder);
275
276    /**
277     * Handles dropping conversations to a folder.
278     */
279    void handleDrop(DragEvent event, Folder folder);
280
281    /**
282     * Coordinates actions that might occur in response to a conversation that has finished loading
283     * and is now user-visible.
284     */
285    void onConversationSeen(Conversation conv);
286
287    /**
288     * Load the default inbox associated with the current account.
289     */
290    public void loadAccountInbox();
291
292    /**
293     * Return the folder currently being viewed by the activity.
294     */
295    public Folder getHierarchyFolder();
296
297    /**
298     * Set the folder currently selected in the folder selection hierarchy fragments.
299     */
300    void setHierarchyFolder(Folder folder);
301
302    /**
303     * @return a {@link SubjectDisplayChanger}, or null
304     */
305    SubjectDisplayChanger getSubjectDisplayChanger();
306
307    /**
308     * Handles the animation end of the animated adapter.
309     */
310    void onAnimationEnd(AnimatedAdapter animatedAdapter);
311}
312