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