1 /*
2  * Copyright (C) 2009 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package com.android.contacts.editor;
18 
19 import android.provider.ContactsContract.Data;
20 
21 import com.android.contacts.common.model.RawContactDelta;
22 import com.android.contacts.common.model.ValuesDelta;
23 import com.android.contacts.common.model.dataitem.DataKind;
24 
25 /**
26  * Generic definition of something that edits a {@link Data} row through an
27  * {@link ValuesDelta} object.
28  */
29 public interface Editor {
30 
31     public interface EditorListener {
32         /**
33          * Called when the given {@link Editor} is requested to be deleted by the user.
34          */
onDeleteRequested(Editor editor)35         public void onDeleteRequested(Editor editor);
36 
37         /**
38          * Called when the given {@link Editor} has a request, for example it
39          * wants to select a photo.
40          */
onRequest(int request)41         public void onRequest(int request);
42 
43         public static final int REQUEST_PICK_PRIMARY_PHOTO = 0;
44         public static final int REQUEST_PICK_PHOTO = 1;
45         public static final int FIELD_CHANGED = 2;
46         public static final int FIELD_TURNED_EMPTY = 3;
47         public static final int FIELD_TURNED_NON_EMPTY = 4;
48 
49         // The editor has switched between different representations of the same
50         // data, e.g. from full name to structured name
51         public static final int EDITOR_FORM_CHANGED = 5;
52 
53         // Focus has changed inside the editor.
54         public static final int EDITOR_FOCUS_CHANGED = 6;
55     }
56 
57     /**
58      * Returns whether or not all the fields are empty in this {@link Editor}.
59      */
isEmpty()60     public boolean isEmpty();
61 
62     /**
63      * Prepares this editor for the given {@link ValuesDelta}, which
64      * builds any needed views. Any changes performed by the user will be
65      * written back to that same object.
66      */
setValues(DataKind kind, ValuesDelta values, RawContactDelta state, boolean readOnly, ViewIdGenerator vig)67     public void setValues(DataKind kind, ValuesDelta values, RawContactDelta state, boolean readOnly,
68             ViewIdGenerator vig);
69 
setDeletable(boolean deletable)70     public void setDeletable(boolean deletable);
71 
72     /**
73      * Add a specific {@link EditorListener} to this {@link Editor}.
74      */
setEditorListener(EditorListener listener)75     public void setEditorListener(EditorListener listener);
76 
77     /**
78      * Called internally when the contents of a specific field have changed,
79      * allowing advanced editors to persist data in a specific way.
80      */
onFieldChanged(String column, String value)81     public void onFieldChanged(String column, String value);
82 
83     /**
84      * Performs the delete operation for this {@link Editor}.
85      */
deleteEditor()86     public void deleteEditor();
87 
88     /**
89      * Clears all fields in this {@link Editor}.
90      */
clearAllFields()91     public void clearAllFields();
92 
93     /**
94      * Called internally when the user has added a new field.  This
95      * allows the appropriate editor UI to be presented immediately.
96      * For example, if a new "event" is added, a date-picker will
97      * immediately pop up.
98      */
editNewlyAddedField()99     public void editNewlyAddedField();
100 
101 }
102