ActivityController.java revision a9b93f35035dc4badd0ac40f4016e1ff809b26b0 
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        FolderChangeListener, AccountChangeListener, 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     * Return the current mode the activity is in. Values need to be matched against constants in
76     * {@link ViewMode}.
77     * @return
78     */
79    int getMode();
80
81    /**
82     *
83     */
84    void handleConversationLoadError();
85
86    /**
87     * @see android.app.Activity#onActionModeFinished(ActionMode)
88     * @param mode
89     */
90    void onActionModeFinished(ActionMode mode);
91
92    /**
93     * @see android.app.Activity#onActionModeStarted(ActionMode)
94     * @param mode
95     */
96    void onActionModeStarted(ActionMode mode);
97
98    /**
99     * @see android.app.Activity#onActivityResult
100     * @param requestCode
101     * @param resultCode
102     * @param data
103     */
104    void onActivityResult(int requestCode, int resultCode, Intent data);
105
106    /**
107     * Called by the Mail activity when the back button is pressed. Returning true consumes the
108     * event and disallows the calling method from trying to handle the back button any other way.
109     *
110     * @see android.app.Activity#onBackPressed()
111     * @return true if the back press was handled and the event was consumed. Return false if the
112     * event was not consumed.
113     */
114    boolean onBackPressed();
115
116    /**
117     * Called by the Mail activity when the up button is pressed.
118     * @return
119     */
120    boolean onUpPressed();
121
122    /**
123     * Called when the root activity calls onCreate. Any initialization needs to
124     * be done here. Subclasses need to call their parents' onCreate method, since it performs
125     * valuable initialization common to all subclasses.
126     *
127     * This was called initialize in Gmail.
128     *
129     * @see android.app.Activity#onCreate
130     * @param savedState
131     * @return true if the controller was able to initialize successfully, false otherwise.
132     */
133    boolean onCreate(Bundle savedState);
134
135    /**
136     * @see android.app.Activity#onCreateDialog(int, Bundle)
137     * @param id
138     * @param bundle
139     * @return
140     */
141    Dialog onCreateDialog(int id, Bundle bundle);
142
143    /**
144     * @see android.app.Activity#onCreateOptionsMenu(Menu)
145     * @param menu
146     * @return
147     */
148    boolean onCreateOptionsMenu(Menu menu);
149
150    /**
151     * @see android.app.Activity#onKeyDown(int, KeyEvent)
152     * @param keyCode
153     * @param event
154     * @return
155     */
156    boolean onKeyDown(int keyCode, KeyEvent event);
157
158    /**
159     * Called by Mail activity when menu items are selected
160     * @see android.app.Activity#onOptionsItemSelected(MenuItem)
161     * @param item
162     * @return
163     */
164    boolean onOptionsItemSelected(MenuItem item);
165
166    /**
167     * Called by the Mail activity on Activity pause.
168     * @see android.app.Activity#onPause
169     */
170    void onPause();
171
172    /**
173     * @see android.app.Activity#onPrepareDialog
174     * @param id
175     * @param dialog
176     * @param bundle
177     */
178    void onPrepareDialog(int id, Dialog dialog, Bundle bundle);
179
180    /**
181     * Called by the Mail activity when menu items need to be prepared.
182     * @see android.app.Activity#onPrepareOptionsMenu(Menu)
183     * @param menu
184     * @return
185     */
186    boolean onPrepareOptionsMenu(Menu menu);
187
188    /**
189     * Called by the Mail activity on Activity resume.
190     * @see android.app.Activity#onResume
191     */
192    void onResume();
193
194    /**
195     * @see android.app.Activity#onSaveInstanceState
196     * @param outState
197     */
198    void onSaveInstanceState(Bundle outState);
199
200    /**
201     * @see android.app.Activity#onSearchRequested()
202     */
203    void onSearchRequested();
204
205    /**
206     * Called by the Mail activity on Activity stop.
207     * @see android.app.Activity#onStop
208     */
209    void onStop();
210
211    /**
212     * Called by the Mail activity when window focus changes.
213     * @see android.app.Activity#onWindowFocusChanged(boolean)
214     * @param hasFocus
215     */
216    void onWindowFocusChanged(boolean hasFocus);
217
218    /**
219     * Set the Action Bar icon according to the mode. The Action Bar icon can contain a back button
220     * or not. The individual controller is responsible for changing the icon based on the mode.
221     */
222    void resetActionBarIcon();
223
224    /**
225     * Show the conversation List with the list context provided here. On certain layouts, this
226     * might show more than just the conversation list. For instance, on tablets this might show
227     * the conversations along with the conversation list.
228     * @param listContext context providing information on what conversation list to display.
229     */
230    void showConversationList(ConversationListContext listContext);
231
232    /**
233     * Show the conversation provided here.
234     * @param conversation conversation to display.
235     */
236    void showConversation(Conversation conversation);
237
238    /**
239     * Show the folder list associated with the currently selected account.
240     */
241    @Override
242    void showFolderList();
243
244    /**
245     * Shows the preferences screen
246     */
247    void showPreferences();
248
249    /**
250     * Handle a touch event.
251     */
252    void onTouchEvent(MotionEvent event);
253}
254