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