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.AlertDialog;
21import android.content.ContentValues;
22import android.net.Uri;
23
24import com.android.mail.browse.ConfirmDialogFragment;
25import com.android.mail.browse.ConversationCursor;
26import com.android.mail.browse.ConversationMessage;
27import com.android.mail.browse.UndoCallback;
28import com.android.mail.providers.Conversation;
29import com.android.mail.providers.ConversationInfo;
30import com.android.mail.providers.Folder;
31import com.android.mail.providers.UIProvider;
32
33import java.util.Collection;
34import java.util.Set;
35
36/**
37 * Classes that can update conversations implement this interface.
38 */
39public interface ConversationUpdater extends ConversationListCallbacks {
40    /**
41     * Modify the given conversation by changing the column provided here to contain the value
42     * provided. Column names are listed in {@link UIProvider.ConversationColumns}, for example
43     * {@link UIProvider.ConversationColumns#FOLDER_LIST}
44     * @param target
45     * @param columnName
46     * @param value
47     */
48    void updateConversation(Collection <Conversation> target, String columnName, String value);
49
50    /**
51     * Modify the given conversation by changing the column provided here to contain the value
52     * provided. Column names are listed in {@link UIProvider.ConversationColumns}, for example
53     * {@link UIProvider.ConversationColumns#READ}
54     * @param target
55     * @param columnName
56     * @param value
57     */
58    void updateConversation(Collection <Conversation> target, String columnName, int value);
59
60    /**
61     * Modify the given conversation by changing the column provided here to contain the value
62     * provided. Column names are listed in {@link UIProvider.ConversationColumns}, for example
63     * {@link UIProvider.ConversationColumns#HAS_ATTACHMENTS}
64     * @param target
65     * @param columnName
66     * @param value
67     */
68    void updateConversation(Collection <Conversation> target, String columnName, boolean value);
69
70    /**
71     * Modify the given conversation by changing the columns provided here to
72     * contain the values provided. Column names are listed in
73     * {@link UIProvider.ConversationColumns}, for example
74     * {@link UIProvider.ConversationColumns#HAS_ATTACHMENTS}
75     * @param target
76     * @param values
77     */
78    void updateConversation(Collection <Conversation> target, ContentValues values);
79
80    /**
81     * Requests the removal of the current conversation with the specified destructive action.
82     * @param actionId the unique id for the action responsible for this delete: R.id.archive, ...
83     * @param target the conversations to act upon.
84     * @param action to perform after the UI has been updated to remove the conversations
85     * @param isBatch true if this is a batch action, false otherwise.
86     */
87    void delete(
88            int actionId, final Collection<Conversation> target, final DestructiveAction action,
89            boolean isBatch);
90
91    /**
92     * Mark a number of conversations as read or unread.
93     * @param targets the conversations to act upon
94     * @param read true if the conversations are marked read, false if they are marked unread.
95     * @param viewed whether the conversations are marked viewed as well. This indicates that the
96     * conversations are shown on the UI.
97     */
98    void markConversationsRead(Collection<Conversation> targets, boolean read, boolean viewed);
99
100    /**
101     * Mark a single conversation unread, either entirely or for just a subset of the messages in a
102     * conversation and the view <b>returns to Conversation List</b> mode.
103     *
104     * @param conv conversation to mark unread
105     * @param unreadMessageUris URIs for the subset of the conversation's messages to mark unread,
106     * or null/empty set to mark the entire conversation unread.
107     * @param originalConversationInfo the original unread state of the {@link ConversationInfo}
108     * that {@link ConversationCursor} will temporarily use until the commit is complete.
109     */
110    void markConversationMessagesUnread(Conversation conv, Set<Uri> unreadMessageUris,
111            byte[] originalConversationInfo);
112
113    /**
114     * Mark a single conversation 'seen', which is a combination of 'viewed' and 'read'. In some
115     * configurations (peek mode), this operation may be prevented and the method will return false.
116     *
117     * @param conv the conversation to mark seen
118     * @return true if the operation was a success
119     */
120    boolean markConversationSeen(Conversation conv);
121
122    /**
123     * Star a single message within a conversation. This method requires a
124     * {@link ConversationMessage} to propagate the change to the owning {@link Conversation}.
125     *
126     */
127    void starMessage(ConversationMessage msg, boolean starred);
128
129    /**
130     * Get a destructive action for selected conversations. The action corresponds to Menu item
131     * identifiers, for example R.id.unread, or R.id.delete.
132     * @param action
133     * @return
134     */
135    public DestructiveAction getBatchAction(int action, UndoCallback undoCallback);
136
137    /**
138     * Get a destructive action for selected conversations. The action corresponds to Menu item
139     * identifiers, for example R.id.unread, or R.id.delete.
140     * @param action
141     * @return
142     */
143    public DestructiveAction getDeferredBatchAction(int action, UndoCallback undoCallback);
144
145    /**
146     * Get destructive folder change for selected conversations.
147     * The caller must explicitly call performAction.
148     * @param target
149     * @param toRemove
150     * @param isDestructive
151     * @param isBatch
152     * @param showUndo
153     * @param undoCallback
154     * @return
155     */
156    public DestructiveAction getDeferredRemoveFolder(Collection<Conversation> target,
157            Folder toRemove, boolean isDestructive, boolean isBatch,
158            boolean showUndo, UndoCallback undoCallback);
159
160    /**
161     * Assign the target conversations to the given folders, and remove them from all other folders
162     * that they might be assigned to.
163     * @param folders the folders to assign the conversations to.
164     * @param target the conversations to act upon.
165     * @param batch whether this is a batch operation
166     * @param showUndo whether to show the undo bar
167     * @param isMoveTo <code>true</code> if this is a move operation, <code>false</code> if it is
168     *        some other type of folder change operation
169     */
170    public void assignFolder(Collection<FolderOperation> folders, Collection<Conversation> target,
171            boolean batch, boolean showUndo, boolean isMoveTo);
172
173    /**
174     * Refreshes the conversation list, if one exists.
175     */
176    void refreshConversationList();
177
178    /**
179     * Show the next conversation after a destructive action. The next
180     * conversation is determined by list state and user preferences.
181     * @param conversations Conversations that were removed as part of the
182     *            destructive action.
183     */
184    void showNextConversation(Collection<Conversation> conversations);
185
186    /**
187     * Make an action listener for a confirmation dialog, and the currently selected set of
188     * conversations. The action is specified as an integer which marks the menu resource:
189     * R.id.delete, R.id.discard_drafts, etc.
190     * @param action the resource ID of the menu action: R.id.delete, for example
191     * @param fromSelectedSet true if the listener acts on the selected set, false if the listener
192     *        acts on the current conversation.
193     * @param undoCallback the appropriate callback (if any) that needs to be run when this
194     *        specific action is undone
195     */
196    public void makeDialogListener(final int action, boolean fromSelectedSet,
197            UndoCallback undoCallback);
198
199    /**
200     * If set, get the listener associated with the existing {@link ConfirmDialogFragment}.  This
201     * listener needs to be set centrally, because the dialog fragment can get torn down, along with
202     * the current activity, and the listener has to be created afresh.
203     * @return the current listener for the positive action in the current confirmation dialog, if
204     * any. Returns null if no confirmation dialog is currently shown.
205     */
206    public AlertDialog.OnClickListener getListener();
207}
208