ActivityController.java revision 674afa42682908640167fc6109b76f6f843e6fbe 
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.ActionMode;
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.ConversationItemView.StarHandler;
33import com.android.mail.providers.Conversation;
34import com.android.mail.ui.ViewMode.ModeChangeListener;
35
36/**
37 * An Activity controller knows how to combine views and listeners into a functioning activity.
38 * ActivityControllers are delegates that implement methods by calling underlying views to modify,
39 * or respond to user action.
40 */
41public interface ActivityController extends MenuCallback, LayoutListener, SubjectDisplayChanger,
42        ModeChangeListener, MailActionBar.Callback, StarHandler, ConversationListCallbacks,
43        FolderListCallback, LoaderManager.LoaderCallbacks<Cursor> {
44
45    // As far as possible, the methods here that correspond to Activity lifecycle have the same name
46    // as their counterpart in the Activity lifecycle.
47
48    /**
49     * Attach the conversation list fragment to the appropriate view.
50     * @param conversationListFragment
51     */
52    // TODO(viki): Why does the activity controller have such a deep knowledge of the conversation
53    // list fragment? Calls to the fragment show up in handleLoadFinished, isConversationListMode,
54    // onDestructiveCommand, restoreState, showConversationAtCursor, handleKeyDown, etc.
55    // Instead, it might be beneficial to have a layout controller a la TriStateSplitLayout which
56    // exists both for one pane and two pane modes. The layout controller should know about the
57    // fragment, and send appropriate calls to it. Such a scheme will allow some separation of
58    // control and view logic, which is spread between the activity controller and the fragment
59    // currently.
60    void attachConversationList(ConversationListFragment conversationListFragment);
61
62    /**
63     * Attach the folder list fragment to the appropriate view.
64     * @param folderListFragment
65     */
66    void attachFolderList(FolderListFragment folderListFragment);
67
68    /**
69     * Attach the conversation view fragment to the appropriate view.
70     * @param conversationViewFragment
71     */
72    void attachConversationView(ConversationViewFragment conversationViewFragment);
73
74    /**
75     * @see android.app.Activity#dispatchTouchEvent(MotionEvent)
76     * @param event
77     */
78    void dispatchTouchEvent(MotionEvent event);
79
80    /**
81     * Return the current mode the activity is in. Values need to be matched against constants in
82     * {@link ViewMode}.
83     * @return
84     */
85    int getMode();
86
87    /**
88     *
89     */
90    void handleConversationLoadError();
91
92    /**
93     * @see android.app.Activity#onActionModeFinished(ActionMode)
94     * @param mode
95     */
96    void onActionModeFinished(ActionMode mode);
97
98    /**
99     * @see android.app.Activity#onActionModeStarted(ActionMode)
100     * @param mode
101     */
102    void onActionModeStarted(ActionMode mode);
103
104    /**
105     * @see android.app.Activity#onActivityResult
106     * @param requestCode
107     * @param resultCode
108     * @param data
109     */
110    void onActivityResult(int requestCode, int resultCode, Intent data);
111
112    /**
113     * Called by the Mail activity when the back button is pressed. Returning true consumes the
114     * event and disallows the calling method from trying to handle the back button any other way.
115     *
116     * @see android.app.Activity#onBackPressed()
117     * @return true if the back press was handled and the event was consumed. Return false if the
118     * event was not consumed.
119     */
120    boolean onBackPressed();
121
122    /**
123     * Called by the Mail activity when the up button is pressed.
124     * @return
125     */
126    boolean onUpPressed();
127
128    /**
129     * Called when the root activity calls onCreate. Any initialization needs to
130     * be done here. Subclasses need to call their parents' onCreate method, since it performs
131     * valuable initialization common to all subclasses.
132     *
133     * This was called initialize in Gmail.
134     *
135     * @see android.app.Activity#onCreate
136     * @param savedState
137     * @return true if the controller was able to initialize successfully, false otherwise.
138     */
139    boolean onCreate(Bundle savedState);
140
141    /**
142     * @see android.app.Activity#onCreateDialog(int, Bundle)
143     * @param id
144     * @param bundle
145     * @return
146     */
147    Dialog onCreateDialog(int id, Bundle bundle);
148
149    /**
150     * @see android.app.Activity#onCreateOptionsMenu(Menu)
151     * @param menu
152     * @return
153     */
154    boolean onCreateOptionsMenu(Menu menu);
155
156    /**
157     * @see android.app.Activity#onKeyDown(int, KeyEvent)
158     * @param keyCode
159     * @param event
160     * @return
161     */
162    boolean onKeyDown(int keyCode, KeyEvent event);
163
164    /**
165     * Called by Mail activity when menu items are selected
166     * @see android.app.Activity#onOptionsItemSelected(MenuItem)
167     * @param item
168     * @return
169     */
170    boolean onOptionsItemSelected(MenuItem item);
171
172    /**
173     * Called by the Mail activity on Activity pause.
174     * @see android.app.Activity#onPause
175     */
176    void onPause();
177
178    /**
179     * @see android.app.Activity#onPrepareDialog
180     * @param id
181     * @param dialog
182     * @param bundle
183     */
184    void onPrepareDialog(int id, Dialog dialog, Bundle bundle);
185
186    /**
187     * Called by the Mail activity when menu items need to be prepared.
188     * @see android.app.Activity#onPrepareOptionsMenu(Menu)
189     * @param menu
190     * @return
191     */
192    boolean onPrepareOptionsMenu(Menu menu);
193
194    /**
195     * Called by the Mail activity on Activity resume.
196     * @see android.app.Activity#onResume
197     */
198    void onResume();
199
200    /**
201     * @see android.app.Activity#onSaveInstanceState
202     * @param outState
203     */
204    void onSaveInstanceState(Bundle outState);
205
206    /**
207     * @see android.app.Activity#onSearchRequested()
208     */
209    void onSearchRequested();
210
211    /**
212     * Called by the Mail activity on Activity stop.
213     * @see android.app.Activity#onStop
214     */
215    void onStop();
216
217    /**
218     * Called by the Mail activity when window focus changes.
219     * @see android.app.Activity#onWindowFocusChanged(boolean)
220     * @param hasFocus
221     */
222    void onWindowFocusChanged(boolean hasFocus);
223
224    /**
225     * Set the Action Bar icon according to the mode. The Action Bar icon can contain a back button
226     * or not. The individual controller is responsible for changing the icon based on the mode.
227     */
228    void resetActionBarIcon();
229
230    /**
231     * Show the conversation List with the list context provided here. On certain layouts, this
232     * might show more than just the conversation list. For instance, on tablets this might show
233     * the conversations along with the conversation list.
234     * @param listContext context providing information on what conversation list to display.
235     */
236    void showConversationList(ConversationListContext listContext);
237
238    /**
239     * Show the conversation provided here.
240     * @param Converseation conversation to display.
241     */
242    void showConversation(Conversation conversation);
243
244    /**
245     * Show the folder list associated with the currently selected account.
246     */
247    void showFolderList();
248
249    /**
250     * Handle a touch event.
251     */
252    void onTouchEvent(MotionEvent event);
253}
254