diff --git a/doc/小米便签的泛读报告.docx b/doc/小米便签泛读和标注报告文档.docx similarity index 92% rename from doc/小米便签的泛读报告.docx rename to doc/小米便签泛读和标注报告文档.docx index 52e7850..2af7980 100644 Binary files a/doc/小米便签的泛读报告.docx and b/doc/小米便签泛读和标注报告文档.docx differ diff --git a/src/data/Contact.java b/src/data/Contact.java index d97ac5d..31ab5c9 100644 --- a/src/data/Contact.java +++ b/src/data/Contact.java @@ -25,47 +25,74 @@ import android.util.Log; import java.util.HashMap; +/** + * + * @Package: net.micode.notes.data + * @ClassName: Contact + * @Description: 通过传入的电话号码获取对应的姓名 + */ public class Contact { + //哈希图型变量sContactCache，用于存储联系人姓名和电话号码的映射关系 private static HashMap sContactCache; private static final String TAG = "Contact"; - private static final String CALLER_ID_SELECTION = "PHONE_NUMBERS_EQUAL(" + Phone.NUMBER - + ",?) AND " + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'" - + " AND " + Data.RAW_CONTACT_ID + " IN " - + "(SELECT raw_contact_id " - + " FROM phone_lookup" - + " WHERE min_match = '+')"; + /** + * 查找联系人的sql语句: + * 执行过程：从phone_lookup中查询符合最小匹配值的raw_contact_id，在data表里找到raw_contact_id，选择电话号码类型，并与传入的电话号码进行精确匹配 + */ + private static final String CALLER_ID_SELECTION = "PHONE_NUMBERS_EQUAL(" + Phone.NUMBER + ",?) AND " + Data.MIMETYPE + + "='" + Phone.CONTENT_ITEM_TYPE + "'" + " AND " + Data.RAW_CONTACT_ID + " IN " + "(SELECT raw_contact_id " + + " FROM phone_lookup" + " WHERE min_match = '+')"; + /** + * @method getContact + * @description 通过传入的电话号码获取对应的姓名 + * @param context 上下文 + * @param phoneNumber 传入的电话号码 + * @return string 姓名 + */ public static String getContact(Context context, String phoneNumber) { - if(sContactCache == null) { + //初始化 sContactCache + if (sContactCache == null) { sContactCache = new HashMap(); } - if(sContactCache.containsKey(phoneNumber)) { + //通过电话号码查找sContactCache，如果命中，直接返回对应的姓名 + if (sContactCache.containsKey(phoneNumber)) { return sContactCache.get(phoneNumber); } - String selection = CALLER_ID_SELECTION.replace("+", - PhoneNumberUtils.toCallerIDMinMatch(phoneNumber)); - Cursor cursor = context.getContentResolver().query( - Data.CONTENT_URI, - new String [] { Phone.DISPLAY_NAME }, - selection, - new String[] { phoneNumber }, - null); + //selection:将CALLER_ID_SELECTION中的“+”替换成实际电话号码的最小匹配字符串 + String selection = CALLER_ID_SELECTION.replace("+", PhoneNumberUtils.toCallerIDMinMatch(phoneNumber)); + + /**查询数据库，返回光标 + * 数据库表：Data.CONTENT_URI + * 查找的列：Phone.DISPLAY_NAME 只显示名称 + * 查找的sql语句：selection + * 替换掉占位符“？”：phoneNumber + * 排序方式：不排序 + */ + Cursor cursor = context.getContentResolver().query(Data.CONTENT_URI, new String[]{Phone.DISPLAY_NAME}, + selection, new String[]{phoneNumber}, null); + //如果光标不为空且移到第一行，即已在数据库中查询到 if (cursor != null && cursor.moveToFirst()) { + //获取联系人姓名 并将电话号码和联系人姓名的映射关系存到sContactCache中 返回姓名 try { String name = cursor.getString(0); sContactCache.put(phoneNumber, name); return name; - } catch (IndexOutOfBoundsException e) { + } + //异常处理 + catch (IndexOutOfBoundsException e) { Log.e(TAG, " Cursor get string error " + e.toString()); return null; } finally { cursor.close(); } - } else { + } + //如果未在数据库中查询到，则记录错误日志 + else { Log.d(TAG, "No contact matched with number:" + phoneNumber); return null; } diff --git a/src/data/Notes.java b/src/data/Notes.java index f240604..6273380 100644 --- a/src/data/Notes.java +++ b/src/data/Notes.java @@ -17,24 +17,40 @@ package net.micode.notes.data; import android.net.Uri; + +/** + * + * @Package: net.micode.notes.data + * @ClassName: Notes + * @Description: 集中定义一些常量 + */ public class Notes { - public static final String AUTHORITY = "micode_notes"; + //定义此应用ContentProvider的唯一标识 + public static final String AUTHORITY = "net.micode.notes.provider"; public static final String TAG = "Notes"; + + /** + *{@link Notes#TYPE_NOTE } 普通便签 + *{@link Notes#TYPE_FOLDER }文件夹 + *{@link Notes#TYPE_SYSTEM } 系统 + */ public static final int TYPE_NOTE = 0; public static final int TYPE_FOLDER = 1; public static final int TYPE_SYSTEM = 2; /** * Following IDs are system folders' identifiers - * {@link Notes#ID_ROOT_FOLDER } is default folder - * {@link Notes#ID_TEMPARAY_FOLDER } is for notes belonging no folder - * {@link Notes#ID_CALL_RECORD_FOLDER} is to store call records + * {@link Notes#ID_ROOT_FOLDER } is default folder 默认文件夹 + * {@link Notes#ID_TEMPARAY_FOLDER } is for notes belonging no folder 不属于文件夹的便签 + * {@link Notes#ID_CALL_RECORD_FOLDER} is to store call records 存储通话记录 + * {@link Notes#ID_TRASH_FOLER} 垃圾文件夹 */ public static final int ID_ROOT_FOLDER = 0; public static final int ID_TEMPARAY_FOLDER = -1; public static final int ID_CALL_RECORD_FOLDER = -2; public static final int ID_TRASH_FOLER = -3; + //定义Intent Extra 的常量，用于在不同组件之间安全地传递数据 public static final String INTENT_EXTRA_ALERT_DATE = "net.micode.notes.alert_date"; public static final String INTENT_EXTRA_BACKGROUND_ID = "net.micode.notes.background_color_id"; public static final String INTENT_EXTRA_WIDGET_ID = "net.micode.notes.widget_id"; @@ -46,6 +62,7 @@ public class Notes { public static final int TYPE_WIDGET_2X = 0; public static final int TYPE_WIDGET_4X = 1; + // 将不同数据类型对应到其MIMEitem类型字符串 public static class DataConstants { public static final String NOTE = TextNote.CONTENT_ITEM_TYPE; public static final String CALL_NOTE = CallNote.CONTENT_ITEM_TYPE; @@ -61,6 +78,7 @@ public class Notes { */ public static final Uri CONTENT_DATA_URI = Uri.parse("content://" + AUTHORITY + "/data"); + //Note表数据库列名常量接口 public interface NoteColumns { /** * The unique ID for a row @@ -95,6 +113,8 @@ public class Notes { /** * Folder's name or text content of note + * 如果是文件夹，存储文件夹名字 + * 如果是便签，存储便签摘要 *

Type: TEXT

*/ public static final String SNIPPET = "snippet"; @@ -167,6 +187,7 @@ public class Notes { public static final String VERSION = "version"; } + //Data表数据库列名常量接口 public interface DataColumns { /** * The unique ID for a row @@ -241,10 +262,12 @@ public class Notes { public static final String DATA5 = "data5"; } + //DataColumns接口的实现方式1：文本便签的数据模型 public static final class TextNote implements DataColumns { /** * Mode to indicate the text in check list mode or not *

Type: Integer 1:check list mode 0: normal mode

+ * data1表示是否是清单模式 */ public static final String MODE = DATA1; @@ -257,16 +280,19 @@ public class Notes { public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/text_note"); } + //DataColumns接口的实现方式2：通话便签的数据模型 public static final class CallNote implements DataColumns { /** * Call date for this record *

Type: INTEGER (long)

+ * data1表示通话时间戳 */ public static final String CALL_DATE = DATA1; /** * Phone number for this record *

Type: TEXT

+ * data3表示电话号码 */ public static final String PHONE_NUMBER = DATA3; diff --git a/src/data/NotesDatabaseHelper.java b/src/data/NotesDatabaseHelper.java index ffe5d57..e1e055f 100644 --- a/src/data/NotesDatabaseHelper.java +++ b/src/data/NotesDatabaseHelper.java @@ -26,7 +26,12 @@ import net.micode.notes.data.Notes.DataColumns; import net.micode.notes.data.Notes.DataConstants; import net.micode.notes.data.Notes.NoteColumns; - +/** + * + * @Package: net.micode.notes.data + * @ClassName: NotesDatabaseHelper + * @Description: 创建和升级数据库 + */ public class NotesDatabaseHelper extends SQLiteOpenHelper { private static final String DB_NAME = "note.db"; @@ -42,6 +47,9 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { private static NotesDatabaseHelper mInstance; + /**创建note表的sql语句 + * note表：存储便签与文件夹的信息 + */ private static final String CREATE_NOTE_TABLE_SQL = "CREATE TABLE " + TABLE.NOTE + "(" + NoteColumns.ID + " INTEGER PRIMARY KEY," + @@ -63,6 +71,9 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { NoteColumns.VERSION + " INTEGER NOT NULL DEFAULT 0" + ")"; + /**创建data表的sql语句 + * data表：保存具体的数据条目 + */ private static final String CREATE_DATA_TABLE_SQL = "CREATE TABLE " + TABLE.DATA + "(" + DataColumns.ID + " INTEGER PRIMARY KEY," + @@ -78,12 +89,17 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { DataColumns.DATA5 + " TEXT NOT NULL DEFAULT ''" + ")"; + //为data表的note_id列创建索引的sql语句： private static final String CREATE_DATA_NOTE_ID_INDEX_SQL = "CREATE INDEX IF NOT EXISTS note_id_index ON " + TABLE.DATA + "(" + DataColumns.NOTE_ID + ");"; /** * Increase folder's note count when move note to the folder + * 创建触发器increase_folder_count_on_update： + * 触发时机：事件后 + * 触发事件：当note表内PARENT_ID更新 + * 触发器动作：更新note表中对应父文件夹的计数 */ private static final String NOTE_INCREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER = "CREATE TRIGGER increase_folder_count_on_update "+ @@ -96,6 +112,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Decrease folder's note count when move note from folder + * 创建触发器decrease_folder_count_on_update： + * 触发时机：事件后 + * 触发事件：当note表内PARENT_ID更新 + * 触发器动作：更新note表中对应原父文件夹的计数 */ private static final String NOTE_DECREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER = "CREATE TRIGGER decrease_folder_count_on_update " + @@ -109,6 +129,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Increase folder's note count when insert new note to the folder + * 创建触发器increase_folder_count_on_insert： + * 触发时机：事件后 + * 触发事件：当note表内插入新一行 + * 触发器动作：更新note表中对应父文件夹的计数 */ private static final String NOTE_INCREASE_FOLDER_COUNT_ON_INSERT_TRIGGER = "CREATE TRIGGER increase_folder_count_on_insert " + @@ -121,6 +145,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Decrease folder's note count when delete note from the folder + * 创建触发器decrease_folder_count_on_delete： + * 触发时机：事件后 + * 触发事件：当note表内删除记录 + * 触发器动作：更新note表中对应原父文件夹的计数 */ private static final String NOTE_DECREASE_FOLDER_COUNT_ON_DELETE_TRIGGER = "CREATE TRIGGER decrease_folder_count_on_delete " + @@ -134,6 +162,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Update note's content when insert data with type {@link DataConstants#NOTE} + * 创建触发器update_note_content_on_insert： + * 触发时机：事件后 + * 触发事件：data表中新插入了某一行（该表数据类型是文字便签类） + * 触发动作：更新对应的note表中的摘要为新便签的内容 */ private static final String DATA_UPDATE_NOTE_CONTENT_ON_INSERT_TRIGGER = "CREATE TRIGGER update_note_content_on_insert " + @@ -147,6 +179,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Update note's content when data with {@link DataConstants#NOTE} type has changed + * 创建触发器update_note_content_on_update： + * 触发时机：事件后 + * 触发事件：当data表内更新记录（该表数据类型是文字便签类） + * 触发器动作：更新note表中对应便签的摘要内容为新内容 */ private static final String DATA_UPDATE_NOTE_CONTENT_ON_UPDATE_TRIGGER = "CREATE TRIGGER update_note_content_on_update " + @@ -160,6 +196,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Update note's content when data with {@link DataConstants#NOTE} type has deleted + * 创建触发器update_note_content_on_delete： + * 触发时机：事件后 + * 触发事件：当data表内删除记录 + * 触发器动作：更新note表中对应便签的摘要内容为空 */ private static final String DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER = "CREATE TRIGGER update_note_content_on_delete " + @@ -173,6 +213,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Delete datas belong to note which has been deleted + * 创建触发器delete_data_on_delete： + * 触发时机：事件后 + * 触发事件：当note表内删除记录 + * 触发器动作：删除data表中对应便签的所有数据 */ private static final String NOTE_DELETE_DATA_ON_DELETE_TRIGGER = "CREATE TRIGGER delete_data_on_delete " + @@ -184,6 +228,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Delete notes belong to folder which has been deleted + * 创建触发器folder_delete_notes_on_delete： + * 触发时机：事件后 + * 触发事件：当note表内删除文件夹记录 + * 触发器动作：删除note表中对应父文件夹的所有便签 */ private static final String FOLDER_DELETE_NOTES_ON_DELETE_TRIGGER = "CREATE TRIGGER folder_delete_notes_on_delete " + @@ -195,6 +243,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Move notes belong to folder which has been moved to trash folder + * 创建触发器folder_move_notes_on_trash： + * 触发时机：事件后 + * 触发事件：当note表内PARENT_ID更新为垃圾文件夹id + * 触发器动作：更新note表中对应原父文件夹的所有便签的父id为垃圾文件夹id */ private static final String FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER = "CREATE TRIGGER folder_move_notes_on_trash " + @@ -206,10 +258,22 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { " WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" + " END"; + + /** + * @method NotesDatabaseHelper + * @description 调用父类构造函数 + * @param context 上下文 + * 上下文： context + * 数据库名字：DB_NAME + * 游标工厂： 默认 + * 数据库版本号：DB_VERSION + */ public NotesDatabaseHelper(Context context) { super(context, DB_NAME, null, DB_VERSION); } + + //创建note表 public void createNoteTable(SQLiteDatabase db) { db.execSQL(CREATE_NOTE_TABLE_SQL); reCreateNoteTableTriggers(db); @@ -217,7 +281,9 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { Log.d(TAG, "note table has been created"); } + //创建note表触发器 private void reCreateNoteTableTriggers(SQLiteDatabase db) { + //将已有的触发器删掉 db.execSQL("DROP TRIGGER IF EXISTS increase_folder_count_on_update"); db.execSQL("DROP TRIGGER IF EXISTS decrease_folder_count_on_update"); db.execSQL("DROP TRIGGER IF EXISTS decrease_folder_count_on_delete"); @@ -235,11 +301,13 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { db.execSQL(FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER); } + //创建系统文件夹 private void createSystemFolder(SQLiteDatabase db) { + //ContentValues是一个键值对集合，用于存储一行数据。名是string，值为基本类型。 ContentValues values = new ContentValues(); - /** * call record foler for call notes + * 创建通话记录文件夹 */ values.put(NoteColumns.ID, Notes.ID_CALL_RECORD_FOLDER); values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM); @@ -247,6 +315,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * root folder which is default folder + * 创建默认文件夹 */ values.clear(); values.put(NoteColumns.ID, Notes.ID_ROOT_FOLDER); @@ -255,6 +324,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * temporary folder which is used for moving note + * 创建临时文件夹（存储不属于其他文件夹的便签） */ values.clear(); values.put(NoteColumns.ID, Notes.ID_TEMPARAY_FOLDER); @@ -263,6 +333,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * create trash folder + * 创建垃圾文件夹 */ values.clear(); values.put(NoteColumns.ID, Notes.ID_TRASH_FOLER); @@ -270,6 +341,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { db.insert(TABLE.NOTE, null, values); } + //创建data表 public void createDataTable(SQLiteDatabase db) { db.execSQL(CREATE_DATA_TABLE_SQL); reCreateDataTableTriggers(db); @@ -277,6 +349,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { Log.d(TAG, "data table has been created"); } + //创建data表触发器 private void reCreateDataTableTriggers(SQLiteDatabase db) { db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_insert"); db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_update"); @@ -287,6 +360,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { db.execSQL(DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER); } + //创建NotesDatabaseHelper的单例 static synchronized NotesDatabaseHelper getInstance(Context context) { if (mInstance == null) { mInstance = new NotesDatabaseHelper(context); @@ -294,12 +368,20 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { return mInstance; } + //重写onCreate方法：创建数据库 @Override public void onCreate(SQLiteDatabase db) { createNoteTable(db); createDataTable(db); } + /** + * @method onUpgrade + * @description 数据库升级 + * @param db 数据库 + * @param oldVersion 旧版本 + * @param newVersion 新版本 + */ @Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { boolean reCreateTriggers = false; @@ -307,7 +389,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { if (oldVersion == 1) { upgradeToV2(db); - skipV2 = true; // this upgrade including the upgrade from v2 to v3 + skipV2 = true; // this upgrade including the upgrade from v2 to v3 v1->v2升级已包含v2->v3升级 oldVersion++; } @@ -333,6 +415,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { } } + //更新到版本2：重建note表和data表 private void upgradeToV2(SQLiteDatabase db) { db.execSQL("DROP TABLE IF EXISTS " + TABLE.NOTE); db.execSQL("DROP TABLE IF EXISTS " + TABLE.DATA); @@ -340,6 +423,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { createDataTable(db); } + //更新到版本3：引入Gtask功能，添加垃圾站功能 private void upgradeToV3(SQLiteDatabase db) { // drop unused triggers db.execSQL("DROP TRIGGER IF EXISTS update_note_modified_date_on_insert"); @@ -355,6 +439,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { db.insert(TABLE.NOTE, null, values); } + //更新到版本4：增加版本字段 private void upgradeToV4(SQLiteDatabase db) { db.execSQL("ALTER TABLE " + TABLE.NOTE + " ADD COLUMN " + NoteColumns.VERSION + " INTEGER NOT NULL DEFAULT 0"); diff --git a/src/data/NotesProvider.java b/src/data/NotesProvider.java index edb0a60..54ff26e 100644 --- a/src/data/NotesProvider.java +++ b/src/data/NotesProvider.java @@ -34,74 +34,105 @@ import net.micode.notes.data.Notes.DataColumns; import net.micode.notes.data.Notes.NoteColumns; import net.micode.notes.data.NotesDatabaseHelper.TABLE; - +/** + * + * @Package: net.micode.notes.data + * @ClassName: NotesProvider + * @Description: 便签提供类 + */ public class NotesProvider extends ContentProvider { + //uri匹配器 private static final UriMatcher mMatcher; private NotesDatabaseHelper mHelper; private static final String TAG = "NotesProvider"; + //定义便签、数据相关的uri常量 private static final int URI_NOTE = 1; private static final int URI_NOTE_ITEM = 2; private static final int URI_DATA = 3; private static final int URI_DATA_ITEM = 4; + //定义搜索相关的uri常量 private static final int URI_SEARCH = 5; private static final int URI_SEARCH_SUGGEST = 6; + + //初始化并配置 UriMatcher 实例。将 URI 模式映射到整数值。 static { mMatcher = new UriMatcher(UriMatcher.NO_MATCH); mMatcher.addURI(Notes.AUTHORITY, "note", URI_NOTE); - mMatcher.addURI(Notes.AUTHORITY, "note/#", URI_NOTE_ITEM); + mMatcher.addURI(Notes.AUTHORITY, "note/#", URI_NOTE_ITEM);//# 表示数字占位符，匹配特定 ID mMatcher.addURI(Notes.AUTHORITY, "data", URI_DATA); - mMatcher.addURI(Notes.AUTHORITY, "data/#", URI_DATA_ITEM); + mMatcher.addURI(Notes.AUTHORITY, "data/#", URI_DATA_ITEM);//# 表示数字占位符，匹配特定 ID mMatcher.addURI(Notes.AUTHORITY, "search", URI_SEARCH); + //两个搜索建议的URI模式：一个是基本的搜索建议请求，另一个是带有查询字符串的搜索建议请求 mMatcher.addURI(Notes.AUTHORITY, SearchManager.SUGGEST_URI_PATH_QUERY, URI_SEARCH_SUGGEST); - mMatcher.addURI(Notes.AUTHORITY, SearchManager.SUGGEST_URI_PATH_QUERY + "/*", URI_SEARCH_SUGGEST); + mMatcher.addURI(Notes.AUTHORITY, SearchManager.SUGGEST_URI_PATH_QUERY + "/*", URI_SEARCH_SUGGEST);//*表示任意字符 } /** * x'0A' represents the '\n' character in sqlite. For title and content in the search result, * we will trim '\n' and white space in order to show more information. + * 定义了一个用于搜索的字符串。 */ private static final String NOTES_SEARCH_PROJECTION = NoteColumns.ID + "," + NoteColumns.ID + " AS " + SearchManager.SUGGEST_COLUMN_INTENT_EXTRA_DATA + "," + "TRIM(REPLACE(" + NoteColumns.SNIPPET + ", x'0A','')) AS " + SearchManager.SUGGEST_COLUMN_TEXT_1 + "," + //将摘要中的换行符替换为空字符串后，去除两端空字符，作为搜索结果的主文本 + "TRIM(REPLACE(" + NoteColumns.SNIPPET + ", x'0A','')) AS " + SearchManager.SUGGEST_COLUMN_TEXT_2 + "," + //与主文本内容一致 + R.drawable.search_result + " AS " + SearchManager.SUGGEST_COLUMN_ICON_1 + "," + //资源里的图片作为指定搜索结果的图标 + "'" + Intent.ACTION_VIEW + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_ACTION + "," + //显示用户的数据 作为 点击搜索结果时要执行的动作 + "'" + Notes.TextNote.CONTENT_TYPE + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_DATA; + //文本数据类型 作为 指定内容的 MIME 类型 + //定义了一个用于根据内容摘要进行搜索的SQL查询语句。 private static String NOTES_SNIPPET_SEARCH_QUERY = "SELECT " + NOTES_SEARCH_PROJECTION + " FROM " + TABLE.NOTE + " WHERE " + NoteColumns.SNIPPET + " LIKE ?" + //"?"是占位符，在查找时，将传入搜索的内容 + " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER + //不搜索垃圾文件夹中便签 + " AND " + NoteColumns.TYPE + "=" + Notes.TYPE_NOTE; + //只搜索普通便签 + //创建NotesDatabaseHelper实例 @Override public boolean onCreate() { mHelper = NotesDatabaseHelper.getInstance(getContext()); return true; } + /** + * @method query + * @description 查询数据的方法，根据传入的URI和其他参数，从数据库中检索相应的数据. + * @param [uri, projection, selection, selectionArgs, sortOrder] + * @return android.database.Cursor + */ @Override public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder) { Cursor c = null; SQLiteDatabase db = mHelper.getReadableDatabase(); String id = null; - switch (mMatcher.match(uri)) { + switch (mMatcher.match(uri)) { //根据返回的匹配码执行相应操作 case URI_NOTE: + //查Note表中的内容 c = db.query(TABLE.NOTE, projection, selection, selectionArgs, null, null, sortOrder); break; case URI_NOTE_ITEM: - id = uri.getPathSegments().get(1); + id = uri.getPathSegments().get(1);//获取便签id + //构建查询条件，确保只查询指定ID c = db.query(TABLE.NOTE, projection, NoteColumns.ID + "=" + id + parseSelection(selection), selectionArgs, null, null, sortOrder); break; case URI_DATA: + //查询数据表中的数据 c = db.query(TABLE.DATA, projection, selection, selectionArgs, null, null, sortOrder); break; @@ -113,11 +144,13 @@ public class NotesProvider extends ContentProvider { case URI_SEARCH: case URI_SEARCH_SUGGEST: if (sortOrder != null || projection != null) { + //搜索查询不允许指定排序顺序或投影 throw new IllegalArgumentException( "do not specify sortOrder, selection, selectionArgs, or projection" + "with this query"); } String searchString = null; + //从URI中提取搜索字符串 if (mMatcher.match(uri) == URI_SEARCH_SUGGEST) { if (uri.getPathSegments().size() > 1) { searchString = uri.getPathSegments().get(1); @@ -131,7 +164,8 @@ public class NotesProvider extends ContentProvider { } try { - searchString = String.format("%%%s%%", searchString); + searchString = String.format("%%%s%%", searchString);//用于模糊匹配的SQL通配符 + //执行预定义的 SQL 查询语句，传入搜索字符串作为参数 c = db.rawQuery(NOTES_SNIPPET_SEARCH_QUERY, new String[] { searchString }); } catch (IllegalStateException ex) { @@ -141,46 +175,60 @@ public class NotesProvider extends ContentProvider { default: throw new IllegalArgumentException("Unknown URI " + uri); } + //设置通知URI，以便在数据更改时通知观察者（不懂） if (c != null) { c.setNotificationUri(getContext().getContentResolver(), uri); } return c; } + /** + * @method insert + * @description 插入数据的方法，根据传入的URI和ContentValues，将数据插入到数据库中。 + * @param [uri, values] + * @return android.net.Uri 新插入数据的URI + */ @Override public Uri insert(Uri uri, ContentValues values) { SQLiteDatabase db = mHelper.getWritableDatabase(); long dataId = 0, noteId = 0, insertedId = 0; switch (mMatcher.match(uri)) { case URI_NOTE: - insertedId = noteId = db.insert(TABLE.NOTE, null, values); + insertedId = noteId = db.insert(TABLE.NOTE, null, values);//插入新的记录 break; case URI_DATA: + //确保数据关联的ID有效 if (values.containsKey(DataColumns.NOTE_ID)) { noteId = values.getAsLong(DataColumns.NOTE_ID); } else { Log.d(TAG, "Wrong data format without note id:" + values.toString()); } - insertedId = dataId = db.insert(TABLE.DATA, null, values); + insertedId = dataId = db.insert(TABLE.DATA, null, values);//插入新的数据记录 break; default: throw new IllegalArgumentException("Unknown URI " + uri); } - // Notify the note uri + // Notify the note uri 通知相关的URI，表示数据已更改 if (noteId > 0) { getContext().getContentResolver().notifyChange( ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId), null); } - // Notify the data uri + // Notify the data uri 通知相关的数据URI，表示数据已更改 if (dataId > 0) { getContext().getContentResolver().notifyChange( ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, dataId), null); } - return ContentUris.withAppendedId(uri, insertedId); + return ContentUris.withAppendedId(uri, insertedId); //返回新插入的URI } + /** + * @method delete + * @description 删除 + * @param [uri, selection, selectionArgs] + * @return int + */ @Override public int delete(Uri uri, String selection, String[] selectionArgs) { int count = 0; @@ -189,10 +237,11 @@ public class NotesProvider extends ContentProvider { boolean deleteData = false; switch (mMatcher.match(uri)) { case URI_NOTE: - selection = "(" + selection + ") AND " + NoteColumns.ID + ">0 "; - count = db.delete(TABLE.NOTE, selection, selectionArgs); + selection = "(" + selection + ") AND " + NoteColumns.ID + ">0 ";//确保不删除系统文件夹 + count = db.delete(TABLE.NOTE, selection, selectionArgs);//删除相关便签，返回删除的记录数 break; case URI_NOTE_ITEM: + //获取要删除的id id = uri.getPathSegments().get(1); /** * ID that smaller than 0 is system folder which is not allowed to @@ -219,14 +268,22 @@ public class NotesProvider extends ContentProvider { throw new IllegalArgumentException("Unknown URI " + uri); } if (count > 0) { + //如果删除了data记录，通知相关的note URI if (deleteData) { getContext().getContentResolver().notifyChange(Notes.CONTENT_NOTE_URI, null); } + //通知传入的URI，表示数据已更改 getContext().getContentResolver().notifyChange(uri, null); } return count; } + /** + * @method update + * @description 更新数据库中的记录 + * @param [uri, values, selection, selectionArgs] + * @return int 影响的行数 + */ @Override public int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) { int count = 0; @@ -235,7 +292,7 @@ public class NotesProvider extends ContentProvider { boolean updateData = false; switch (mMatcher.match(uri)) { case URI_NOTE: - increaseNoteVersion(-1, selection, selectionArgs); + increaseNoteVersion(-1, selection, selectionArgs);//更新便签版本号 count = db.update(TABLE.NOTE, values, selection, selectionArgs); break; case URI_NOTE_ITEM: @@ -260,42 +317,60 @@ public class NotesProvider extends ContentProvider { if (count > 0) { if (updateData) { - getContext().getContentResolver().notifyChange(Notes.CONTENT_NOTE_URI, null); + getContext().getContentResolver().notifyChange(Notes.CONTENT_NOTE_URI, null);//通知便签URI数据已更改 } getContext().getContentResolver().notifyChange(uri, null); } return count; } + /** + * @method parseSelection + * @description //辅助方法，用于解析查询条件字符串，确保在已有条件的基础上正确添加新的条件。 + * @param selection + * @return String + */ private String parseSelection(String selection) { + //如果selection不为空，则在前面加上" AND ("，并在后面加上")"，否则返回空字符串 return (!TextUtils.isEmpty(selection) ? " AND (" + selection + ')' : ""); } + /** + * @method increaseNoteVersion + * @description 增加便签的版本号，用于标识便签的更新状态。 + * @param + * @return + */ private void increaseNoteVersion(long id, String selection, String[] selectionArgs) { - StringBuilder sql = new StringBuilder(120); + StringBuilder sql = new StringBuilder(120);//初始化一个容量为120的StringBuilder对象，用于构建SQL语句 + //构建更新便签版本号的SQL语句 sql.append("UPDATE "); sql.append(TABLE.NOTE); sql.append(" SET "); sql.append(NoteColumns.VERSION); sql.append("=" + NoteColumns.VERSION + "+1 "); + //如果指定了id或selection，则添加WHERE子句 if (id > 0 || !TextUtils.isEmpty(selection)) { sql.append(" WHERE "); } + //如果指定了id，则添加ID条件 if (id > 0) { sql.append(NoteColumns.ID + "=" + String.valueOf(id)); } + if (!TextUtils.isEmpty(selection)) { String selectString = id > 0 ? parseSelection(selection) : selection; for (String args : selectionArgs) { - selectString = selectString.replaceFirst("\\?", args); + selectString = selectString.replaceFirst("\\?", args);//将每个占位符 '?' 替换为实际的参数值 } sql.append(selectString); } - mHelper.getWritableDatabase().execSQL(sql.toString()); + mHelper.getWritableDatabase().execSQL(sql.toString());//执行构建好的SQL语句 } + //未实现：获取URI对应的MIME类型 @Override public String getType(Uri uri) { // TODO Auto-generated method stub diff --git a/src/gtask/data/MetaData.java b/src/gtask/data/MetaData.java index 3a2050b..d8bc462 100644 --- a/src/gtask/data/MetaData.java +++ b/src/gtask/data/MetaData.java @@ -25,6 +25,11 @@ import org.json.JSONException; import org.json.JSONObject; +/** + * @Package: net.micode.notes.gtask.data + * @ClassName: MetaData + * @Description: 存储和管理Google Task同步相关的元数据，维护本地便签与Google Task任务的关联关系 + */ public class MetaData extends Task { private final static String TAG = MetaData.class.getSimpleName(); @@ -47,7 +52,7 @@ public class MetaData extends Task { @Override public boolean isWorthSaving() { return getNotes() != null; - } + }//只要便签非空，就认为值得保存 @Override public void setContentByRemoteJSON(JSONObject js) { @@ -66,16 +71,19 @@ public class MetaData extends Task { @Override public void setContentByLocalJSON(JSONObject js) { // this function should not be called + //功能是被禁止调用的，因为元数据不从本地 JSON 设置内容 throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called"); } @Override public JSONObject getLocalJSONFromContent() { + //功能是被禁止调用的，因为元数据不生成本地 JSON 内容 throw new IllegalAccessError("MetaData:getLocalJSONFromContent should not be called"); } @Override public int getSyncAction(Cursor c) { + //功能是被禁止调用的，因为元数据不参与同步操作 throw new IllegalAccessError("MetaData:getSyncAction should not be called"); } diff --git a/src/gtask/data/Node.java b/src/gtask/data/Node.java index 63950e0..7be302a 100644 --- a/src/gtask/data/Node.java +++ b/src/gtask/data/Node.java @@ -18,9 +18,17 @@ package net.micode.notes.gtask.data; import android.database.Cursor; + import org.json.JSONObject; +/** + * + * @Package: net.micode.notes.gtask.data + * @ClassName: Node + * @Description: 抽象类，表示同步节点的基本属性和行为。 + */ public abstract class Node { + //同步操作类型常量定义 public static final int SYNC_ACTION_NONE = 0; public static final int SYNC_ACTION_ADD_REMOTE = 1; @@ -39,6 +47,7 @@ public abstract class Node { public static final int SYNC_ACTION_ERROR = 8; + // 节点的全局唯一标识符 private String mGid; private String mName; @@ -47,6 +56,7 @@ public abstract class Node { private boolean mDeleted; + // 构造函数，初始化节点的基本属性 public Node() { mGid = null; mName = ""; @@ -54,7 +64,15 @@ public abstract class Node { mDeleted = false; } - public abstract JSONObject getCreateAction(int actionId); + /** + * 定义了一些方法:创建节点的远程和本地同步操作的 JSON 表示 + * 从远程和本地 JSON 设置节点内容 + * 从数据库游标获取同步操作类型 + * 以及节点属性的 get和 set 方法 + */ + + + public abstract JSONObject getCreateAction(int actionId);// public abstract JSONObject getUpdateAction(int actionId); diff --git a/src/gtask/data/SqlData.java b/src/gtask/data/SqlData.java index d3ec3be..e16fcc6 100644 --- a/src/gtask/data/SqlData.java +++ b/src/gtask/data/SqlData.java @@ -34,17 +34,24 @@ import net.micode.notes.gtask.exception.ActionFailureException; import org.json.JSONException; import org.json.JSONObject; - +/** + * + * @Package: net.micode.notes.gtask.data + * @ClassName: SqlData + * @Description: 为Google Task同步功能提供数据层支持，将便签数据抽象为可序列化的对象 + */ public class SqlData { private static final String TAG = SqlData.class.getSimpleName(); private static final int INVALID_ID = -99999; + //包含便签数据表的核心字段，用于查询和加载数据 public static final String[] PROJECTION_DATA = new String[] { DataColumns.ID, DataColumns.MIME_TYPE, DataColumns.CONTENT, DataColumns.DATA1, DataColumns.DATA3 }; + // 查询结果列索引常量，提高代码可读性和维护性 public static final int DATA_ID_COLUMN = 0; public static final int DATA_MIME_TYPE_COLUMN = 1; @@ -57,7 +64,7 @@ public class SqlData { private ContentResolver mContentResolver; - private boolean mIsCreate; + private boolean mIsCreate;// 标记是否为新建数据 private long mDataId; @@ -69,19 +76,21 @@ public class SqlData { private String mDataContentData3; - private ContentValues mDiffDataValues; + private ContentValues mDiffDataValues;// 存储数据变化的ContentValues + //构造函数：新建便签 public SqlData(Context context) { mContentResolver = context.getContentResolver(); mIsCreate = true; mDataId = INVALID_ID; mDataMimeType = DataConstants.NOTE; - mDataContent = ""; + mDataContent = "";// 初始内容为空 mDataContentData1 = 0; mDataContentData3 = ""; mDiffDataValues = new ContentValues(); } + //构造函数：从数据库游标加载现有数据 public SqlData(Context context, Cursor c) { mContentResolver = context.getContentResolver(); mIsCreate = false; @@ -89,6 +98,7 @@ public class SqlData { mDiffDataValues = new ContentValues(); } + //从数据库游标加载数据到对象字段 private void loadFromCursor(Cursor c) { mDataId = c.getLong(DATA_ID_COLUMN); mDataMimeType = c.getString(DATA_MIME_TYPE_COLUMN); @@ -97,13 +107,16 @@ public class SqlData { mDataContentData3 = c.getString(DATA_CONTENT_DATA_3_COLUMN); } + //将JSON格式的数据解析并设置到对象字段 public void setContent(JSONObject js) throws JSONException { - long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID; + // 处理数据ID + long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID;//如果有ID字段则取值，否则设为无效ID if (mIsCreate || mDataId != dataId) { mDiffDataValues.put(DataColumns.ID, dataId); - } + }//如果是新建数据或ID发生变化，记录变化 mDataId = dataId; + //处理MIME类型 String dataMimeType = js.has(DataColumns.MIME_TYPE) ? js.getString(DataColumns.MIME_TYPE) : DataConstants.NOTE; if (mIsCreate || !mDataMimeType.equals(dataMimeType)) { @@ -111,18 +124,21 @@ public class SqlData { } mDataMimeType = dataMimeType; + //处理数据内容 String dataContent = js.has(DataColumns.CONTENT) ? js.getString(DataColumns.CONTENT) : ""; if (mIsCreate || !mDataContent.equals(dataContent)) { mDiffDataValues.put(DataColumns.CONTENT, dataContent); } mDataContent = dataContent; + //处理扩展数据1 long dataContentData1 = js.has(DataColumns.DATA1) ? js.getLong(DataColumns.DATA1) : 0; if (mIsCreate || mDataContentData1 != dataContentData1) { mDiffDataValues.put(DataColumns.DATA1, dataContentData1); } mDataContentData1 = dataContentData1; + // 处理扩展数据3 String dataContentData3 = js.has(DataColumns.DATA3) ? js.getString(DataColumns.DATA3) : ""; if (mIsCreate || !mDataContentData3.equals(dataContentData3)) { mDiffDataValues.put(DataColumns.DATA3, dataContentData3); @@ -130,6 +146,7 @@ public class SqlData { mDataContentData3 = dataContentData3; } + //将对象字段序列化为JSON格式，用于网络传输或数据交换 public JSONObject getContent() throws JSONException { if (mIsCreate) { Log.e(TAG, "it seems that we haven't created this in database yet"); @@ -144,25 +161,44 @@ public class SqlData { return js; } + /** + * @method commit + * @description 提交数据到数据库 + * 执行流程： + * 1. 新数据：执行INSERT操作，插入后从URI中提取新数据的ID + * 2. 现有数据：执行UPDATE操作，支持版本验证 + * 3. 清除变更记录，更新对象状态 + * @param noteId 关联的便签ID + * @param validateVersion 是否验证版本号 + * @param version 期望的版本号 + */ public void commit(long noteId, boolean validateVersion, long version) { - + // 新数据：执行INSERT操作 if (mIsCreate) { + // 如果ID是无效值，从变更记录中移除ID字段 if (mDataId == INVALID_ID && mDiffDataValues.containsKey(DataColumns.ID)) { mDiffDataValues.remove(DataColumns.ID); } + // 设置关联的便签ID mDiffDataValues.put(DataColumns.NOTE_ID, noteId); + + // 执行插入操作 Uri uri = mContentResolver.insert(Notes.CONTENT_DATA_URI, mDiffDataValues); + try { - mDataId = Long.valueOf(uri.getPathSegments().get(1)); + mDataId = Long.valueOf(uri.getPathSegments().get(1));//从返回的URI中提取新数据的ID } catch (NumberFormatException e) { Log.e(TAG, "Get note id error :" + e.toString()); throw new ActionFailureException("create note failed"); } - } else { + } + //现有数据：执行UPDATE操作 + else { if (mDiffDataValues.size() > 0) { int result = 0; if (!validateVersion) { + // 不验证版本：直接更新 result = mContentResolver.update(ContentUris.withAppendedId( Notes.CONTENT_DATA_URI, mDataId), mDiffDataValues, null, null); } else { @@ -179,6 +215,7 @@ public class SqlData { } } + // 清除变更记录，更新对象状态 mDiffDataValues.clear(); mIsCreate = false; } diff --git a/src/gtask/data/SqlNote.java b/src/gtask/data/SqlNote.java index 79a4095..152aa98 100644 --- a/src/gtask/data/SqlNote.java +++ b/src/gtask/data/SqlNote.java @@ -38,103 +38,91 @@ import org.json.JSONObject; import java.util.ArrayList; +/** + * + * @Package: net.micode.notes.gtask.data + * @ClassName: SqlNote + * @Description: 管理便签的所有属性、数据和关联关系 + */ public class SqlNote { - private static final String TAG = SqlNote.class.getSimpleName(); + private static final String TAG = SqlNote.class.getSimpleName(); // 日志标签 - private static final int INVALID_ID = -99999; + private static final int INVALID_ID = -99999; // 无效ID常量，表示便签尚未保存到数据库 + //便签表的所有字段，用于查询和加载便签 public static final String[] PROJECTION_NOTE = new String[] { - NoteColumns.ID, NoteColumns.ALERTED_DATE, NoteColumns.BG_COLOR_ID, - NoteColumns.CREATED_DATE, NoteColumns.HAS_ATTACHMENT, NoteColumns.MODIFIED_DATE, - NoteColumns.NOTES_COUNT, NoteColumns.PARENT_ID, NoteColumns.SNIPPET, NoteColumns.TYPE, - NoteColumns.WIDGET_ID, NoteColumns.WIDGET_TYPE, NoteColumns.SYNC_ID, - NoteColumns.LOCAL_MODIFIED, NoteColumns.ORIGIN_PARENT_ID, NoteColumns.GTASK_ID, - NoteColumns.VERSION + NoteColumns.ID, // 便签ID + NoteColumns.ALERTED_DATE, // 提醒日期 + NoteColumns.BG_COLOR_ID, // 背景颜色ID + NoteColumns.CREATED_DATE, // 创建日期 + NoteColumns.HAS_ATTACHMENT, // 是否有附件 + NoteColumns.MODIFIED_DATE, // 修改日期 + NoteColumns.NOTES_COUNT, // 子便签数量 + NoteColumns.PARENT_ID, // 父文件夹ID + NoteColumns.SNIPPET, // 片段内容 + NoteColumns.TYPE, // 便签类型 + NoteColumns.WIDGET_ID, // 小部件ID + NoteColumns.WIDGET_TYPE, // 小部件类型 + NoteColumns.SYNC_ID, // 同步ID + NoteColumns.LOCAL_MODIFIED, // 本地修改标记 + NoteColumns.ORIGIN_PARENT_ID, // 原始父文件夹ID + NoteColumns.GTASK_ID, // Google Task ID + NoteColumns.VERSION // 版本号 }; + // 查询结果列索引常量 public static final int ID_COLUMN = 0; - public static final int ALERTED_DATE_COLUMN = 1; - public static final int BG_COLOR_ID_COLUMN = 2; - public static final int CREATED_DATE_COLUMN = 3; - public static final int HAS_ATTACHMENT_COLUMN = 4; - public static final int MODIFIED_DATE_COLUMN = 5; - public static final int NOTES_COUNT_COLUMN = 6; - public static final int PARENT_ID_COLUMN = 7; - public static final int SNIPPET_COLUMN = 8; - public static final int TYPE_COLUMN = 9; - public static final int WIDGET_ID_COLUMN = 10; - public static final int WIDGET_TYPE_COLUMN = 11; - public static final int SYNC_ID_COLUMN = 12; - public static final int LOCAL_MODIFIED_COLUMN = 13; - public static final int ORIGIN_PARENT_ID_COLUMN = 14; - public static final int GTASK_ID_COLUMN = 15; - public static final int VERSION_COLUMN = 16; - private Context mContext; - - private ContentResolver mContentResolver; - - private boolean mIsCreate; - + private Context mContext; // Android上下文 + private ContentResolver mContentResolver; // ContentResolver，用于数据库操作 + private boolean mIsCreate; // 标记是否为新建便签 private long mId; - private long mAlertDate; - private int mBgColorId; - private long mCreatedDate; - - private int mHasAttachment; - + private int mHasAttachment; // 是否有附件（0无，1有） private long mModifiedDate; - - private long mParentId; - - private String mSnippet; - - private int mType; - + private long mParentId; // 父文件夹ID + private String mSnippet; // 摘要 + private int mType; // 便签类型（NOTE/FOLDER/SYSTEM） private int mWidgetId; - private int mWidgetType; + private long mOriginParent; // 原始父文件夹ID（用于恢复操作） + private long mVersion; // 版本号 - private long mOriginParent; - - private long mVersion; - - private ContentValues mDiffNoteValues; - - private ArrayList mDataList; + private ContentValues mDiffNoteValues; // 存储便签变化的ContentValues + private ArrayList mDataList; // 关联的数据列表（仅TYPE_NOTE类型） + //构造函数：创建新便签 public SqlNote(Context context) { mContext = context; mContentResolver = context.getContentResolver(); mIsCreate = true; - mId = INVALID_ID; - mAlertDate = 0; + mId = INVALID_ID; // 新便签ID无效 + mAlertDate = 0; // 默认无提醒 mBgColorId = ResourceParser.getDefaultBgId(context); mCreatedDate = System.currentTimeMillis(); mHasAttachment = 0; mModifiedDate = System.currentTimeMillis(); - mParentId = 0; - mSnippet = ""; - mType = Notes.TYPE_NOTE; + mParentId = 0; // 默认父文件夹为根目录 + mSnippet = ""; // 默认摘要内容为空 + mType = Notes.TYPE_NOTE; // 默认为普通便签 mWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID; mWidgetType = Notes.TYPE_WIDGET_INVALIDE; mOriginParent = 0; @@ -143,35 +131,38 @@ public class SqlNote { mDataList = new ArrayList(); } + //构造函数：从数据库游标加载现有便签 public SqlNote(Context context, Cursor c) { mContext = context; mContentResolver = context.getContentResolver(); mIsCreate = false; loadFromCursor(c); - mDataList = new ArrayList(); - if (mType == Notes.TYPE_NOTE) + mDataList = new ArrayList(); // 初始化数据列表 + if (mType == Notes.TYPE_NOTE) // 如果是普通便签，加载数据内容 loadDataContent(); - mDiffNoteValues = new ContentValues(); + mDiffNoteValues = new ContentValues(); // 初始化变化值容器 } + //构造函数：根据便签ID加载现有便签 public SqlNote(Context context, long id) { mContext = context; mContentResolver = context.getContentResolver(); mIsCreate = false; - loadFromCursor(id); + loadFromCursor(id); // 根据ID加载便签 mDataList = new ArrayList(); if (mType == Notes.TYPE_NOTE) loadDataContent(); mDiffNoteValues = new ContentValues(); - } + + //根据便签ID从数据库加载便签 private void loadFromCursor(long id) { Cursor c = null; try { c = mContentResolver.query(Notes.CONTENT_NOTE_URI, PROJECTION_NOTE, "(_id=?)", new String[] { - String.valueOf(id) + String.valueOf(id) }, null); if (c != null) { c.moveToNext(); @@ -181,10 +172,11 @@ public class SqlNote { } } finally { if (c != null) - c.close(); + c.close(); // 关闭游标 } } + //从数据库游标加载便签属性 private void loadFromCursor(Cursor c) { mId = c.getLong(ID_COLUMN); mAlertDate = c.getLong(ALERTED_DATE_COLUMN); @@ -200,13 +192,20 @@ public class SqlNote { mVersion = c.getLong(VERSION_COLUMN); } + /** + * 加载便签关联的数据内容 + * 执行流程： + * 1. 根据便签ID查询数据表 + * 2. 遍历查询结果，创建SqlData对象 + * 3. 将SqlData对象添加到数据列表 + */ private void loadDataContent() { Cursor c = null; - mDataList.clear(); + mDataList.clear(); // 清空现有数据列表 try { c = mContentResolver.query(Notes.CONTENT_DATA_URI, SqlData.PROJECTION_DATA, "(note_id=?)", new String[] { - String.valueOf(mId) + String.valueOf(mId) }, null); if (c != null) { if (c.getCount() == 0) { @@ -226,13 +225,27 @@ public class SqlNote { } } + /** + * @method setContent + * @description 功能：将JSON格式的便签数据解析并设置到对象字段 + * 执行流程： + * 1. 提取便签元数据部分 + * 2. 根据便签类型分别处理 + * 3. 记录哪些字段发生了变化，用于后续的增量更新 + * @param js 包含便签信息的JSON对象 + * @return + */ public boolean setContent(JSONObject js) { try { JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE); + + // 系统文件夹：不能设置 if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_SYSTEM) { Log.w(TAG, "cannot set system folder"); - } else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) { - // for folder we can only update the snnipet and type + } + // 文件夹：只能更新片段和类型 + else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) { + // 处理片段内容 String snippet = note.has(NoteColumns.SNIPPET) ? note .getString(NoteColumns.SNIPPET) : ""; if (mIsCreate || !mSnippet.equals(snippet)) { @@ -240,20 +253,26 @@ public class SqlNote { } mSnippet = snippet; + // 处理类型 int type = note.has(NoteColumns.TYPE) ? note.getInt(NoteColumns.TYPE) : Notes.TYPE_NOTE; if (mIsCreate || mType != type) { mDiffNoteValues.put(NoteColumns.TYPE, type); } mType = type; - } else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_NOTE) { + } + // 普通便签：处理所有字段 + else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_NOTE) { JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA); + + // 处理便签ID long id = note.has(NoteColumns.ID) ? note.getLong(NoteColumns.ID) : INVALID_ID; if (mIsCreate || mId != id) { mDiffNoteValues.put(NoteColumns.ID, id); } mId = id; + // 处理提醒日期 long alertDate = note.has(NoteColumns.ALERTED_DATE) ? note .getLong(NoteColumns.ALERTED_DATE) : 0; if (mIsCreate || mAlertDate != alertDate) { @@ -261,6 +280,7 @@ public class SqlNote { } mAlertDate = alertDate; + // 处理背景颜色ID int bgColorId = note.has(NoteColumns.BG_COLOR_ID) ? note .getInt(NoteColumns.BG_COLOR_ID) : ResourceParser.getDefaultBgId(mContext); if (mIsCreate || mBgColorId != bgColorId) { @@ -268,6 +288,7 @@ public class SqlNote { } mBgColorId = bgColorId; + // 处理创建日期 long createDate = note.has(NoteColumns.CREATED_DATE) ? note .getLong(NoteColumns.CREATED_DATE) : System.currentTimeMillis(); if (mIsCreate || mCreatedDate != createDate) { @@ -275,6 +296,7 @@ public class SqlNote { } mCreatedDate = createDate; + // 处理附件标记 int hasAttachment = note.has(NoteColumns.HAS_ATTACHMENT) ? note .getInt(NoteColumns.HAS_ATTACHMENT) : 0; if (mIsCreate || mHasAttachment != hasAttachment) { @@ -282,6 +304,7 @@ public class SqlNote { } mHasAttachment = hasAttachment; + // 处理修改日期 long modifiedDate = note.has(NoteColumns.MODIFIED_DATE) ? note .getLong(NoteColumns.MODIFIED_DATE) : System.currentTimeMillis(); if (mIsCreate || mModifiedDate != modifiedDate) { @@ -289,6 +312,7 @@ public class SqlNote { } mModifiedDate = modifiedDate; + // 处理父文件夹ID long parentId = note.has(NoteColumns.PARENT_ID) ? note .getLong(NoteColumns.PARENT_ID) : 0; if (mIsCreate || mParentId != parentId) { @@ -296,6 +320,7 @@ public class SqlNote { } mParentId = parentId; + // 处理片段内容 String snippet = note.has(NoteColumns.SNIPPET) ? note .getString(NoteColumns.SNIPPET) : ""; if (mIsCreate || !mSnippet.equals(snippet)) { @@ -303,6 +328,7 @@ public class SqlNote { } mSnippet = snippet; + // 处理类型 int type = note.has(NoteColumns.TYPE) ? note.getInt(NoteColumns.TYPE) : Notes.TYPE_NOTE; if (mIsCreate || mType != type) { @@ -310,6 +336,7 @@ public class SqlNote { } mType = type; + // 处理小部件ID int widgetId = note.has(NoteColumns.WIDGET_ID) ? note.getInt(NoteColumns.WIDGET_ID) : AppWidgetManager.INVALID_APPWIDGET_ID; if (mIsCreate || mWidgetId != widgetId) { @@ -317,6 +344,7 @@ public class SqlNote { } mWidgetId = widgetId; + // 处理小部件类型 int widgetType = note.has(NoteColumns.WIDGET_TYPE) ? note .getInt(NoteColumns.WIDGET_TYPE) : Notes.TYPE_WIDGET_INVALIDE; if (mIsCreate || mWidgetType != widgetType) { @@ -324,6 +352,7 @@ public class SqlNote { } mWidgetType = widgetType; + // 处理原始父文件夹ID long originParent = note.has(NoteColumns.ORIGIN_PARENT_ID) ? note .getLong(NoteColumns.ORIGIN_PARENT_ID) : 0; if (mIsCreate || mOriginParent != originParent) { @@ -331,23 +360,29 @@ public class SqlNote { } mOriginParent = originParent; + // 处理数据内容 for (int i = 0; i < dataArray.length(); i++) { JSONObject data = dataArray.getJSONObject(i); SqlData sqlData = null; + + // 查找现有的数据对象 if (data.has(DataColumns.ID)) { long dataId = data.getLong(DataColumns.ID); for (SqlData temp : mDataList) { if (dataId == temp.getId()) { sqlData = temp; + break; } } } + // 如果没找到，创建新的数据对象 if (sqlData == null) { sqlData = new SqlData(mContext); mDataList.add(sqlData); } + // 设置数据内容 sqlData.setContent(data); } } @@ -359,6 +394,13 @@ public class SqlNote { return true; } + + /** + * @method getContent + * @description 将便签对象序列化为JSON格式，用于网络传输或数据交换 + * @param + * @return JSONObject 包含便签内容的JSON对象 + */ public JSONObject getContent() { try { JSONObject js = new JSONObject(); @@ -369,6 +411,8 @@ public class SqlNote { } JSONObject note = new JSONObject(); + + // 普通便签：包含完整字段和数据 if (mType == Notes.TYPE_NOTE) { note.put(NoteColumns.ID, mId); note.put(NoteColumns.ALERTED_DATE, mAlertDate); @@ -384,6 +428,7 @@ public class SqlNote { note.put(NoteColumns.ORIGIN_PARENT_ID, mOriginParent); js.put(GTaskStringUtils.META_HEAD_NOTE, note); + // 添加数据内容 JSONArray dataArray = new JSONArray(); for (SqlData sqlData : mDataList) { JSONObject data = sqlData.getContent(); @@ -392,7 +437,9 @@ public class SqlNote { } } js.put(GTaskStringUtils.META_HEAD_DATA, dataArray); - } else if (mType == Notes.TYPE_FOLDER || mType == Notes.TYPE_SYSTEM) { + } + // 文件夹和系统文件夹：仅包含ID、类型和片段 + else if (mType == Notes.TYPE_FOLDER || mType == Notes.TYPE_SYSTEM) { note.put(NoteColumns.ID, mId); note.put(NoteColumns.TYPE, mType); note.put(NoteColumns.SNIPPET, mSnippet); @@ -407,86 +454,118 @@ public class SqlNote { return null; } + public void setParentId(long id) { mParentId = id; mDiffNoteValues.put(NoteColumns.PARENT_ID, id); } + //设置Google Task ID public void setGtaskId(String gid) { mDiffNoteValues.put(NoteColumns.GTASK_ID, gid); } + //设置同步ID public void setSyncId(long syncId) { mDiffNoteValues.put(NoteColumns.SYNC_ID, syncId); } + //重置本地修改标记。在同步完成后调用，表示便签已经与远程同步 public void resetLocalModified() { mDiffNoteValues.put(NoteColumns.LOCAL_MODIFIED, 0); } + public long getId() { return mId; } + public long getParentId() { return mParentId; } + public String getSnippet() { return mSnippet; } + //判断是否为普通便签类型 public boolean isNoteType() { return mType == Notes.TYPE_NOTE; } + + /** + * @method commit + * @description 提交便签到数据库 + * @param validateVersion 是否验证版本号 + * @return + */ public void commit(boolean validateVersion) { + // 新便签：执行INSERT操作 if (mIsCreate) { + // 如果ID是无效值，从变更记录中移除ID字段，让数据库自动生成 if (mId == INVALID_ID && mDiffNoteValues.containsKey(NoteColumns.ID)) { mDiffNoteValues.remove(NoteColumns.ID); } + // 执行插入操作 Uri uri = mContentResolver.insert(Notes.CONTENT_NOTE_URI, mDiffNoteValues); try { + // 从返回的URI中提取新便签的ID + // URI格式：content://authority/note/{note_id} mId = Long.valueOf(uri.getPathSegments().get(1)); } catch (NumberFormatException e) { Log.e(TAG, "Get note id error :" + e.toString()); throw new ActionFailureException("create note failed"); } + if (mId == 0) { throw new IllegalStateException("Create thread id failed"); } + // 如果是普通便签，提交关联的所有数据 if (mType == Notes.TYPE_NOTE) { for (SqlData sqlData : mDataList) { sqlData.commit(mId, false, -1); } } - } else { + } + // 现有便签：执行UPDATE操作 + else { + // 检查便签ID有效性 if (mId <= 0 && mId != Notes.ID_ROOT_FOLDER && mId != Notes.ID_CALL_RECORD_FOLDER) { Log.e(TAG, "No such note"); throw new IllegalStateException("Try to update note with invalid id"); } + + // 如果有变更，执行更新操作 if (mDiffNoteValues.size() > 0) { - mVersion ++; + mVersion ++; // 版本号自增 int result = 0; + if (!validateVersion) { + // 不验证版本：直接更新 result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "(" + NoteColumns.ID + "=?)", new String[] { - String.valueOf(mId) + String.valueOf(mId) }); } else { + // 验证版本：使用乐观锁机制 result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "(" - + NoteColumns.ID + "=?) AND (" + NoteColumns.VERSION + "<=?)", + + NoteColumns.ID + "=?) AND (" + NoteColumns.VERSION + "<=?)", new String[] { String.valueOf(mId), String.valueOf(mVersion) }); } + if (result == 0) { Log.w(TAG, "there is no update. maybe user updates note when syncing"); } } + // 如果是普通便签，提交关联的所有数据 if (mType == Notes.TYPE_NOTE) { for (SqlData sqlData : mDataList) { sqlData.commit(mId, validateVersion, mVersion); @@ -494,12 +573,13 @@ public class SqlNote { } } - // refresh local info + // 刷新本地信息：重新从数据库加载，确保数据一致性 loadFromCursor(mId); if (mType == Notes.TYPE_NOTE) loadDataContent(); + // 清除变更记录，更新对象状态 mDiffNoteValues.clear(); mIsCreate = false; } -} +} \ No newline at end of file diff --git a/src/gtask/data/Task.java b/src/gtask/data/Task.java index 6a19454..e6871dd 100644 --- a/src/gtask/data/Task.java +++ b/src/gtask/data/Task.java @@ -31,19 +31,24 @@ import org.json.JSONArray; import org.json.JSONException; import org.json.JSONObject; - +/** + * + * @Package: net.micode.notes.gtask.data + * @ClassName: Task + * @Description: 表示任务节点，包含任务的具体属性和行为 + */ public class Task extends Node { private static final String TAG = Task.class.getSimpleName(); - private boolean mCompleted; + private boolean mCompleted;//任务是否完成 - private String mNotes; + private String mNotes;//任务 - private JSONObject mMetaInfo; + private JSONObject mMetaInfo; //任务的元数据信息 - private Task mPriorSibling; + private Task mPriorSibling;//任务的前一个兄弟任务 - private TaskList mParent; + private TaskList mParent; //任务所属的任务列表 public Task() { super(); @@ -54,21 +59,31 @@ public class Task extends Node { mMetaInfo = null; } + /** + * @method getCreateAction + * @description 生成任务创建操作的 JSON 对象表示 + * @param actionId + * @return JSONObject + */ public JSONObject getCreateAction(int actionId) { JSONObject js = new JSONObject(); try { // action_type + //添加任务创建操作的类型标识 js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE, GTaskStringUtils.GTASK_JSON_ACTION_TYPE_CREATE); // action_id + //添加操作的唯一标识符 js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId); // index + //添加任务在其父任务列表中的索引位置 js.put(GTaskStringUtils.GTASK_JSON_INDEX, mParent.getChildTaskIndex(this)); // entity_delta + //初始化entity,表示任务的具体属性,添加名称、创建者标识、类型和便签 JSONObject entity = new JSONObject(); entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName()); entity.put(GTaskStringUtils.GTASK_JSON_CREATOR_ID, "null"); @@ -77,19 +92,25 @@ public class Task extends Node { if (getNotes() != null) { entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes()); } + + //添加任务的完成状态 js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity); // parent_id + //添加任务所属的父任务列表的标识符 js.put(GTaskStringUtils.GTASK_JSON_PARENT_ID, mParent.getGid()); // dest_parent_type + //添加任务所属的父任务列表的类型标识 js.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT_TYPE, GTaskStringUtils.GTASK_JSON_TYPE_GROUP); // list_id + //添加任务所属的任务列表的标识符 js.put(GTaskStringUtils.GTASK_JSON_LIST_ID, mParent.getGid()); // prior_sibling_id + //添加任务的前一个兄弟任务的标识符（如果有的话） if (mPriorSibling != null) { js.put(GTaskStringUtils.GTASK_JSON_PRIOR_SIBLING_ID, mPriorSibling.getGid()); } @@ -103,6 +124,12 @@ public class Task extends Node { return js; } + /** + * @method getUpdateAction + * @description 生成任务更新操作的 JSON 对象表示 + * @param actionId + * @return JSONObject + */ public JSONObject getUpdateAction(int actionId) { JSONObject js = new JSONObject(); @@ -135,6 +162,12 @@ public class Task extends Node { return js; } + /** + * @method setContentByRemoteJSON + * @description 从远程 JSON 对象设置任务的内容 + * @param js 包含任务内容的 JSON 对象 + * @return + */ public void setContentByRemoteJSON(JSONObject js) { if (js != null) { try { @@ -175,7 +208,14 @@ public class Task extends Node { } } + /** + * @method setContentByLocalJSON + * @description 从本地 JSON 对象设置任务的内容 + * @param js 包含任务内容的 JSON 对象 + * @return + */ public void setContentByLocalJSON(JSONObject js) { + //如果传入的 JSON 对象为空或缺少必要的字段，则记录警告日志 if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE) || !js.has(GTaskStringUtils.META_HEAD_DATA)) { Log.w(TAG, "setContentByLocalJSON: nothing is avaiable"); @@ -185,6 +225,7 @@ public class Task extends Node { JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE); JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA); + //如果类型不匹配，则记录错误日志并返回 if (note.getInt(NoteColumns.TYPE) != Notes.TYPE_NOTE) { Log.e(TAG, "invalid type"); return; @@ -192,6 +233,7 @@ public class Task extends Node { for (int i = 0; i < dataArray.length(); i++) { JSONObject data = dataArray.getJSONObject(i); + //找到文本便签的数据，并设置任务的名称 if (TextUtils.equals(data.getString(DataColumns.MIME_TYPE), DataConstants.NOTE)) { setName(data.getString(DataColumns.CONTENT)); break; @@ -204,9 +246,15 @@ public class Task extends Node { } } + /** + * @method getLocalJSONFromContent + * @description 将任务的内容转换为本地 JSON 对象表示 + * @return JSONObject 表示任务内容的本地 JSON 对象 + */ public JSONObject getLocalJSONFromContent() { String name = getName(); try { + //如果元数据信息为空，表示是从远程创建的新任务 if (mMetaInfo == null) { // new task created from web if (name == null) { @@ -218,6 +266,7 @@ public class Task extends Node { JSONObject note = new JSONObject(); JSONArray dataArray = new JSONArray(); JSONObject data = new JSONObject(); + //构建表示任务内容的本地 JSON 对象 data.put(DataColumns.CONTENT, name); dataArray.put(data); js.put(GTaskStringUtils.META_HEAD_DATA, dataArray); @@ -247,10 +296,16 @@ public class Task extends Node { } } + /** + * @method setMetaInfo + * @description 设置任务的元数据信息 + * @param metaData 包含任务元数据信息的 MetaData 对象 + * @return + */ public void setMetaInfo(MetaData metaData) { if (metaData != null && metaData.getNotes() != null) { try { - mMetaInfo = new JSONObject(metaData.getNotes()); + mMetaInfo = new JSONObject(metaData.getNotes());//将 MetaData 对象的便签信息解析为 JSON 对象并存储 } catch (JSONException e) { Log.w(TAG, e.toString()); mMetaInfo = null; @@ -258,6 +313,12 @@ public class Task extends Node { } } + /** + * @method getSyncAction + * @description 确定任务与本地数据的同步操作类型 + * @param c：表示本地任务数据的数据库游标 + * @return int：表示同步操作类型的整数值 + */ public int getSyncAction(Cursor c) { try { JSONObject noteInfo = null; @@ -276,18 +337,21 @@ public class Task extends Node { } // validate the note id now + //如果本地数据的 ID 与远程数据的 ID 不匹配 if (c.getLong(SqlNote.ID_COLUMN) != noteInfo.getLong(NoteColumns.ID)) { Log.w(TAG, "note id doesn't match"); return SYNC_ACTION_UPDATE_LOCAL; } + //如果本地数据的修改标志为 0，即没有本地更新 if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) { // there is no local update + //如果本地数据的同步 ID 与任务的最后修改时间戳匹配 if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) { // no update both side return SYNC_ACTION_NONE; } else { - // apply remote to local + // apply remote to local 远程更新 return SYNC_ACTION_UPDATE_LOCAL; } } else { @@ -297,9 +361,10 @@ public class Task extends Node { return SYNC_ACTION_ERROR; } if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) { - // local modification only + // local modification only 仅本地更新 return SYNC_ACTION_UPDATE_REMOTE; } else { + //本地-远程更新 更新冲突 return SYNC_ACTION_UPDATE_CONFLICT; } } @@ -311,6 +376,7 @@ public class Task extends Node { return SYNC_ACTION_ERROR; } + //任务有元数据信息，或名称非空，或便签非空，则认为值得保存 public boolean isWorthSaving() { return mMetaInfo != null || (getName() != null && getName().trim().length() > 0) || (getNotes() != null && getNotes().trim().length() > 0); diff --git a/src/gtask/data/TaskList.java b/src/gtask/data/TaskList.java index 4ea21c5..6bfbc1e 100644 --- a/src/gtask/data/TaskList.java +++ b/src/gtask/data/TaskList.java @@ -29,7 +29,16 @@ import org.json.JSONObject; import java.util.ArrayList; - +/** + * + * @Package: net.micode.notes.gtask.data + * @ClassName: TaskList + * @Description: 表示一个任务列表（或任务组），继承自Node类。 + * 1. 管理任务列表中的子任务（Task对象） + * 2. 处理任务列表与Google Task API的JSON数据转换 + * 3. 处理任务列表与本地数据库的同步逻辑 + * 4. 管理任务列表在远程服务中的创建、更新和删除操作 + */ public class TaskList extends Node { private static final String TAG = TaskList.class.getSimpleName(); @@ -137,15 +146,19 @@ public class TaskList extends Node { try { JSONObject folder = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE); + //如果是文件夹类型，则设置名称为“文件夹：名称” if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) { String name = folder.getString(NoteColumns.SNIPPET); setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + name); - } else if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_SYSTEM) { - if (folder.getLong(NoteColumns.ID) == Notes.ID_ROOT_FOLDER) - setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_DEFAULT); - else if (folder.getLong(NoteColumns.ID) == Notes.ID_CALL_RECORD_FOLDER) + } + + //否则如果是系统文件夹类型，则根据ID设置名称 + else if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_SYSTEM) { + if (folder.getLong(NoteColumns.ID) == Notes.ID_ROOT_FOLDER)//如果是根文件夹 + setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_DEFAULT);//设置名称为“文件夹：默认文件夹” + else if (folder.getLong(NoteColumns.ID) == Notes.ID_CALL_RECORD_FOLDER)//如果是通话记录文件夹 setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX - + GTaskStringUtils.FOLDER_CALL_NOTE); + + GTaskStringUtils.FOLDER_CALL_NOTE);//设置名称为“文件夹：通话记录” else Log.e(TAG, "invalid system folder"); } else { @@ -222,36 +235,38 @@ public class TaskList extends Node { public boolean addChildTask(Task task) { boolean ret = false; + //如果任务不为空且不在子任务列表中，添加子任务 if (task != null && !mChildren.contains(task)) { ret = mChildren.add(task); if (ret) { - // need to set prior sibling and parent + // need to set prior sibling and parent 设置兄弟节点和父节点 task.setPriorSibling(mChildren.isEmpty() ? null : mChildren - .get(mChildren.size() - 1)); + .get(mChildren.size() - 1));//如果前一个任务为空，则设置前一个任务为null，否则设置为子任务列表中的最后一个任务 task.setParent(this); } } return ret; } + // 在指定位置添加子任务 public boolean addChildTask(Task task, int index) { if (index < 0 || index > mChildren.size()) { Log.e(TAG, "add child task: invalid index"); return false; } - int pos = mChildren.indexOf(task); + int pos = mChildren.indexOf(task);//获取任务在子任务列表中的位置 if (task != null && pos == -1) { mChildren.add(index, task); // update the task list + //更新任务列表 Task preTask = null; Task afterTask = null; if (index != 0) preTask = mChildren.get(index - 1); if (index != mChildren.size() - 1) afterTask = mChildren.get(index + 1); - task.setPriorSibling(preTask); if (afterTask != null) afterTask.setPriorSibling(task); @@ -273,6 +288,7 @@ public class TaskList extends Node { // update the task list if (index != mChildren.size()) { + //如果被移除任务不是最后一个任务，则将其后一个任务的前一个任务设置为被移除任务的前一个任务 mChildren.get(index).setPriorSibling( index == 0 ? null : mChildren.get(index - 1)); } @@ -281,6 +297,7 @@ public class TaskList extends Node { return ret; } + // 移动子任务到指定位置 public boolean moveChildTask(Task task, int index) { if (index < 0 || index >= mChildren.size()) { @@ -296,9 +313,10 @@ public class TaskList extends Node { if (pos == index) return true; - return (removeChildTask(task) && addChildTask(task, index)); + return (removeChildTask(task) && addChildTask(task, index));//先移除任务，再添加到指定位置 } + public Task findChildTaskByGid(String gid) { for (int i = 0; i < mChildren.size(); i++) { Task t = mChildren.get(i); @@ -309,10 +327,12 @@ public class TaskList extends Node { return null; } + // 根据任务获取子任务索引 public int getChildTaskIndex(Task task) { return mChildren.indexOf(task); } + // 根据索引获取子任务 public Task getChildTaskByIndex(int index) { if (index < 0 || index >= mChildren.size()) { Log.e(TAG, "getTaskByIndex: invalid index"); @@ -321,6 +341,7 @@ public class TaskList extends Node { return mChildren.get(index); } + // 根据 GID 获取子任务 public Task getChilTaskByGid(String gid) { for (Task task : mChildren) { if (task.getGid().equals(gid)) diff --git a/src/gtask/exception/ActionFailureException.java b/src/gtask/exception/ActionFailureException.java index 15504be..0635938 100644 --- a/src/gtask/exception/ActionFailureException.java +++ b/src/gtask/exception/ActionFailureException.java @@ -16,17 +16,21 @@ package net.micode.notes.gtask.exception; +// 自定义异常类：表示操作失败的异常 public class ActionFailureException extends RuntimeException { - private static final long serialVersionUID = 4425249765923293627L; + private static final long serialVersionUID = 4425249765923293627L;//序列化版本号 + // 构造方法 public ActionFailureException() { super(); } + // 构造方法，带有错误信息 public ActionFailureException(String paramString) { super(paramString); } + // 构造方法，带有错误信息和原因 public ActionFailureException(String paramString, Throwable paramThrowable) { super(paramString, paramThrowable); } diff --git a/src/gtask/exception/NetworkFailureException.java b/src/gtask/exception/NetworkFailureException.java index b08cfb1..5976949 100644 --- a/src/gtask/exception/NetworkFailureException.java +++ b/src/gtask/exception/NetworkFailureException.java @@ -16,17 +16,21 @@ package net.micode.notes.gtask.exception; +// 自定义异常类：表示网络故障的异常 public class NetworkFailureException extends Exception { - private static final long serialVersionUID = 2107610287180234136L; + private static final long serialVersionUID = 2107610287180234136L;//序列化版本号 + // 构造方法 public NetworkFailureException() { super(); } + // 构造方法，带有错误信息 public NetworkFailureException(String paramString) { super(paramString); } + // 构造方法，带有错误信息和原因 public NetworkFailureException(String paramString, Throwable paramThrowable) { super(paramString, paramThrowable); } diff --git a/src/gtask/remote/GTaskASyncTask.java b/src/gtask/remote/GTaskASyncTask.java index b3b61e7..2a9a416 100644 --- a/src/gtask/remote/GTaskASyncTask.java +++ b/src/gtask/remote/GTaskASyncTask.java @@ -1,4 +1,3 @@ - /* * Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net) * @@ -29,21 +28,29 @@ import net.micode.notes.ui.NotesListActivity; import net.micode.notes.ui.NotesPreferenceActivity; +/** + * + * @Package: net.micode.notes.gtask.remote + * @ClassName: GTaskASyncTask + * @Description: 1. 在后台线程执行Google Task同步操作 + * 2. 显示同步进度通知 + * 3. 处理同步完成后的结果展示 + * 4. 支持同步取消操作 + */ public class GTaskASyncTask extends AsyncTask { - private static int GTASK_SYNC_NOTIFICATION_ID = 5234235; + private static int GTASK_SYNC_NOTIFICATION_ID = 5234235; // 同步通知ID + //同步完成监听器接口 用于通知同步服务的完成事件 public interface OnCompleteListener { void onComplete(); } - private Context mContext; - - private NotificationManager mNotifiManager; + private Context mContext; // Android上下文 + private NotificationManager mNotifiManager; // 通知管理器 + private GTaskManager mTaskManager; // 同步管理器 + private OnCompleteListener mOnCompleteListener; // 完成监听器 - private GTaskManager mTaskManager; - - private OnCompleteListener mOnCompleteListener; public GTaskASyncTask(Context context, OnCompleteListener listener) { mContext = context; @@ -53,42 +60,67 @@ public class GTaskASyncTask extends AsyncTask { mTaskManager = GTaskManager.getInstance(); } + public void cancelSync() { mTaskManager.cancelSync(); } + //发布同步进度 public void publishProgess(String message) { publishProgress(new String[] { - message + message }); } + /** + * @method showNotification + * @description 显示同步通知 + * @param tickerId 通知标题字符串资源ID + * @param content 通知内容 + */ private void showNotification(int tickerId, String content) { - Notification notification = new Notification(R.drawable.notification, mContext - .getString(tickerId), System.currentTimeMillis()); - notification.defaults = Notification.DEFAULT_LIGHTS; - notification.flags = Notification.FLAG_AUTO_CANCEL; PendingIntent pendingIntent; if (tickerId != R.string.ticker_success) { + // 同步中或失败：跳转到设置页面 pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext, - NotesPreferenceActivity.class), 0); - + NotesPreferenceActivity.class), PendingIntent.FLAG_IMMUTABLE); } else { + // 同步成功：跳转到便签列表页面 pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext, - NotesListActivity.class), 0); + NotesListActivity.class), PendingIntent.FLAG_IMMUTABLE); } - notification.setLatestEventInfo(mContext, mContext.getString(R.string.app_name), content, - pendingIntent); + + // 构建通知 + Notification.Builder builder = new Notification.Builder(mContext) + .setAutoCancel(true) + .setContentTitle(mContext.getString(R.string.app_name)) + .setContentText(content) + .setContentIntent(pendingIntent) + .setWhen(System.currentTimeMillis()) + .setOngoing(true); + Notification notification=builder.getNotification(); mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification); } + + /** + * @method doInBackground + * @description 在后台执行同步 + * @param unused 未使用的参数（Void类型） + * @return 同步结果状态码 + */ @Override protected Integer doInBackground(Void... unused) { + // 发布登录进度 publishProgess(mContext.getString(R.string.sync_progress_login, NotesPreferenceActivity .getSyncAccountName(mContext))); + + // 执行同步 return mTaskManager.sync(mContext, this); } + + //更新同步进度 @Override protected void onProgressUpdate(String... progress) { showNotification(R.string.ticker_syncing, progress[0]); @@ -97,8 +129,11 @@ public class GTaskASyncTask extends AsyncTask { } } + + //同步完成后处理。根据同步结果显示相应的通知，并调用完成监听器 @Override protected void onPostExecute(Integer result) { + // 根据同步结果显示相应的通知 if (result == GTaskManager.STATE_SUCCESS) { showNotification(R.string.ticker_success, mContext.getString( R.string.success_sync_account, mTaskManager.getSyncAccount())); @@ -111,13 +146,14 @@ public class GTaskASyncTask extends AsyncTask { showNotification(R.string.ticker_cancel, mContext .getString(R.string.error_sync_cancelled)); } + + // 调用完成监听器（在新线程中执行，避免阻塞UI） if (mOnCompleteListener != null) { new Thread(new Runnable() { - public void run() { mOnCompleteListener.onComplete(); } }).start(); } } -} +} \ No newline at end of file diff --git a/src/gtask/remote/GTaskClient.java b/src/gtask/remote/GTaskClient.java index c67dfdf..66f4e9f 100644 --- a/src/gtask/remote/GTaskClient.java +++ b/src/gtask/remote/GTaskClient.java @@ -61,34 +61,38 @@ import java.util.zip.Inflater; import java.util.zip.InflaterInputStream; +/** + * + * @Package: net.micode.notes.gtask.remote + * @ClassName: GTaskClient + * @Description: 1. 封装与Google Task服务端的所有HTTP通信 + * 2. 处理用户认证、登录和会话管理 + * 3. 提供任务和任务列表的增删改查API + * 4. 管理请求的动作ID和批量更新 + */ public class GTaskClient { private static final String TAG = GTaskClient.class.getSimpleName(); - private static final String GTASK_URL = "https://mail.google.com/tasks/"; + private static final String GTASK_URL = "https://mail.google.com/tasks/"; // Google Task基础URL - private static final String GTASK_GET_URL = "https://mail.google.com/tasks/ig"; + private static final String GTASK_GET_URL = "https://mail.google.com/tasks/ig"; // GET请求URL - private static final String GTASK_POST_URL = "https://mail.google.com/tasks/r/ig"; + private static final String GTASK_POST_URL = "https://mail.google.com/tasks/r/ig"; // POST请求URL private static GTaskClient mInstance = null; - private DefaultHttpClient mHttpClient; - - private String mGetUrl; - - private String mPostUrl; - - private long mClientVersion; - - private boolean mLoggedin; - - private long mLastLoginTime; + private DefaultHttpClient mHttpClient; // HTTP客户端，用于执行网络请求 + private String mGetUrl; // 当前使用的GET请求URL + private String mPostUrl; // 当前使用的POST请求URL + private long mClientVersion; // 客户端版本号 + private boolean mLoggedin; // 登录状态标记 + private long mLastLoginTime; // 上次登录时间，用于会话超时控制 + private int mActionId; // 动作ID计数器，确保每个请求有唯一ID + private Account mAccount; // 当前同步的Google账户 + private JSONArray mUpdateArray; // 批量更新数组，用于缓存更新操作 - private int mActionId; - private Account mAccount; - - private JSONArray mUpdateArray; + // 构造函数：实现单例模式 private GTaskClient() { mHttpClient = null; @@ -102,6 +106,7 @@ public class GTaskClient { mUpdateArray = null; } + //获取单例实例 public static synchronized GTaskClient getInstance() { if (mInstance == null) { mInstance = new GTaskClient(); @@ -109,34 +114,42 @@ public class GTaskClient { return mInstance; } + /** + * 登录Google Task服务 + * @param activity 用于获取账户授权令牌 + * @return + */ public boolean login(Activity activity) { - // we suppose that the cookie would expire after 5 minutes - // then we need to re-login - final long interval = 1000 * 60 * 5; + // 检查会话超时：假设Cookie在5分钟后过期 + final long interval = 1000 * 60 * 5; // 5分钟 if (mLastLoginTime + interval < System.currentTimeMillis()) { mLoggedin = false; } - // need to re-login after account switch + // 检查账户切换：如果当前账户与设置中的账户不同，需要重新登录 if (mLoggedin && !TextUtils.equals(getSyncAccount().name, NotesPreferenceActivity - .getSyncAccountName(activity))) { + .getSyncAccountName(activity))) { mLoggedin = false; } + // 如果已经登录，直接返回成功 if (mLoggedin) { Log.d(TAG, "already logged in"); return true; } + // 记录本次登录时间 mLastLoginTime = System.currentTimeMillis(); + + // 获取Google账户授权令牌 String authToken = loginGoogleAccount(activity, false); if (authToken == null) { Log.e(TAG, "login google account failed"); return false; } - // login with custom domain if necessary + // 尝试使用自定义域名登录（针对非Gmail用户） if (!(mAccount.name.toLowerCase().endsWith("gmail.com") || mAccount.name.toLowerCase() .endsWith("googlemail.com"))) { StringBuilder url = new StringBuilder(GTASK_URL).append("a/"); @@ -151,7 +164,7 @@ public class GTaskClient { } } - // try to login with google official url + // 如果自定义域名登录失败，尝试使用官方Google域名登录 if (!mLoggedin) { mGetUrl = GTASK_GET_URL; mPostUrl = GTASK_POST_URL; @@ -164,16 +177,32 @@ public class GTaskClient { return true; } + + /** + * @method loginGoogleAccount + * @description 登录Google账户并获取授权令牌 + * + * 执行流程： + * 1. 获取设备上的所有Google账户 + * 2. 根据设置中的账户名称匹配账户 + * 3. 使用AccountManager获取授权令牌 + * 4. 可选择使令牌失效并重新获取（用于令牌过期情况） + * + * @param activity + * @param invalidateToken 是否使当前令牌失效并重新获取 + * @return String 授权令牌字符串，获取失败返回null + */ private String loginGoogleAccount(Activity activity, boolean invalidateToken) { String authToken; - AccountManager accountManager = AccountManager.get(activity); - Account[] accounts = accountManager.getAccountsByType("com.google"); + AccountManager accountManager = AccountManager.get(activity);// 获取账户管理器 + Account[] accounts = accountManager.getAccountsByType("com.google");// 获取所有Google账户 if (accounts.length == 0) { Log.e(TAG, "there is no available google account"); return null; } + // 根据设置中的账户名称查找对应账户 String accountName = NotesPreferenceActivity.getSyncAccountName(activity); Account account = null; for (Account a : accounts) { @@ -189,12 +218,14 @@ public class GTaskClient { return null; } - // get the token now + // 获取授权令牌 AccountManagerFuture accountManagerFuture = accountManager.getAuthToken(account, "goanna_mobile", null, activity, null, null); try { Bundle authTokenBundle = accountManagerFuture.getResult(); authToken = authTokenBundle.getString(AccountManager.KEY_AUTHTOKEN); + + // 如果令牌失效，重新获取 if (invalidateToken) { accountManager.invalidateAuthToken("com.google", authToken); loginGoogleAccount(activity, false); @@ -207,10 +238,21 @@ public class GTaskClient { return authToken; } + + /** + * @method tryToLoginGtask + * @description 描尝试登录Google Task服务 + * 执行流程： + * 1. 使用授权令牌登录Google Task + * 2. 如果失败，可能是令牌过期，使令牌失效后重新获取并重试 + * + * @param activity + * @param authToken 授权令牌 + * @return + */ private boolean tryToLoginGtask(Activity activity, String authToken) { if (!loginGtask(authToken)) { - // maybe the auth token is out of date, now let's invalidate the - // token and try again + // 令牌可能过期，使令牌失效并重新获取 authToken = loginGoogleAccount(activity, true); if (authToken == null) { Log.e(TAG, "login google account failed"); @@ -225,25 +267,42 @@ public class GTaskClient { return true; } + + /** + * @method loginGtask + * @description 使用授权令牌登录Google Task服务 + * 执行流程： + * 1. 配置HTTP客户端参数（连接超时、Socket超时） + * 2. 设置Cookie存储 + * 3. 构建登录URL并发送GET请求 + * 4. 验证返回的Cookie中是否包含认证Cookie（GTL） + * 5. 解析响应内容，获取客户端版本号 + * + * @param authToken 授权令牌 + * @return true登录成功，false登录失败 + */ private boolean loginGtask(String authToken) { - int timeoutConnection = 10000; - int timeoutSocket = 15000; + // 配置HTTP客户端参数 + int timeoutConnection = 10000; // 连接超时10秒 + int timeoutSocket = 15000; // Socket超时15秒 HttpParams httpParameters = new BasicHttpParams(); HttpConnectionParams.setConnectionTimeout(httpParameters, timeoutConnection); HttpConnectionParams.setSoTimeout(httpParameters, timeoutSocket); mHttpClient = new DefaultHttpClient(httpParameters); + + // 设置Cookie存储 BasicCookieStore localBasicCookieStore = new BasicCookieStore(); mHttpClient.setCookieStore(localBasicCookieStore); HttpProtocolParams.setUseExpectContinue(mHttpClient.getParams(), false); - // login gtask + // 登录Google Task try { String loginUrl = mGetUrl + "?auth=" + authToken; HttpGet httpGet = new HttpGet(loginUrl); HttpResponse response = null; response = mHttpClient.execute(httpGet); - // get the cookie now + // 检查认证Cookie是否获取成功 List cookies = mHttpClient.getCookieStore().getCookies(); boolean hasAuthCookie = false; for (Cookie cookie : cookies) { @@ -255,7 +314,7 @@ public class GTaskClient { Log.w(TAG, "it seems that there is no auth cookie"); } - // get the client version + // 解析响应内容，获取客户端版本号 String resString = getResponseContent(response.getEntity()); String jsBegin = "_setup("; String jsEnd = ")}"; @@ -272,7 +331,7 @@ public class GTaskClient { e.printStackTrace(); return false; } catch (Exception e) { - // simply catch all exceptions + // 捕获所有异常，确保稳定性 Log.e(TAG, "httpget gtask_url failed"); return false; } @@ -280,17 +339,26 @@ public class GTaskClient { return true; } + //获取下一个动作ID private int getActionId() { return mActionId++; } + //创建HTTP POST请求对象 private HttpPost createHttpPost() { HttpPost httpPost = new HttpPost(mPostUrl); httpPost.setHeader("Content-Type", "application/x-www-form-urlencoded;charset=utf-8"); - httpPost.setHeader("AT", "1"); + httpPost.setHeader("AT", "1"); // AT=1表示使用Cookie认证 return httpPost; } + /** + * @method getResponseContent + * @description 从HttpEntity获取响应内容 + * @param entity HTTP响应实体 + * @return 响应内容字符串 + * @throws IOException 读取响应内容时发生IO异常 + */ private String getResponseContent(HttpEntity entity) throws IOException { String contentEncoding = null; if (entity.getContentEncoding() != null) { @@ -299,6 +367,7 @@ public class GTaskClient { } InputStream input = entity.getContent(); + // 根据压缩编码选择对应的解压流 if (contentEncoding != null && contentEncoding.equalsIgnoreCase("gzip")) { input = new GZIPInputStream(entity.getContent()); } else if (contentEncoding != null && contentEncoding.equalsIgnoreCase("deflate")) { @@ -319,10 +388,27 @@ public class GTaskClient { sb = sb.append(buff); } } finally { - input.close(); + input.close(); // 确保流被关闭 } } + /** + * + /** + * @method postRequest + * @description 发送POST请求到Google Task服务 + * 执行流程： + * 1. 验证登录状态 + * 2. 创建HttpPost请求 + * 3. 将JSON对象编码为表单参数 + * 4. 执行请求并获取响应 + * 5. 解析响应内容为JSON对象 + * + * @param js 要发送的JSON对象 + * @return 服务器响应的JSON对象 + * @throws NetworkFailureException 网络请求失败 + * @throws ActionFailureException JSON解析或处理失败 + */ private JSONObject postRequest(JSONObject js) throws NetworkFailureException { if (!mLoggedin) { Log.e(TAG, "please login first"); @@ -331,12 +417,13 @@ public class GTaskClient { HttpPost httpPost = createHttpPost(); try { + // 将JSON对象编码为表单参数 LinkedList list = new LinkedList(); list.add(new BasicNameValuePair("r", js.toString())); UrlEncodedFormEntity entity = new UrlEncodedFormEntity(list, "UTF-8"); httpPost.setEntity(entity); - // execute the post + // 执行POST请求 HttpResponse response = mHttpClient.execute(httpPost); String jsString = getResponseContent(response.getEntity()); return new JSONObject(jsString); @@ -360,20 +447,32 @@ public class GTaskClient { } } + /** + * @method createTask + * @description 创建任务 + * 执行流程： + * 1. 提交已有的批量更新 + * 2. 构建创建任务的JSON请求 + * 3. 发送请求到服务器 + * 4. 从响应中提取新任务的ID并设置到任务对象 + * + * @param task 要创建的任务对象 + * @throws NetworkFailureException 网络请求失败 + */ public void createTask(Task task) throws NetworkFailureException { - commitUpdate(); + commitUpdate(); // 先提交已有的批量更新 try { JSONObject jsPost = new JSONObject(); JSONArray actionList = new JSONArray(); - // action_list + // 构建动作列表：包含创建任务的动作 actionList.put(task.getCreateAction(getActionId())); jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList); - // client_version + // 添加客户端版本号 jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion); - // post + // 发送请求并处理响应 JSONObject jsResponse = postRequest(jsPost); JSONObject jsResult = (JSONObject) jsResponse.getJSONArray( GTaskStringUtils.GTASK_JSON_RESULTS).get(0); @@ -386,20 +485,33 @@ public class GTaskClient { } } + + /** + * @method createTaskList + * @description 创建任务列表 + * 执行流程： + * 1. 提交已有的批量更新 + * 2. 构建创建任务列表的JSON请求 + * 3. 发送请求到服务器 + * 4. 从响应中提取新任务列表的ID并设置到任务列表对象 + * + * @param tasklist 要创建的任务列表对象 + * @throws NetworkFailureException 网络请求失败 + */ public void createTaskList(TaskList tasklist) throws NetworkFailureException { - commitUpdate(); + commitUpdate(); // 先提交已有的批量更新 try { JSONObject jsPost = new JSONObject(); JSONArray actionList = new JSONArray(); - // action_list + // 构建动作列表：包含创建任务列表的动作 actionList.put(tasklist.getCreateAction(getActionId())); jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList); - // client version + // 添加客户端版本号 jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion); - // post + // 发送请求并处理响应 JSONObject jsResponse = postRequest(jsPost); JSONObject jsResult = (JSONObject) jsResponse.getJSONArray( GTaskStringUtils.GTASK_JSON_RESULTS).get(0); @@ -412,19 +524,22 @@ public class GTaskClient { } } + + //提交批量更新 public void commitUpdate() throws NetworkFailureException { if (mUpdateArray != null) { try { JSONObject jsPost = new JSONObject(); - // action_list + // 添加缓存的更新动作列表 jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, mUpdateArray); - // client_version + // 添加客户端版本号 jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion); + // 发送请求 postRequest(jsPost); - mUpdateArray = null; + mUpdateArray = null; // 清空更新数组 } catch (JSONException e) { Log.e(TAG, e.toString()); e.printStackTrace(); @@ -433,48 +548,61 @@ public class GTaskClient { } } + + //将节点的更新操作添加到批量更新数组中 public void addUpdateNode(Node node) throws NetworkFailureException { if (node != null) { - // too many update items may result in an error - // set max to 10 items + // 优化：更新项太多可能导致错误，设置最大为10项 if (mUpdateArray != null && mUpdateArray.length() > 10) { commitUpdate(); } + // 初始化更新数组并添加更新动作 if (mUpdateArray == null) mUpdateArray = new JSONArray(); mUpdateArray.put(node.getUpdateAction(getActionId())); } } + /** + * @method moveTask + * @description 将任务从一个任务列表移动到另一个任务列表 + * @param task 要移动的任务 + * @param preParent 移动前的父任务列表 + * @param curParent 移动后的父任务列表 + * @throws NetworkFailureException 网络请求失败 + */ public void moveTask(Task task, TaskList preParent, TaskList curParent) throws NetworkFailureException { - commitUpdate(); + commitUpdate(); // 先提交已有的批量更新 try { JSONObject jsPost = new JSONObject(); JSONArray actionList = new JSONArray(); JSONObject action = new JSONObject(); - // action_list + // 构建移动动作 action.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE, GTaskStringUtils.GTASK_JSON_ACTION_TYPE_MOVE); action.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, getActionId()); action.put(GTaskStringUtils.GTASK_JSON_ID, task.getGid()); + + // 在同一任务列表内移动且不是第一个时，设置前一个兄弟节点ID if (preParent == curParent && task.getPriorSibling() != null) { - // put prioring_sibing_id only if moving within the tasklist and - // it is not the first one action.put(GTaskStringUtils.GTASK_JSON_PRIOR_SIBLING_ID, task.getPriorSibling()); } + action.put(GTaskStringUtils.GTASK_JSON_SOURCE_LIST, preParent.getGid()); action.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT, curParent.getGid()); + + // 在不同任务列表之间移动时，设置目标列表ID if (preParent != curParent) { - // put the dest_list only if moving between tasklists action.put(GTaskStringUtils.GTASK_JSON_DEST_LIST, curParent.getGid()); } + actionList.put(action); jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList); - // client_version + // 添加客户端版本号 jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion); postRequest(jsPost); @@ -486,22 +614,24 @@ public class GTaskClient { } } + + //Google Task中删除节点 public void deleteNode(Node node) throws NetworkFailureException { - commitUpdate(); + commitUpdate(); // 先提交已有的批量更新 try { JSONObject jsPost = new JSONObject(); JSONArray actionList = new JSONArray(); - // action_list + // 构建删除动作 node.setDeleted(true); actionList.put(node.getUpdateAction(getActionId())); jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList); - // client_version + // 添加客户端版本号 jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion); postRequest(jsPost); - mUpdateArray = null; + mUpdateArray = null; // 清空更新数组 } catch (JSONException e) { Log.e(TAG, e.toString()); e.printStackTrace(); @@ -509,6 +639,8 @@ public class GTaskClient { } } + + //获取当前账户下的所有任务列表 public JSONArray getTaskLists() throws NetworkFailureException { if (!mLoggedin) { Log.e(TAG, "please login first"); @@ -520,7 +652,7 @@ public class GTaskClient { HttpResponse response = null; response = mHttpClient.execute(httpGet); - // get the task list + // 解析响应内容，提取任务列表信息 String resString = getResponseContent(response.getEntity()); String jsBegin = "_setup("; String jsEnd = ")}"; @@ -547,25 +679,27 @@ public class GTaskClient { } } + //获取特定任务列表下的所有任务 public JSONArray getTaskList(String listGid) throws NetworkFailureException { - commitUpdate(); + commitUpdate(); // 先提交已有的批量更新 try { JSONObject jsPost = new JSONObject(); JSONArray actionList = new JSONArray(); JSONObject action = new JSONObject(); - // action_list + // 构建获取所有任务的动作 action.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE, GTaskStringUtils.GTASK_JSON_ACTION_TYPE_GETALL); action.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, getActionId()); action.put(GTaskStringUtils.GTASK_JSON_LIST_ID, listGid); - action.put(GTaskStringUtils.GTASK_JSON_GET_DELETED, false); + action.put(GTaskStringUtils.GTASK_JSON_GET_DELETED, false); // 不获取已删除的任务 actionList.put(action); jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList); - // client_version + // 添加客户端版本号 jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion); + // 发送请求并获取响应 JSONObject jsResponse = postRequest(jsPost); return jsResponse.getJSONArray(GTaskStringUtils.GTASK_JSON_TASKS); } catch (JSONException e) { @@ -575,11 +709,13 @@ public class GTaskClient { } } + //获取当前同步账户 public Account getSyncAccount() { return mAccount; } + //重置更新数组 public void resetUpdateArray() { mUpdateArray = null; } -} +} \ No newline at end of file diff --git a/src/gtask/remote/GTaskManager.java b/src/gtask/remote/GTaskManager.java index d2b4082..bc5e1ae 100644 --- a/src/gtask/remote/GTaskManager.java +++ b/src/gtask/remote/GTaskManager.java @@ -48,45 +48,47 @@ import java.util.Iterator; import java.util.Map; +/** + * + * @Package: net.micode.notes.gtask.remote + * @ClassName: GTaskManager + * @Description: + * 1. 协调本地SQLite数据库与Google Task之间的双向同步 + * 2. 管理同步状态和冲突解决策略 + * 3. 维护本地ID与Google Task ID之间的映射关系 + * 4. 处理文件夹、便签和元数据的完整同步逻辑 + */ public class GTaskManager { - private static final String TAG = GTaskManager.class.getSimpleName(); - - public static final int STATE_SUCCESS = 0; - - public static final int STATE_NETWORK_ERROR = 1; - - public static final int STATE_INTERNAL_ERROR = 2; + private static final String TAG = GTaskManager.class.getSimpleName(); // 日志标签 - public static final int STATE_SYNC_IN_PROGRESS = 3; - - public static final int STATE_SYNC_CANCELLED = 4; + // 同步状态常量 + public static final int STATE_SUCCESS = 0; // 同步成功 + public static final int STATE_NETWORK_ERROR = 1; // 网络错误 + public static final int STATE_INTERNAL_ERROR = 2; // 内部错误 + public static final int STATE_SYNC_IN_PROGRESS = 3; // 同步进行中 + public static final int STATE_SYNC_CANCELLED = 4; // 同步已取消 private static GTaskManager mInstance = null; - private Activity mActivity; - - private Context mContext; - - private ContentResolver mContentResolver; - - private boolean mSyncing; + private Activity mActivity; // Activity上下文，用于获取授权令牌 + private Context mContext; // 应用上下文 + private ContentResolver mContentResolver; // ContentResolver，用于数据库操作 + private boolean mSyncing; // 同步状态标记 + private boolean mCancelled; // 取消同步标记 - private boolean mCancelled; + // Google Task相关数据结构 + private HashMap mGTaskListHashMap; // Google Task列表映射（GID -> TaskList） + private HashMap mGTaskHashMap; // Google Task节点映射（GID -> Node） + private HashMap mMetaHashMap; // 元数据映射（相关GID -> MetaData） + private TaskList mMetaList; // 元数据任务列表 - private HashMap mGTaskListHashMap; + // 本地数据相关 + private HashSet mLocalDeleteIdMap; // 本地待删除的便签ID集合 + private HashMap mGidToNid; // GID到本地ID的映射 + private HashMap mNidToGid; // 本地ID到GID的映射 - private HashMap mGTaskHashMap; - - private HashMap mMetaHashMap; - - private TaskList mMetaList; - - private HashSet mLocalDeleteIdMap; - - private HashMap mGidToNid; - - private HashMap mNidToGid; + //初始化所有数据结构和状态变量 private GTaskManager() { mSyncing = false; mCancelled = false; @@ -99,6 +101,7 @@ public class GTaskManager { mNidToGid = new HashMap(); } + public static synchronized GTaskManager getInstance() { if (mInstance == null) { mInstance = new GTaskManager(); @@ -106,20 +109,41 @@ public class GTaskManager { return mInstance; } + + //设置Activity上下文 public synchronized void setActivityContext(Activity activity) { - // used for getting authtoken mActivity = activity; } + /** + * @method sync + * @description 执行同步操作 + * 1. 检查是否已经在同步中 + * 2. 初始化同步环境和数据结构 + * 3. 登录Google Task + * 4. 初始化任务列表 + * 5. 同步内容（包括文件夹和便签） + * 6. 清理资源 + * 7. 返回同步结果 + * + * @param context Android上下文 + * @param asyncTask 异步任务，用于更新进度 + * @return 同步结果状态码 + */ public int sync(Context context, GTaskASyncTask asyncTask) { + // 检查是否已经在同步中 if (mSyncing) { Log.d(TAG, "Sync is in progress"); return STATE_SYNC_IN_PROGRESS; } + + // 初始化同步环境 mContext = context; mContentResolver = mContext.getContentResolver(); mSyncing = true; mCancelled = false; + + // 清空数据结构，准备新的同步 mGTaskListHashMap.clear(); mGTaskHashMap.clear(); mMetaHashMap.clear(); @@ -129,20 +153,20 @@ public class GTaskManager { try { GTaskClient client = GTaskClient.getInstance(); - client.resetUpdateArray(); + client.resetUpdateArray(); // 重置客户端更新数组 - // login google task + // 登录Google Task if (!mCancelled) { if (!client.login(mActivity)) { throw new NetworkFailureException("login google task failed"); } } - // get the task list from google + // 初始化任务列表 asyncTask.publishProgess(mContext.getString(R.string.sync_progress_init_list)); initGTaskList(); - // do content sync work + // 执行内容同步 asyncTask.publishProgess(mContext.getString(R.string.sync_progress_syncing)); syncContent(); } catch (NetworkFailureException e) { @@ -156,6 +180,7 @@ public class GTaskManager { e.printStackTrace(); return STATE_INTERNAL_ERROR; } finally { + // 无论成功失败，都清理资源 mGTaskListHashMap.clear(); mGTaskHashMap.clear(); mMetaHashMap.clear(); @@ -168,26 +193,36 @@ public class GTaskManager { return mCancelled ? STATE_SYNC_CANCELLED : STATE_SUCCESS; } + /** + * @method initGTaskList + * @description 初始化Google Task列表 + * 执行流程： + * 1. 从Google Task获取所有任务列表 + * 2. 查找并初始化元数据列表 + * 3. 加载元数据列表中的所有元数据 + * 4. 如果元数据列表不存在则创建 + * 5. 初始化普通任务列表 + */ private void initGTaskList() throws NetworkFailureException { - if (mCancelled) - return; + if (mCancelled) return; + GTaskClient client = GTaskClient.getInstance(); try { JSONArray jsTaskLists = client.getTaskLists(); - // init meta list first + // 首先初始化元数据列表 mMetaList = null; for (int i = 0; i < jsTaskLists.length(); i++) { JSONObject object = jsTaskLists.getJSONObject(i); String gid = object.getString(GTaskStringUtils.GTASK_JSON_ID); String name = object.getString(GTaskStringUtils.GTASK_JSON_NAME); - if (name - .equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_META)) { + // 查找元数据列表（名称以特定前缀开头） + if (name.equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_META)) { mMetaList = new TaskList(); mMetaList.setContentByRemoteJSON(object); - // load meta data + // 加载元数据列表中的所有元数据任务 JSONArray jsMetas = client.getTaskList(gid); for (int j = 0; j < jsMetas.length(); j++) { object = (JSONObject) jsMetas.getJSONObject(j); @@ -203,29 +238,28 @@ public class GTaskManager { } } - // create meta list if not existed + // 如果元数据列表不存在，创建新的 if (mMetaList == null) { mMetaList = new TaskList(); - mMetaList.setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX - + GTaskStringUtils.FOLDER_META); + mMetaList.setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_META); GTaskClient.getInstance().createTaskList(mMetaList); } - // init task list + // 初始化普通任务列表 for (int i = 0; i < jsTaskLists.length(); i++) { JSONObject object = jsTaskLists.getJSONObject(i); String gid = object.getString(GTaskStringUtils.GTASK_JSON_ID); String name = object.getString(GTaskStringUtils.GTASK_JSON_NAME); + // 只处理以MIUI前缀开头的任务列表（排除元数据列表） if (name.startsWith(GTaskStringUtils.MIUI_FOLDER_PREFFIX) - && !name.equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX - + GTaskStringUtils.FOLDER_META)) { + && !name.equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_META)) { TaskList tasklist = new TaskList(); tasklist.setContentByRemoteJSON(object); mGTaskListHashMap.put(gid, tasklist); mGTaskHashMap.put(gid, tasklist); - // load tasks + // 加载任务列表中的所有任务 JSONArray jsTasks = client.getTaskList(gid); for (int j = 0; j < jsTasks.length(); j++) { object = (JSONObject) jsTasks.getJSONObject(j); @@ -247,6 +281,17 @@ public class GTaskManager { } } + /** + * @method syncContent + * @description 同步内容（便签和文件夹的具体数据） + * 执行流程： + * 1. 同步本地已删除的便签 + * 2. 同步文件夹（先同步文件夹，再同步便签） + * 3. 同步现有的便签 + * 4. 处理远程新增的项目 + * 5. 批量删除本地已删除的便签 + * 6. 刷新本地同步ID + */ private void syncContent() throws NetworkFailureException { int syncType; Cursor c = null; @@ -255,11 +300,9 @@ public class GTaskManager { mLocalDeleteIdMap.clear(); - if (mCancelled) { - return; - } + if (mCancelled) return; - // for local deleted note + // 第一步：处理本地已删除的便签（在回收站中的便签） try { c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE, "(type<>? AND parent_id=?)", new String[] { @@ -286,10 +329,10 @@ public class GTaskManager { } } - // sync folder first + // 第二步：同步文件夹（必须先同步文件夹，因为便签需要知道父文件夹的映射关系） syncFolder(); - // for note existing in database + // 第三步：同步现有的便签 try { c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE, "(type=? AND parent_id<>?)", new String[] { @@ -306,10 +349,10 @@ public class GTaskManager { syncType = node.getSyncAction(c); } else { if (c.getString(SqlNote.GTASK_ID_COLUMN).trim().length() == 0) { - // local add + // 本地新增：本地有GID，但远程没有对应节点 syncType = Node.SYNC_ACTION_ADD_REMOTE; } else { - // remote delete + // 远程删除：本地有GID，但远程节点不存在 syncType = Node.SYNC_ACTION_DEL_LOCAL; } } @@ -318,7 +361,6 @@ public class GTaskManager { } else { Log.w(TAG, "failed to query existing note in database"); } - } finally { if (c != null) { c.close(); @@ -326,7 +368,7 @@ public class GTaskManager { } } - // go through remaining items + // 第四步：处理远程新增的项目（遍历剩余的Google Task节点） Iterator> iter = mGTaskHashMap.entrySet().iterator(); while (iter.hasNext()) { Map.Entry entry = iter.next(); @@ -334,34 +376,38 @@ public class GTaskManager { doContentSync(Node.SYNC_ACTION_ADD_LOCAL, node, null); } - // mCancelled can be set by another thread, so we neet to check one by - // one - // clear local delete table + // 第五步：批量删除本地已删除的便签 if (!mCancelled) { if (!DataUtils.batchDeleteNotes(mContentResolver, mLocalDeleteIdMap)) { throw new ActionFailureException("failed to batch-delete local deleted notes"); } } - // refresh local sync id + // 第六步：刷新本地同步ID if (!mCancelled) { GTaskClient.getInstance().commitUpdate(); refreshLocalSyncId(); } - } + /** + * @method syncFolder + * @description 同步文件夹 + * 执行流程： + * 1. 同步根文件夹 + * 2. 同步通话记录文件夹 + * 3. 同步现有的普通文件夹 + * 4. 处理远程新增的文件夹 + */ private void syncFolder() throws NetworkFailureException { Cursor c = null; String gid; Node node; int syncType; - if (mCancelled) { - return; - } + if (mCancelled) return; - // for root folder + // 同步根文件夹 try { c = mContentResolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, Notes.ID_ROOT_FOLDER), SqlNote.PROJECTION_NOTE, null, null, null); @@ -373,7 +419,7 @@ public class GTaskManager { mGTaskHashMap.remove(gid); mGidToNid.put(gid, (long) Notes.ID_ROOT_FOLDER); mNidToGid.put((long) Notes.ID_ROOT_FOLDER, gid); - // for system folder, only update remote name if necessary + // 系统文件夹：只有在名称不同时才更新远程 if (!node.getName().equals( GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_DEFAULT)) doContentSync(Node.SYNC_ACTION_UPDATE_REMOTE, node, c); @@ -390,11 +436,11 @@ public class GTaskManager { } } - // for call-note folder + // 同步通话记录文件夹 try { c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE, "(_id=?)", new String[] { - String.valueOf(Notes.ID_CALL_RECORD_FOLDER) + String.valueOf(Notes.ID_CALL_RECORD_FOLDER) }, null); if (c != null) { if (c.moveToNext()) { @@ -404,11 +450,9 @@ public class GTaskManager { mGTaskHashMap.remove(gid); mGidToNid.put(gid, (long) Notes.ID_CALL_RECORD_FOLDER); mNidToGid.put((long) Notes.ID_CALL_RECORD_FOLDER, gid); - // for system folder, only update remote name if - // necessary + // 系统文件夹：只有在名称不同时才更新远程 if (!node.getName().equals( - GTaskStringUtils.MIUI_FOLDER_PREFFIX - + GTaskStringUtils.FOLDER_CALL_NOTE)) + GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_CALL_NOTE)) doContentSync(Node.SYNC_ACTION_UPDATE_REMOTE, node, c); } else { doContentSync(Node.SYNC_ACTION_ADD_REMOTE, node, c); @@ -424,7 +468,7 @@ public class GTaskManager { } } - // for local existing folders + // 同步现有的普通文件夹 try { c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE, "(type=? AND parent_id<>?)", new String[] { @@ -441,10 +485,10 @@ public class GTaskManager { syncType = node.getSyncAction(c); } else { if (c.getString(SqlNote.GTASK_ID_COLUMN).trim().length() == 0) { - // local add + // 本地新增 syncType = Node.SYNC_ACTION_ADD_REMOTE; } else { - // remote delete + // 远程删除 syncType = Node.SYNC_ACTION_DEL_LOCAL; } } @@ -460,7 +504,7 @@ public class GTaskManager { } } - // for remote add folders + // 处理远程新增的文件夹 Iterator> iter = mGTaskListHashMap.entrySet().iterator(); while (iter.hasNext()) { Map.Entry entry = iter.next(); @@ -476,10 +520,15 @@ public class GTaskManager { GTaskClient.getInstance().commitUpdate(); } + /** + * @method doContentSync + * @description 根据同步类型执行相应的同步动作 + * @param syncType 同步类型 + * @param node Google Task节点 + * @param c 数据库游标 + */ private void doContentSync(int syncType, Node node, Cursor c) throws NetworkFailureException { - if (mCancelled) { - return; - } + if (mCancelled) return; MetaData meta; switch (syncType) { @@ -510,25 +559,36 @@ public class GTaskManager { updateRemoteNode(node, c); break; case Node.SYNC_ACTION_UPDATE_CONFLICT: - // merging both modifications maybe a good idea - // right now just use local update simply + // 冲突处理：简单策略，使用本地更新远程 updateRemoteNode(node, c); break; case Node.SYNC_ACTION_NONE: break; case Node.SYNC_ACTION_ERROR: default: - throw new ActionFailureException("unkown sync action type"); + throw new ActionFailureException("unknown sync action type"); } } + /** + * @method addLocalNode + * @description 在本地添加节点 + * 执行流程： + * 1. 根据节点类型创建SqlNote对象 + * 2. 处理可能存在的ID冲突 + * 3. 设置父文件夹ID + * 4. 提交到本地数据库 + * 5. 更新ID映射关系 + * 6. 更新远程元数据 + * + * @param node 要在本地添加的节点 + */ private void addLocalNode(Node node) throws NetworkFailureException { - if (mCancelled) { - return; - } + if (mCancelled) return; SqlNote sqlNote; if (node instanceof TaskList) { + // 处理任务列表（文件夹） if (node.getName().equals( GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_DEFAULT)) { sqlNote = new SqlNote(mContext, Notes.ID_ROOT_FOLDER); @@ -541,20 +601,23 @@ public class GTaskManager { sqlNote.setParentId(Notes.ID_ROOT_FOLDER); } } else { + // 处理任务（便签） sqlNote = new SqlNote(mContext); JSONObject js = node.getLocalJSONFromContent(); try { + // 检查便签ID是否可用 if (js.has(GTaskStringUtils.META_HEAD_NOTE)) { JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE); if (note.has(NoteColumns.ID)) { long id = note.getLong(NoteColumns.ID); if (DataUtils.existInNoteDatabase(mContentResolver, id)) { - // the id is not available, have to create a new one + // ID已被占用，移除ID让数据库自动生成新ID note.remove(NoteColumns.ID); } } } + // 检查数据ID是否可用 if (js.has(GTaskStringUtils.META_HEAD_DATA)) { JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA); for (int i = 0; i < dataArray.length(); i++) { @@ -562,13 +625,11 @@ public class GTaskManager { if (data.has(DataColumns.ID)) { long dataId = data.getLong(DataColumns.ID); if (DataUtils.existInDataDatabase(mContentResolver, dataId)) { - // the data id is not available, have to create - // a new one + // 数据ID已被占用，移除ID data.remove(DataColumns.ID); } } } - } } catch (JSONException e) { Log.w(TAG, e.toString()); @@ -576,6 +637,7 @@ public class GTaskManager { } sqlNote.setContent(js); + // 设置父文件夹ID Long parentId = mGidToNid.get(((Task) node).getParent().getGid()); if (parentId == null) { Log.e(TAG, "cannot find task's parent id locally"); @@ -584,28 +646,40 @@ public class GTaskManager { sqlNote.setParentId(parentId.longValue()); } - // create the local node + // 创建本地节点 sqlNote.setGtaskId(node.getGid()); sqlNote.commit(false); - // update gid-nid mapping + // 更新ID映射 mGidToNid.put(node.getGid(), sqlNote.getId()); mNidToGid.put(sqlNote.getId(), node.getGid()); - // update meta + // 更新元数据 updateRemoteMeta(node.getGid(), sqlNote); } + /** + * @method updateLocalNode + * @description 更新本地节点（远程更新） + * 执行流程： + * 1. 从游标创建SqlNote对象 + * 2. 设置新的内容 + * 3. 更新父文件夹ID + * 4. 提交更新（带版本验证） + * 5. 更新远程元数据 + * + * @param node 更新后的节点 + * @param c 数据库游标，指向要更新的本地记录 + */ private void updateLocalNode(Node node, Cursor c) throws NetworkFailureException { - if (mCancelled) { - return; - } + if (mCancelled) return; SqlNote sqlNote; - // update the note locally + // 更新本地便签 sqlNote = new SqlNote(mContext, c); sqlNote.setContent(node.getLocalJSONFromContent()); + // 更新父文件夹ID Long parentId = (node instanceof Task) ? mGidToNid.get(((Task) node).getParent().getGid()) : new Long(Notes.ID_ROOT_FOLDER); if (parentId == null) { @@ -613,25 +687,42 @@ public class GTaskManager { throw new ActionFailureException("cannot update local node"); } sqlNote.setParentId(parentId.longValue()); + + // 提交更新（带版本验证） sqlNote.commit(true); - // update meta info + // 更新元数据 updateRemoteMeta(node.getGid(), sqlNote); } + /** + * @method addRemoteNode + * @description 在远程添加节点（本地新增） + * + * 执行流程： + * 1. 根据本地数据创建Google Task节点 + * 2. 添加到相应的父任务列表 + * 3. 在远程创建节点 + * 4. 更新本地节点的GID + * 5. 更新ID映射关系 + * 6. 重置本地修改标记 + * + * @param node 要在远程添加的节点 + * @param c 数据库游标，指向本地记录 + */ private void addRemoteNode(Node node, Cursor c) throws NetworkFailureException { - if (mCancelled) { - return; - } + if (mCancelled) return; SqlNote sqlNote = new SqlNote(mContext, c); Node n; - // update remotely + // 在远程创建节点 if (sqlNote.isNoteType()) { + // 创建任务（便签） Task task = new Task(); task.setContentByLocalJSON(sqlNote.getContent()); + // 查找父任务列表 String parentGid = mNidToGid.get(sqlNote.getParentId()); if (parentGid == null) { Log.e(TAG, "cannot find task's parent tasklist"); @@ -642,12 +733,13 @@ public class GTaskManager { GTaskClient.getInstance().createTask(task); n = (Node) task; - // add meta + // 添加元数据 updateRemoteMeta(task.getGid(), sqlNote); } else { + // 创建任务列表（文件夹） TaskList tasklist = null; - // we need to skip folder if it has already existed + // 检查是否已存在同名文件夹 String folderName = GTaskStringUtils.MIUI_FOLDER_PREFFIX; if (sqlNote.getId() == Notes.ID_ROOT_FOLDER) folderName += GTaskStringUtils.FOLDER_DEFAULT; @@ -656,6 +748,7 @@ public class GTaskManager { else folderName += sqlNote.getSnippet(); + // 查找已存在的同名文件夹 Iterator> iter = mGTaskListHashMap.entrySet().iterator(); while (iter.hasNext()) { Map.Entry entry = iter.next(); @@ -671,7 +764,7 @@ public class GTaskManager { } } - // no match we can add now + // 如果没有匹配的文件夹，创建新的 if (tasklist == null) { tasklist = new TaskList(); tasklist.setContentByLocalJSON(sqlNote.getContent()); @@ -681,32 +774,43 @@ public class GTaskManager { n = (Node) tasklist; } - // update local note + // 更新本地节点 sqlNote.setGtaskId(n.getGid()); sqlNote.commit(false); - sqlNote.resetLocalModified(); + sqlNote.resetLocalModified(); // 重置本地修改标记 sqlNote.commit(true); - // gid-id mapping + // 更新ID映射 mGidToNid.put(n.getGid(), sqlNote.getId()); mNidToGid.put(sqlNote.getId(), n.getGid()); } + /** + * @method updateRemoteNode + * @description 更新远程节点（本地更新） + * + * 执行流程： + * 1. 更新远程节点内容 + * 2. 更新远程元数据 + * 3. 如果需要，移动任务到其他任务列表 + * 4. 重置本地修改标记 + * + * @param node 要更新的节点 + * @param c 数据库游标，指向本地记录 + */ private void updateRemoteNode(Node node, Cursor c) throws NetworkFailureException { - if (mCancelled) { - return; - } + if (mCancelled) return; SqlNote sqlNote = new SqlNote(mContext, c); - // update remotely + // 更新远程节点 node.setContentByLocalJSON(sqlNote.getContent()); GTaskClient.getInstance().addUpdateNode(node); - // update meta + // 更新元数据 updateRemoteMeta(node.getGid(), sqlNote); - // move task if necessary + // 如果便签被移动到其他文件夹，处理移动操作 if (sqlNote.isNoteType()) { Task task = (Task) node; TaskList preParentList = task.getParent(); @@ -725,18 +829,30 @@ public class GTaskManager { } } - // clear local modified flag + // 重置本地修改标记 sqlNote.resetLocalModified(); sqlNote.commit(true); } + /** + * @method updateRemoteMeta + * @description 更新远程元数据 + * + * 功能：为任务创建或更新关联的元数据 + * 元数据包含任务ID和便签内容的关联信息 + * + * @param gid 任务的Google Task ID + * @param sqlNote 本地便签对象 + */ private void updateRemoteMeta(String gid, SqlNote sqlNote) throws NetworkFailureException { if (sqlNote != null && sqlNote.isNoteType()) { MetaData metaData = mMetaHashMap.get(gid); if (metaData != null) { + // 更新现有元数据 metaData.setMeta(gid, sqlNote.getContent()); GTaskClient.getInstance().addUpdateNode(metaData); } else { + // 创建新的元数据 metaData = new MetaData(); metaData.setMeta(gid, sqlNote.getContent()); mMetaList.addChildTask(metaData); @@ -746,17 +862,18 @@ public class GTaskManager { } } + + //同步完成后，更新本地便签的同步ID private void refreshLocalSyncId() throws NetworkFailureException { - if (mCancelled) { - return; - } + if (mCancelled) return; - // get the latest gtask list + // 重新获取最新的任务列表 mGTaskHashMap.clear(); mGTaskListHashMap.clear(); mMetaHashMap.clear(); initGTaskList(); + // 更新本地同步ID Cursor c = null; try { c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE, @@ -790,11 +907,13 @@ public class GTaskManager { } } + //获取同步账户名称 public String getSyncAccount() { return GTaskClient.getInstance().getSyncAccount().name; } + public void cancelSync() { mCancelled = true; } -} +} \ No newline at end of file diff --git a/src/gtask/remote/GTaskSyncService.java b/src/gtask/remote/GTaskSyncService.java index cca36f7..ac08aa1 100644 --- a/src/gtask/remote/GTaskSyncService.java +++ b/src/gtask/remote/GTaskSyncService.java @@ -23,50 +23,78 @@ import android.content.Intent; import android.os.Bundle; import android.os.IBinder; -public class GTaskSyncService extends Service { - public final static String ACTION_STRING_NAME = "sync_action_type"; - - public final static int ACTION_START_SYNC = 0; - - public final static int ACTION_CANCEL_SYNC = 1; - public final static int ACTION_INVALID = 2; - - public final static String GTASK_SERVICE_BROADCAST_NAME = "net.micode.notes.gtask.remote.gtask_sync_service"; +/** + * + * @Package: net.micode.notes.gtask.remote + * @ClassName: GTaskSyncService + * @Description: + * 1. 管理Google Task同步的生命周期 + * 2. 接收同步开始/取消的Intent命令 + * 3. 在后台执行同步操作，避免阻塞UI线程 + * 4. 通过广播发送同步状态和进度信息 + */ +public class GTaskSyncService extends Service { + public final static String ACTION_STRING_NAME = "sync_action_type"; // Intent动作类型键 - public final static String GTASK_SERVICE_BROADCAST_IS_SYNCING = "isSyncing"; + public final static int ACTION_START_SYNC = 0; // 开始同步动作 + public final static int ACTION_CANCEL_SYNC = 1; // 取消同步动作 + public final static int ACTION_INVALID = 2; // 无效动作 - public final static String GTASK_SERVICE_BROADCAST_PROGRESS_MSG = "progressMsg"; + public final static String GTASK_SERVICE_BROADCAST_NAME = "net.micode.notes.gtask.remote.gtask_sync_service"; // 广播名称 - private static GTaskASyncTask mSyncTask = null; + public final static String GTASK_SERVICE_BROADCAST_IS_SYNCING = "isSyncing"; // 是否正在同步的键 + public final static String GTASK_SERVICE_BROADCAST_PROGRESS_MSG = "progressMsg"; // 进度消息的键 - private static String mSyncProgress = ""; + private static GTaskASyncTask mSyncTask = null; // 同步任务实例 + private static String mSyncProgress = ""; // 同步进度信息 + /** + * 开始同步 + * + * 执行流程： + * 1. 检查是否已经有同步任务在运行 + * 2. 创建新的GTaskASyncTask异步任务 + * 3. 设置任务完成监听器，在完成时清理资源 + * 4. 执行异步任务，发送进度广播 + */ private void startSync() { + // 确保只有一个同步任务在运行 if (mSyncTask == null) { mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() { public void onComplete() { - mSyncTask = null; - sendBroadcast(""); - stopSelf(); + mSyncTask = null; // 清理任务引用 + sendBroadcast(""); // 发送完成广播 + stopSelf(); // 停止服务自身 } }); - sendBroadcast(""); - mSyncTask.execute(); + sendBroadcast(""); // 发送开始同步广播 + mSyncTask.execute(); // 执行异步任务 } } + //取消同步 private void cancelSync() { if (mSyncTask != null) { mSyncTask.cancelSync(); } } + //初始化同步任务引用 @Override public void onCreate() { mSyncTask = null; } + + /** + * @method onStartCommand + * @description 根据Intent中的动作类型执行相应的同步操作 + * @param intent 启动服务的Intent + * @param flags 启动标志 + * @param startId 启动ID + * @return 服务启动模式（START_STICKY表示服务被杀死后自动重启） + */ @Override public int onStartCommand(Intent intent, int flags, int startId) { Bundle bundle = intent.getExtras(); @@ -81,11 +109,12 @@ public class GTaskSyncService extends Service { default: break; } - return START_STICKY; + return START_STICKY; // 服务被杀死后自动重启 } return super.onStartCommand(intent, flags, startId); } + //当系统内存不足时，取消同步任务以释放资源 @Override public void onLowMemory() { if (mSyncTask != null) { @@ -93,10 +122,12 @@ public class GTaskSyncService extends Service { } } + //此服务不提供绑定功能，返回null public IBinder onBind(Intent intent) { return null; } + //发送同步状态广播 public void sendBroadcast(String msg) { mSyncProgress = msg; Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME); @@ -105,6 +136,8 @@ public class GTaskSyncService extends Service { sendBroadcast(intent); } + + //设置GTaskManager的Activity上下文并启动服务 public static void startSync(Activity activity) { GTaskManager.getInstance().setActivityContext(activity); Intent intent = new Intent(activity, GTaskSyncService.class); @@ -112,17 +145,22 @@ public class GTaskSyncService extends Service { activity.startService(intent); } + + //从Context调用的便捷方法，发送取消同步命令到服务 public static void cancelSync(Context context) { Intent intent = new Intent(context, GTaskSyncService.class); intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_CANCEL_SYNC); context.startService(intent); } + //检查是否正在同步 + public static boolean isSyncing() { return mSyncTask != null; } + public static String getProgressString() { return mSyncProgress; } -} +} \ No newline at end of file diff --git a/src/model/Note.java b/src/model/Note.java index 6706cf6..95f5f1b 100644 --- a/src/model/Note.java +++ b/src/model/Note.java @@ -34,9 +34,15 @@ import net.micode.notes.data.Notes.TextNote; import java.util.ArrayList; +/** + * + * @Package: net.micode.notes.model + * @ClassName: Note + * @Description: 定义了便签对象的基本操作：创建新便签、设置便签属性、同步便签等 + */ public class Note { - private ContentValues mNoteDiffValues; - private NoteData mNoteData; + private ContentValues mNoteDiffValues;//用于存储便签属性的变化 + private NoteData mNoteData;//用于存储便签的具体数据 private static final String TAG = "Note"; /** * Create a new note id for adding a new note to databases @@ -44,17 +50,17 @@ public class Note { public static synchronized long getNewNoteId(Context context, long folderId) { // Create a new note in the database ContentValues values = new ContentValues(); - long createdTime = System.currentTimeMillis(); + long createdTime = System.currentTimeMillis();// 获取当前时间作为创建时间 values.put(NoteColumns.CREATED_DATE, createdTime); values.put(NoteColumns.MODIFIED_DATE, createdTime); values.put(NoteColumns.TYPE, Notes.TYPE_NOTE); values.put(NoteColumns.LOCAL_MODIFIED, 1); values.put(NoteColumns.PARENT_ID, folderId); - Uri uri = context.getContentResolver().insert(Notes.CONTENT_NOTE_URI, values); + Uri uri = context.getContentResolver().insert(Notes.CONTENT_NOTE_URI, values);//获取新便签的 URI long noteId = 0; try { - noteId = Long.valueOf(uri.getPathSegments().get(1)); + noteId = Long.valueOf(uri.getPathSegments().get(1));// 从 URI 中提取便签 ID } catch (NumberFormatException e) { Log.e(TAG, "Get note id error :" + e.toString()); noteId = 0; @@ -71,9 +77,9 @@ public class Note { } public void setNoteValue(String key, String value) { - mNoteDiffValues.put(key, value); - mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1); - mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis()); + mNoteDiffValues.put(key, value);// 将便签属性的变化存储到 ContentValues 对象中 + mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);// 标记便签为本地已修改 + mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());// 更新修改时间 } public void setTextData(String key, String value) { @@ -97,9 +103,10 @@ public class Note { } public boolean isLocalModified() { - return mNoteDiffValues.size() > 0 || mNoteData.isLocalModified(); + return mNoteDiffValues.size() > 0 || mNoteData.isLocalModified();//便签属性或数据是否有本地修改 } + //同步便签到内容提供器中 public boolean syncNote(Context context, long noteId) { if (noteId <= 0) { throw new IllegalArgumentException("Wrong note id:" + noteId); @@ -130,6 +137,7 @@ public class Note { return true; } + //内部类：用于存储便签的具体数据 private class NoteData { private long mTextDataId; @@ -178,6 +186,16 @@ public class Note { mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis()); } + + /** + * @method pushIntoContentResolver + * @description 将便签数据（文本数据和通话数据）批量同步到Content Provider中 + * @param context Android上下文，用于访问ContentResolver + * @param noteId 当前便签的唯一标识符，用于关联数据记录 + * @return Uri 操作成功时返回便签的完整URI，失败时返回null + * 调用路径： + * WorkingNote.saveNote() → Note.syncNote() → NoteData.pushIntoContentResolver() + */ Uri pushIntoContentResolver(Context context, long noteId) { /** * Check for safety @@ -189,6 +207,7 @@ public class Note { ArrayList operationList = new ArrayList(); ContentProviderOperation.Builder builder = null; + //处理文本数据变更 if(mTextDataValues.size() > 0) { mTextDataValues.put(DataColumns.NOTE_ID, noteId); if (mTextDataId == 0) { @@ -211,6 +230,7 @@ public class Note { mTextDataValues.clear(); } + //处理通话数据变更 if(mCallDataValues.size() > 0) { mCallDataValues.put(DataColumns.NOTE_ID, noteId); if (mCallDataId == 0) { @@ -233,10 +253,13 @@ public class Note { mCallDataValues.clear(); } + //执行批量操作 if (operationList.size() > 0) { try { + //批量应用所有数据库操作 applyBatch()确保所有操作在单个事务中执行 ContentProviderResult[] results = context.getContentResolver().applyBatch( Notes.AUTHORITY, operationList); + //检查批量操作结果 成功时返回便签的完整URI return (results == null || results.length == 0 || results[0] == null) ? null : ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId); } catch (RemoteException e) { diff --git a/src/model/WorkingNote.java b/src/model/WorkingNote.java index be081e4..61ec1f0 100644 --- a/src/model/WorkingNote.java +++ b/src/model/WorkingNote.java @@ -60,8 +60,9 @@ public class WorkingNote { private boolean mIsDeleted; - private NoteSettingChangedListener mNoteSettingStatusListener; + private NoteSettingChangedListener mNoteSettingStatusListener;// 设置变化监听器 + //数据表查询字段投影 用于查询便签数据 public static final String[] DATA_PROJECTION = new String[] { DataColumns.ID, DataColumns.CONTENT, @@ -72,6 +73,7 @@ public class WorkingNote { DataColumns.DATA4, }; + //便签表查询字段投影 用于查询便签属性 public static final String[] NOTE_PROJECTION = new String[] { NoteColumns.PARENT_ID, NoteColumns.ALERTED_DATE, @@ -101,7 +103,7 @@ public class WorkingNote { private static final int NOTE_MODIFIED_DATE_COLUMN = 5; - // New note construct + // New note construct 创建新便签 private WorkingNote(Context context, long folderId) { mContext = context; mAlertDate = 0; @@ -114,7 +116,7 @@ public class WorkingNote { mWidgetType = Notes.TYPE_WIDGET_INVALIDE; } - // Existing note construct + // Existing note construct 加载现有便签 private WorkingNote(Context context, long noteId, long folderId) { mContext = context; mNoteId = noteId; @@ -124,7 +126,9 @@ public class WorkingNote { loadNote(); } + //从数据库加载便签基本属性 private void loadNote() { + // 构建便签查询URI Cursor cursor = mContext.getContentResolver().query( ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, mNoteId), NOTE_PROJECTION, null, null, null); @@ -143,9 +147,11 @@ public class WorkingNote { Log.e(TAG, "No note with id:" + mNoteId); throw new IllegalArgumentException("Unable to find note with id " + mNoteId); } - loadNoteData(); + loadNoteData(); // 继续加载便签内容数据 + } + //加载便签的内容数据 private void loadNoteData() { Cursor cursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI, DATA_PROJECTION, DataColumns.NOTE_ID + "=?", new String[] { @@ -157,10 +163,12 @@ public class WorkingNote { do { String type = cursor.getString(DATA_MIME_TYPE_COLUMN); if (DataConstants.NOTE.equals(type)) { + //处理文本便签数据 mContent = cursor.getString(DATA_CONTENT_COLUMN); mMode = cursor.getInt(DATA_MODE_COLUMN); mNote.setTextDataId(cursor.getLong(DATA_ID_COLUMN)); } else if (DataConstants.CALL_NOTE.equals(type)) { + //处理通话便签数据 mNote.setCallDataId(cursor.getLong(DATA_ID_COLUMN)); } else { Log.d(TAG, "Wrong note type with type:" + type); @@ -174,6 +182,7 @@ public class WorkingNote { } } + //创建空便签工厂方法 public static WorkingNote createEmptyNote(Context context, long folderId, int widgetId, int widgetType, int defaultBgColorId) { WorkingNote note = new WorkingNote(context, folderId); @@ -183,24 +192,32 @@ public class WorkingNote { return note; } + //加载现有便签的工厂方法 public static WorkingNote load(Context context, long id) { return new WorkingNote(context, id, 0); } public synchronized boolean saveNote() { if (isWorthSaving()) { + // 新便签：创建数据库记录并获取ID if (!existInDatabase()) { if ((mNoteId = Note.getNewNoteId(mContext, mFolderId)) == 0) { Log.e(TAG, "Create new note fail with id:" + mNoteId); return false; } } - - mNote.syncNote(mContext, mNoteId); + mNote.syncNote(mContext, mNoteId);//同步便签数据到数据库 /** * Update widget content if there exist any widget of this note */ + /** + * 更新小部件内容 + * 条件： + * 1. 有有效的小部件ID + * 2. 有有效的小部件类型 + * 3. 设置了监听器 + */ if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID && mWidgetType != Notes.TYPE_WIDGET_INVALIDE && mNoteSettingStatusListener != null) { @@ -212,11 +229,20 @@ public class WorkingNote { } } + //检查便签是否已存在于数据库中 public boolean existInDatabase() { return mNoteId > 0; } - private boolean isWorthSaving() { + /** + * 判断便签是否值得保存 + * + * 不值得保存的几种情况： + * 1. 便签已被标记为删除 + * 2. 新便签且内容为空 + * 3. 已有便签但没有本地修改 + */ + private boolean isWorthSaving() { if (mIsDeleted || (!existInDatabase() && TextUtils.isEmpty(mContent)) || (existInDatabase() && !mNote.isLocalModified())) { return false; @@ -239,8 +265,10 @@ public class WorkingNote { } } + //标记便签为删除状态 public void markDeleted(boolean mark) { mIsDeleted = mark; + // 如果便签有关联的小部件，通知小部件更新 if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID && mWidgetType != Notes.TYPE_WIDGET_INVALIDE && mNoteSettingStatusListener != null) { mNoteSettingStatusListener.onWidgetChanged(); @@ -257,6 +285,7 @@ public class WorkingNote { } } + //设置清单模式 public void setCheckListMode(int mode) { if (mMode != mode) { if (mNoteSettingStatusListener != null) { @@ -281,6 +310,7 @@ public class WorkingNote { } } + //设置便签工作文本内容 public void setWorkingText(String text) { if (!TextUtils.equals(mContent, text)) { mContent = text; @@ -288,6 +318,7 @@ public class WorkingNote { } } + //将普通便签转换为通话便签 public void convertToCallNote(String phoneNumber, long callDate) { mNote.setCallData(CallNote.CALL_DATE, String.valueOf(callDate)); mNote.setCallData(CallNote.PHONE_NUMBER, phoneNumber); @@ -342,6 +373,7 @@ public class WorkingNote { return mWidgetType; } + //便签设置变化监听器接口 public interface NoteSettingChangedListener { /** * Called when the background color of current note has just changed diff --git a/src/tool/BackupUtils.java b/src/tool/BackupUtils.java index 39f6ec4..0fbf526 100644 --- a/src/tool/BackupUtils.java +++ b/src/tool/BackupUtils.java @@ -41,38 +41,34 @@ public class BackupUtils { // Singleton stuff private static BackupUtils sInstance; - public static synchronized BackupUtils getInstance(Context context) { + //ynchronized 关键字，代表这个方法加锁,防止多进程混乱 if (sInstance == null) { + //如果当前备份不存在，则新声明一个 sInstance = new BackupUtils(context); } return sInstance; } - - /** - * Following states are signs to represents backup or restore - * status - */ - // Currently, the sdcard is not mounted + // 当前 SD 卡未挂载 public static final int STATE_SD_CARD_UNMOUONTED = 0; - // The backup file not exist + // 文件不存在 public static final int STATE_BACKUP_FILE_NOT_EXIST = 1; - // The data is not well formated, may be changed by other programs + // 数据格式损坏（可能被其他程序修改） public static final int STATE_DATA_DESTROIED = 2; - // Some run-time exception which causes restore or backup fails + // 运行时异常导致备份/恢复失败 public static final int STATE_SYSTEM_ERROR = 3; - // Backup or restore success + // 备份或重新储存成功？？？ public static final int STATE_SUCCESS = 4; - + //文本提取 private TextExport mTextExport; - + //初始化类，将该类设置为context接口格式，提供了访问资源、启动组件、获取系统服务、管理文件、执行权限检查等。 private BackupUtils(Context context) { mTextExport = new TextExport(context); } - + // 获取外部存储的根目录，便于进行api操作 private static boolean externalStorageAvailable() { return Environment.MEDIA_MOUNTED.equals(Environment.getExternalStorageState()); } - + // mTextExport是一个静态内部类,提供了导出功能 public int exportToText() { return mTextExport.exportToText(); } @@ -86,20 +82,20 @@ public class BackupUtils { } private static class TextExport { - private static final String[] NOTE_PROJECTION = { + private static final String[] NOTE_PROJECTION = { //文本基础信息 NoteColumns.ID, NoteColumns.MODIFIED_DATE, - NoteColumns.SNIPPET, + NoteColumns.SNIPPET, //文本片段 NoteColumns.TYPE }; - + //定义类级别的常量.p s f，下面的 数字代表在字符串中存储位置 private static final int NOTE_COLUMN_ID = 0; private static final int NOTE_COLUMN_MODIFIED_DATE = 1; private static final int NOTE_COLUMN_SNIPPET = 2; - private static final String[] DATA_PROJECTION = { + private static final String[] DATA_PROJECTION = { //数据基础信息，这个数据是啥数据？？？ DataColumns.CONTENT, DataColumns.MIME_TYPE, DataColumns.DATA1, @@ -110,7 +106,7 @@ public class BackupUtils { private static final int DATA_COLUMN_CONTENT = 0; - private static final int DATA_COLUMN_MIME_TYPE = 1; + private static final int DATA_COLUMN_MIME_TYPE = 1; //导出笔记时，先查询这条笔记的 DATA_COLUMN_MIME_TYPE 值，判断格式 private static final int DATA_COLUMN_CALL_DATE = 2; @@ -126,7 +122,7 @@ public class BackupUtils { private String mFileDirectory; public TextExport(Context context) { - TEXT_FORMAT = context.getResources().getStringArray(R.array.format_for_exported_note); + TEXT_FORMAT = context.getResources().getStringArray(R.array.format_for_exported_note);//从array.xml里获取字符串数组信息 mContext = context; mFileName = ""; mFileDirectory = ""; @@ -137,33 +133,33 @@ public class BackupUtils { } /** - * Export the folder identified by folder id to text + * Export the folder identified by folder id to text ，从文件夹流向便签 */ private void exportFolderToText(String folderId, PrintStream ps) { // Query notes belong to this folder Cursor notesCursor = mContext.getContentResolver().query(Notes.CONTENT_NOTE_URI, NOTE_PROJECTION, NoteColumns.PARENT_ID + "=?", new String[] { - folderId + folderId //引用的别的类的啥？？父母ID }, null); - if (notesCursor != null) { - if (notesCursor.moveToFirst()) { + if (notesCursor != null) { //遍历cursor的数据 + if (notesCursor.moveToFirst()) { //在开头 do { // Print note's last modified date ps.println(String.format(getFormat(FORMAT_NOTE_DATE), DateFormat.format( - mContext.getString(R.string.format_datetime_mdhm), - notesCursor.getLong(NOTE_COLUMN_MODIFIED_DATE)))); + mContext.getString(R.string.format_datetime_mdhm), //R.string.xxx 是一个引用字符串资源的标识符，它直接指向资源文件中的字符串,用gststring执行 + notesCursor.getLong(NOTE_COLUMN_MODIFIED_DATE)))); //getXX，XX是结构 // Query data belong to this note String noteId = notesCursor.getString(NOTE_COLUMN_ID); exportNoteToText(noteId, ps); - } while (notesCursor.moveToNext()); + } while (notesCursor.moveToNext()); //没有下一个就终止，代表数据遍历完毕 } notesCursor.close(); } } /** - * Export note identified by id to a print stream + * Export note identified by id to a print stream，从便签流向文本流 */ private void exportNoteToText(String noteId, PrintStream ps) { Cursor dataCursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI, @@ -175,14 +171,14 @@ public class BackupUtils { if (dataCursor.moveToFirst()) { do { String mimeType = dataCursor.getString(DATA_COLUMN_MIME_TYPE); - if (DataConstants.CALL_NOTE.equals(mimeType)) { + if (DataConstants.CALL_NOTE.equals(mimeType)) { //有电话的note // Print phone number String phoneNumber = dataCursor.getString(DATA_COLUMN_PHONE_NUMBER); long callDate = dataCursor.getLong(DATA_COLUMN_CALL_DATE); String location = dataCursor.getString(DATA_COLUMN_CONTENT); if (!TextUtils.isEmpty(phoneNumber)) { - ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), + ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), //在导出内容时，把phoneNumber填充到 “笔记内容的格式模板” 并打印出来 phoneNumber)); } // Print call date @@ -216,9 +212,10 @@ public class BackupUtils { } /** - * Note will be exported as text which is user readable + * Note will be exported as text which is user readable ,下面的是主函数 */ public int exportToText() { + //判断两个失败条件 if (!externalStorageAvailable()) { Log.d(TAG, "Media was not mounted"); return STATE_SD_CARD_UNMOUONTED; @@ -229,22 +226,22 @@ public class BackupUtils { Log.e(TAG, "get print stream error"); return STATE_SYSTEM_ERROR; } - // First export folder and its notes + // First export folder and its notes 输出在文件夹中的便签 Cursor folderCursor = mContext.getContentResolver().query( Notes.CONTENT_NOTE_URI, NOTE_PROJECTION, "(" + NoteColumns.TYPE + "=" + Notes.TYPE_FOLDER + " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER + ") OR " - + NoteColumns.ID + "=" + Notes.ID_CALL_RECORD_FOLDER, null, null); + + NoteColumns.ID + "=" + Notes.ID_CALL_RECORD_FOLDER, null, null); //xinxi if (folderCursor != null) { if (folderCursor.moveToFirst()) { do { // Print folder's name String folderName = ""; - if(folderCursor.getLong(NOTE_COLUMN_ID) == Notes.ID_CALL_RECORD_FOLDER) { - folderName = mContext.getString(R.string.call_record_folder_name); - } else { + if(folderCursor.getLong(NOTE_COLUMN_ID) == Notes.ID_CALL_RECORD_FOLDER) { //这个判断何意味，为啥一个cursor一个context + folderName = mContext.getString(R.string.call_record_folder_name); //Context.getString 是 Android 中用于从资源文件中获取字符串的方法 + } else { //cursor.getString 是 Android 中用于从数据库中获取字符串类型数据的方法 folderName = folderCursor.getString(NOTE_COLUMN_SNIPPET); } if (!TextUtils.isEmpty(folderName)) { @@ -257,7 +254,7 @@ public class BackupUtils { folderCursor.close(); } - // Export notes in root's folder + // Export notes in root's folder，输出根目录中的便签 Cursor noteCursor = mContext.getContentResolver().query( Notes.CONTENT_NOTE_URI, NOTE_PROJECTION, @@ -279,15 +276,16 @@ public class BackupUtils { } ps.close(); - return STATE_SUCCESS; + return STATE_SUCCESS; //都能对应上 } /** - * Get a print stream pointed to the file {@generateExportedTextFile} + * Get a print stream pointed to the file {@generateExportedTextFile} ， + */ private PrintStream getExportToTextPrintStream() { File file = generateFileMountedOnSDcard(mContext, R.string.file_path, - R.string.file_name_txt_format); + R.string.file_name_txt_format); //建一个指向 SD 卡指定目录的 TXT 导出文件 if (file == null) { Log.e(TAG, "create file to exported failed"); return null; @@ -295,9 +293,9 @@ public class BackupUtils { mFileName = file.getName(); mFileDirectory = mContext.getString(R.string.file_path); PrintStream ps = null; - try { + try { //try catch语法 FileOutputStream fos = new FileOutputStream(file); - ps = new PrintStream(fos); + ps = new PrintStream(fos); //返回操作该文件的 PrintStream 输出流 } catch (FileNotFoundException e) { e.printStackTrace(); return null; @@ -310,25 +308,25 @@ public class BackupUtils { } /** - * Generate the text file to store imported data + * Generate the text file to store imported data把笔记内容（比如之前的电话号码、笔记正文）写入到 TXT 文件中。 */ private static File generateFileMountedOnSDcard(Context context, int filePathResId, int fileNameFormatResId) { StringBuilder sb = new StringBuilder(); sb.append(Environment.getExternalStorageDirectory()); sb.append(context.getString(filePathResId)); File filedir = new File(sb.toString()); - sb.append(context.getString( + sb.append(context.getString( fileNameFormatResId, DateFormat.format(context.getString(R.string.format_date_ymd), System.currentTimeMillis()))); - File file = new File(sb.toString()); + File file = new File(sb.toString()); //stringbuilder转成srting再写进file try { if (!filedir.exists()) { - filedir.mkdir(); + filedir.mkdir(); //文件目录 } if (!file.exists()) { - file.createNewFile(); + file.createNewFile(); //文件 } return file; } catch (SecurityException e) { diff --git a/src/tool/DataUtils.java b/src/tool/DataUtils.java index 2a14982..3c3e580 100644 --- a/src/tool/DataUtils.java +++ b/src/tool/DataUtils.java @@ -37,6 +37,7 @@ import java.util.HashSet; public class DataUtils { public static final String TAG = "DataUtils"; + //批量操作删除便签，发生错误就返回flase，删除成功就返回true public static boolean batchDeleteNotes(ContentResolver resolver, HashSet ids) { if (ids == null) { Log.d(TAG, "the ids is null"); @@ -46,32 +47,34 @@ public class DataUtils { Log.d(TAG, "no id is in the hashset"); return true; } - + // 构建删除操作：拼接标签ID到标签ContentUR ArrayList operationList = new ArrayList(); for (long id : ids) { if(id == Notes.ID_ROOT_FOLDER) { Log.e(TAG, "Don't delete system folder root"); continue; } + ContentProviderOperation.Builder builder = ContentProviderOperation .newDelete(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id)); + //创建一个 ContentProviderOperation.Builder，删除指定id的标签 只查询 ID 为 id 的那一条记录 operationList.add(builder.build()); } try { ContentProviderResult[] results = resolver.applyBatch(Notes.AUTHORITY, operationList); - if (results == null || results.length == 0 || results[0] == null) { + if (results == null || results.length == 0 || results[0] == null) {////上面的一条执行数据库操作删除并返回结果数组 Log.d(TAG, "delete notes failed, ids:" + ids.toString()); return false; } return true; - } catch (RemoteException e) { + } catch (RemoteException e) { //记录错误信息 Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage())); } catch (OperationApplicationException e) { Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage())); } return false; } - + //便签转进新文件夹 public static void moveNoteToFoler(ContentResolver resolver, long id, long srcFolderId, long desFolderId) { ContentValues values = new ContentValues(); values.put(NoteColumns.PARENT_ID, desFolderId); @@ -79,7 +82,7 @@ public class DataUtils { values.put(NoteColumns.LOCAL_MODIFIED, 1); resolver.update(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id), values, null, null); } - + //批量操作便签转进新文件夹 public static boolean batchMoveToFolder(ContentResolver resolver, HashSet ids, long folderId) { if (ids == null) { @@ -90,7 +93,7 @@ public class DataUtils { ArrayList operationList = new ArrayList(); for (long id : ids) { ContentProviderOperation.Builder builder = ContentProviderOperation - .newUpdate(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id)); + .newUpdate(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id)); //创建更新, builder.withValue(NoteColumns.PARENT_ID, folderId); builder.withValue(NoteColumns.LOCAL_MODIFIED, 1); operationList.add(builder.build()); @@ -110,11 +113,21 @@ public class DataUtils { } return false; } - /** * Get the all folder count except system folders {@link Notes#TYPE_SYSTEM}} */ - public static int getUserFolderCount(ContentResolver resolver) { + public static int getUserFolderCount(ContentResolver resolver) { + //查询设备中「类型为文件夹（TYPE_FOLDER）」且「父文件夹 ID 不等于回收站 ID（ID_TRASH_FOLER）」的文件夹总数。 +''' +触发了一次跨进程的数据库查询操作 +Cursor query( + Uri uri, // 要查询的数据 URI + String[] projection, // 要返回的列（字段），null 表示所有列 + String selection, // WHERE 子句（不含 "WHERE" 关键字） + String[] selectionArgs, // WHERE 子句中占位符 ? 的实际值 + String sortOrder // 排序方式（如 "date DESC"） +); +''' Cursor cursor =resolver.query(Notes.CONTENT_NOTE_URI, new String[] { "COUNT(*)" }, NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>?", @@ -125,7 +138,7 @@ public class DataUtils { if(cursor != null) { if(cursor.moveToFirst()) { try { - count = cursor.getInt(0); + count = cursor.getInt(0);//从当前游标指向的行中，读取第 0 列（第一列）的整数类型数据 } catch (IndexOutOfBoundsException e) { Log.e(TAG, "get folder count failed:" + e.toString()); } finally { @@ -135,11 +148,11 @@ public class DataUtils { } return count; } - + //变迁是否可见（没进回收站） public static boolean visibleInNoteDatabase(ContentResolver resolver, long noteId, int type) { Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId), null, - NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER, + NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER, //笔记的 parent_id 不能等于回收站的 ID（即不在回收站中） new String [] {String.valueOf(type)}, null); @@ -152,7 +165,7 @@ public class DataUtils { } return exist; } - + //便签还存在否 public static boolean existInNoteDatabase(ContentResolver resolver, long noteId) { Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId), null, null, null, null); @@ -166,7 +179,7 @@ public class DataUtils { } return exist; } - + //便签数据还存在否 public static boolean existInDataDatabase(ContentResolver resolver, long dataId) { Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, dataId), null, null, null, null); @@ -180,12 +193,12 @@ public class DataUtils { } return exist; } - + //查看是否存在一个名字是XX的文件夹 public static boolean checkVisibleFolderName(ContentResolver resolver, String name) { Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI, null, - NoteColumns.TYPE + "=" + Notes.TYPE_FOLDER + - " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER + - " AND " + NoteColumns.SNIPPET + "=?", + NoteColumns.TYPE + "=" + Notes.TYPE_FOLDER + //类型是文件夹 + " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER +//没进回收站 + " AND " + NoteColumns.SNIPPET + "=?", //存储在snippet的名字和下面的name一样 new String[] { name }, null); boolean exist = false; if(cursor != null) { @@ -196,9 +209,9 @@ public class DataUtils { } return exist; } - + //获得文件夹下的便签，并仅返回它们的 Widget ID 和 Widget 类型 public static HashSet getFolderNoteWidget(ContentResolver resolver, long folderId) { - Cursor c = resolver.query(Notes.CONTENT_NOTE_URI, + Cursor c = resolver.query(Notes.CONTENT_NOTE_URI, //获得便签 new String[] { NoteColumns.WIDGET_ID, NoteColumns.WIDGET_TYPE }, NoteColumns.PARENT_ID + "=?", new String[] { String.valueOf(folderId) }, @@ -223,7 +236,7 @@ public class DataUtils { } return set; } - + //获得电话号 public static String getCallNumberByNoteId(ContentResolver resolver, long noteId) { Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI, new String [] { CallNote.PHONE_NUMBER }, @@ -233,7 +246,7 @@ public class DataUtils { if (cursor != null && cursor.moveToFirst()) { try { - return cursor.getString(0); + return cursor.getString(0); //返回电话号 } catch (IndexOutOfBoundsException e) { Log.e(TAG, "Get call number fails " + e.toString()); } finally { @@ -242,7 +255,7 @@ public class DataUtils { } return ""; } - +//通过电话号和日期查找便签 public static long getNoteIdByPhoneNumberAndCallDate(ContentResolver resolver, String phoneNumber, long callDate) { Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI, new String [] { CallNote.NOTE_ID }, @@ -263,7 +276,7 @@ public class DataUtils { } return 0; } - +//通过id获得名字 public static String getSnippetById(ContentResolver resolver, long noteId) { Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI, new String [] { NoteColumns.SNIPPET }, @@ -281,13 +294,13 @@ public class DataUtils { } throw new IllegalArgumentException("Note is not found with id: " + noteId); } - +//从一段文本（snippet）中提取作为标题 public static String getFormattedSnippet(String snippet) { if (snippet != null) { - snippet = snippet.trim(); - int index = snippet.indexOf('\n'); + snippet = snippet.trim();//清空无用制表符 + int index = snippet.indexOf('\n');//index即录字符串中第一个换行符 \n 出现的位置 if (index != -1) { - snippet = snippet.substring(0, index); + snippet = snippet.substring(0, index);//只获取换行前的部分（核心）。 } } return snippet; diff --git a/src/tool/GTaskStringUtils.java b/src/tool/GTaskStringUtils.java index 666b729..7a4b50f 100644 --- a/src/tool/GTaskStringUtils.java +++ b/src/tool/GTaskStringUtils.java @@ -15,7 +15,7 @@ */ package net.micode.notes.tool; - +//定义一些与 Google Tasks（GTask）JSON 数据交互相关的常量字符串,为与 Google Tasks 同步相关的 JSON 数据结构提供标准化的字段名常量，便于在GTask上同步 public class GTaskStringUtils { public final static String GTASK_JSON_ACTION_ID = "action_id"; diff --git a/src/tool/ResourceParser.java b/src/tool/ResourceParser.java index 1ad3ad6..896e9a4 100644 --- a/src/tool/ResourceParser.java +++ b/src/tool/ResourceParser.java @@ -19,7 +19,7 @@ package net.micode.notes.tool; import android.content.Context; import android.preference.PreferenceManager; -import net.micode.notes.R; +import net.micode.notes.R; //资源文件夹中的文件被编译成R类的一部分，R类在编译过程中会生成 import net.micode.notes.ui.NotesPreferenceActivity; public class ResourceParser { @@ -40,6 +40,7 @@ public class ResourceParser { public static final int BG_DEFAULT_FONT_SIZE = TEXT_MEDIUM; public static class NoteBgResources { + //引用背景颜色资源 private final static int [] BG_EDIT_RESOURCES = new int [] { R.drawable.edit_yellow, R.drawable.edit_blue, @@ -47,7 +48,7 @@ public class ResourceParser { R.drawable.edit_green, R.drawable.edit_red }; - + //引用标题颜色资源 private final static int [] BG_EDIT_TITLE_RESOURCES = new int [] { R.drawable.edit_title_yellow, R.drawable.edit_title_blue, @@ -55,7 +56,7 @@ public class ResourceParser { R.drawable.edit_title_green, R.drawable.edit_title_red }; - + public static int getNoteBgResource(int id) { return BG_EDIT_RESOURCES[id]; } @@ -66,15 +67,15 @@ public class ResourceParser { } public static int getDefaultBgId(Context context) { - if (PreferenceManager.getDefaultSharedPreferences(context).getBoolean( - NotesPreferenceActivity.PREFERENCE_SET_BG_COLOR_KEY, false)) { + if (PreferenceManager.getDefaultSharedPreferences(context).getBoolean( //获得一个实例，指向该偏好框架在给定上下文中使用的默认文件 + NotesPreferenceActivity.PREFERENCE_SET_BG_COLOR_KEY, false)) { //如果没指定就随机给个颜色 return (int) (Math.random() * NoteBgResources.BG_EDIT_RESOURCES.length); } else { return BG_DEFAULT_COLOR; } } - public static class NoteItemBgResources { + public static class NoteItemBgResources { //便签主题资源 private final static int [] BG_FIRST_RESOURCES = new int [] { R.drawable.list_yellow_up, R.drawable.list_blue_up, diff --git a/src/ui/AlarmAlertActivity.java b/src/ui/AlarmAlertActivity.java index 85723be..6e80b45 100644 --- a/src/ui/AlarmAlertActivity.java +++ b/src/ui/AlarmAlertActivity.java @@ -39,42 +39,49 @@ import net.micode.notes.tool.DataUtils; import java.io.IOException; - + //继承Activity //承诺实现click，dismiss接口，不继承功能 public class AlarmAlertActivity extends Activity implements OnClickListener, OnDismissListener { private long mNoteId; private String mSnippet; private static final int SNIPPET_PREW_MAX_LEN = 60; MediaPlayer mPlayer; - @Override + @Override //创建闹钟行为 protected void onCreate(Bundle savedInstanceState) { + //调用其父类Activity的onCreate方法来实现对界面的图画绘制工作。 super.onCreate(savedInstanceState); + //onSaveInstanceState()来保存当前activity的状态信息 requestWindowFeature(Window.FEATURE_NO_TITLE); - + //final类似stactic，获得窗口对象 final Window win = getWindow(); + //为窗口添加各种标志（flags），从而改变窗口的行为和外观 + //屏幕锁定时显示窗口，便于锁屏时启动闹钟 win.addFlags(WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED); - - if (!isScreenOn()) { - win.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON - | WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON - | WindowManager.LayoutParams.FLAG_ALLOW_LOCK_WHILE_SCREEN_ON - | WindowManager.LayoutParams.FLAG_LAYOUT_INSET_DECOR); + //LayoutParams 布局参数，规定子视图如何放置 + if (!isScreenOn()) {//不锁平时 + win.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON//当这个window对用户是可见状态,则保持设备屏幕不关闭且不变暗 + | WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON//当window被添加或者显示,系统会点亮屏幕, + | WindowManager.LayoutParams.FLAG_ALLOW_LOCK_WHILE_SCREEN_ON//允许在屏幕开启的时候锁定屏幕 + | WindowManager.LayoutParams.FLAG_LAYOUT_INSET_DECOR);//插入window的矩形大小,来确保内容不会被装饰物(如状态栏)掩盖 } Intent intent = getIntent(); - try { + try { //传递到当前组件的 URI 数据，截取Uri内的字符串的第二个“/”右边的字符及id mNoteId = Long.valueOf(intent.getData().getPathSegments().get(1)); + //根据ID从数据库中获取标签的内容 mSnippet = DataUtils.getSnippetById(this.getContentResolver(), mNoteId); + //判断是否超过最大长度，超过执行截取操作 mSnippet = mSnippet.length() > SNIPPET_PREW_MAX_LEN ? mSnippet.substring(0, SNIPPET_PREW_MAX_LEN) + getResources().getString(R.string.notelist_string_info) : mSnippet; } catch (IllegalArgumentException e) { - e.printStackTrace(); + e.printStackTrace();// 将异常的详细信息输出到标准错误流 return; } mPlayer = new MediaPlayer(); + //如果不在回收站就显示文字并发出声音 if (DataUtils.visibleInNoteDatabase(getContentResolver(), mNoteId, Notes.TYPE_NOTE)) { showActionDialog(); playAlarmSound(); @@ -83,26 +90,27 @@ public class AlarmAlertActivity extends Activity implements OnClickListener, OnD } } - private boolean isScreenOn() { + private boolean isScreenOn() { //由电量判断屏幕状态 PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE); return pm.isScreenOn(); } private void playAlarmSound() { + //由铃声管理器获得默认铃声的uri Uri url = RingtoneManager.getActualDefaultRingtoneUri(this, RingtoneManager.TYPE_ALARM); - + //设置为有声铃声还是无声的参数 int silentModeStreams = Settings.System.getInt(getContentResolver(), Settings.System.MODE_RINGER_STREAMS_AFFECTED, 0); - + //无铃声模式且不报警就设置为无铃声 if ((silentModeStreams & (1 << AudioManager.STREAM_ALARM)) != 0) { mPlayer.setAudioStreamType(silentModeStreams); } else { mPlayer.setAudioStreamType(AudioManager.STREAM_ALARM); } try { - mPlayer.setDataSource(this, url); + mPlayer.setDataSource(this, url);//指定播放文件的路径 mPlayer.prepare(); - mPlayer.setLooping(true); + mPlayer.setLooping(true);//设置循环播放 mPlayer.start(); } catch (IllegalArgumentException e) { // TODO Auto-generated catch block @@ -120,34 +128,35 @@ public class AlarmAlertActivity extends Activity implements OnClickListener, OnD } private void showActionDialog() { + //AlertDialog.Builder是对话框组件，用于显示信息 AlertDialog.Builder dialog = new AlertDialog.Builder(this); dialog.setTitle(R.string.app_name); dialog.setMessage(mSnippet); - dialog.setPositiveButton(R.string.notealert_ok, this); + dialog.setPositiveButton(R.string.notealert_ok, this); //setPositive/Negative/NeutralButton()设置：确定，取消，中立按钮； if (isScreenOn()) { - dialog.setNegativeButton(R.string.notealert_enter, this); + dialog.setNegativeButton(R.string.notealert_enter, this); //取消 } - dialog.show().setOnDismissListener(this); + dialog.show().setOnDismissListener(this); //设置关闭监听 } - + //选择negative时执行跳转到笔记 （那可能positive仅关闭弹窗） public void onClick(DialogInterface dialog, int which) { switch (which) { case DialogInterface.BUTTON_NEGATIVE: Intent intent = new Intent(this, NoteEditActivity.class); - intent.setAction(Intent.ACTION_VIEW); - intent.putExtra(Intent.EXTRA_UID, mNoteId); - startActivity(intent); + intent.setAction(Intent.ACTION_VIEW);//执行安卓内置操作查看数据 + intent.putExtra(Intent.EXTRA_UID, mNoteId);//向目标页面传递笔记的ID + startActivity(intent);//触发页面跳转 break; default: break; } } - + //取消监听后操作 public void onDismiss(DialogInterface dialog) { stopAlarmSound(); finish(); } - + //取消声音 private void stopAlarmSound() { if (mPlayer != null) { mPlayer.stop(); diff --git a/src/ui/AlarmInitReceiver.java b/src/ui/AlarmInitReceiver.java index f221202..61176a0 100644 --- a/src/ui/AlarmInitReceiver.java +++ b/src/ui/AlarmInitReceiver.java @@ -27,7 +27,7 @@ import android.database.Cursor; import net.micode.notes.data.Notes; import net.micode.notes.data.Notes.NoteColumns; - + //广播接收器用于响应来自其他应用程序或者系统的广播消息（可以使事件） public class AlarmInitReceiver extends BroadcastReceiver { private static final String [] PROJECTION = new String [] { @@ -39,24 +39,31 @@ public class AlarmInitReceiver extends BroadcastReceiver { private static final int COLUMN_ALERTED_DATE = 1; @Override - public void onReceive(Context context, Intent intent) { + public void onReceive(Context context, Intent intent) { //设置接收装置 + //获取当前时间的常用方法。它返回自 1970 年 1 月 1 日 00:00:00.000 到当前时刻的时间距离 long currentDate = System.currentTimeMillis(); + //查询未到响应时间且是有提醒类型的便签 Cursor c = context.getContentResolver().query(Notes.CONTENT_NOTE_URI, PROJECTION, NoteColumns.ALERTED_DATE + ">? AND " + NoteColumns.TYPE + "=" + Notes.TYPE_NOTE, new String[] { String.valueOf(currentDate) }, null); - if (c != null) { if (c.moveToFirst()) { do { long alertDate = c.getLong(COLUMN_ALERTED_DATE); + //显示intent格式，明确启动应用中的AlarmReceiver类 Intent sender = new Intent(context, AlarmReceiver.class); + //指定要访问的资源URI(这里的uir是把id和contentUri连接后成一个新的Uri) sender.setData(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, c.getLong(COLUMN_ID))); + //(满足特定条件但这里是0即没有)向BroadcastReceiver发送执行sender的广播 PendingIntent pendingIntent = PendingIntent.getBroadcast(context, 0, sender, 0); + //获取 AlarmManager AlarmManager alermManager = (AlarmManager) context .getSystemService(Context.ALARM_SERVICE); + //set(int type，long startTime，PendingIntent pi) ,设置一次性定时器，到达时间执行完就没了 alermManager.set(AlarmManager.RTC_WAKEUP, alertDate, pendingIntent); + //闹钟在睡眠状态下会唤醒系统并执行提示功能 } while (c.moveToNext()); } c.close(); diff --git a/src/ui/AlarmReceiver.java b/src/ui/AlarmReceiver.java index 54e503b..e072fbb 100644 --- a/src/ui/AlarmReceiver.java +++ b/src/ui/AlarmReceiver.java @@ -20,11 +20,11 @@ import android.content.BroadcastReceiver; import android.content.Context; import android.content.Intent; -public class AlarmReceiver extends BroadcastReceiver { +public class AlarmReceiver extends BroadcastReceiver {//闹钟响应广播接收者 @Override public void onReceive(Context context, Intent intent) { - intent.setClass(context, AlarmAlertActivity.class); - intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); - context.startActivity(intent); + intent.setClass(context, AlarmAlertActivity.class); //启动闹钟响应的行为 + intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);//启动一个新的任务栈,为何要启动新的？？？ + context.startActivity(intent);//执行 } } diff --git a/src/ui/DateTimePicker.java b/src/ui/DateTimePicker.java index 496b0cd..d921f3b 100644 --- a/src/ui/DateTimePicker.java +++ b/src/ui/DateTimePicker.java @@ -27,7 +27,7 @@ import android.text.format.DateFormat; import android.view.View; import android.widget.FrameLayout; import android.widget.NumberPicker; - + //FrameLayout 是 Android 布局容器之一，用于在屏幕上开辟一块区域，将子控件按照添加顺序进行层叠显示 public class DateTimePicker extends FrameLayout { private static final boolean DEFAULT_ENABLE_STATE = true; @@ -45,56 +45,56 @@ public class DateTimePicker extends FrameLayout { private static final int MINUT_SPINNER_MAX_VAL = 59; private static final int AMPM_SPINNER_MIN_VAL = 0; private static final int AMPM_SPINNER_MAX_VAL = 1; - + //XX选择器设置 + //这里定义的四个变量全部是在设置闹钟时需要选择的变量（如日期、时、分、上午或者下午） private final NumberPicker mDateSpinner; private final NumberPicker mHourSpinner; private final NumberPicker mMinuteSpinner; private final NumberPicker mAmPmSpinner; private Calendar mDate; - private String[] mDateDisplayValues = new String[DAYS_IN_ALL_WEEK]; - - private boolean mIsAm; + private String[] mDateDisplayValues = new String[DAYS_IN_ALL_WEEK];// + + private boolean mIsAm; //12小时制是否上午 - private boolean mIs24HourView; + private boolean mIs24HourView;//24小时制 - private boolean mIsEnabled = DEFAULT_ENABLE_STATE; + private boolean mIsEnabled = DEFAULT_ENABLE_STATE; //是否启动？ - private boolean mInitialising; + private boolean mInitialising; //是否正在初始化？ - private OnDateTimeChangedListener mOnDateTimeChangedListener; - - private NumberPicker.OnValueChangeListener mOnDateChangedListener = new NumberPicker.OnValueChangeListener() { + private OnDateTimeChangedListener mOnDateTimeChangedListener; //自定义接口，创建接口类型变量,外部实现功能，可以调用onDateTimeChanged了 + //系统接口，自己实现功能，当用户滑动日期滚轮（比如从 5 号滑到 6 号），系统会自动调用onValueChange方法 + private NumberPicker.OnValueChangeListener mOnDateChangedListener = new NumberPicker.OnValueChangeListener() { //日期变更 @Override - public void onValueChange(NumberPicker picker, int oldVal, int newVal) { + public void onValueChange(NumberPicker picker, int oldVal, int newVal) { mDate.add(Calendar.DAY_OF_YEAR, newVal - oldVal); - updateDateControl(); - onDateTimeChanged(); + updateDateControl();//更新日期 + onDateTimeChanged();//触发自定义接口的回调（把事件传给外部）[实现方法不在此类]，作用未知？？ } }; - - private NumberPicker.OnValueChangeListener mOnHourChangedListener = new NumberPicker.OnValueChangeListener() { + private NumberPicker.OnValueChangeListener mOnHourChangedListener = new NumberPicker.OnValueChangeListener() { //小时变更 @Override public void onValueChange(NumberPicker picker, int oldVal, int newVal) { boolean isDateChanged = false; - Calendar cal = Calendar.getInstance(); - if (!mIs24HourView) { - if (!mIsAm && oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY) { - cal.setTimeInMillis(mDate.getTimeInMillis()); + Calendar cal = Calendar.getInstance(); //获取现在的日历 + if (!mIs24HourView) { //12小时制 + if (!mIsAm && oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY) { //从十一点多调整到第二天0点，日期加一。 + cal.setTimeInMillis(mDate.getTimeInMillis());// set time to（ 1970 年 1 月 1 日的 00:00:00.000到Calendar对象表示的时间之间的毫秒数 ）after january 1 1970 cal.add(Calendar.DAY_OF_YEAR, 1); isDateChanged = true; - } else if (mIsAm && oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) { + } else if (mIsAm && oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) {//从0点多调整到昨天点，日期加一。 cal.setTimeInMillis(mDate.getTimeInMillis()); cal.add(Calendar.DAY_OF_YEAR, -1); isDateChanged = true; } - if (oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY || + if (oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY || //上下午切换 oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) { mIsAm = !mIsAm; updateAmPmControl(); } - } else { - if (oldVal == HOURS_IN_ALL_DAY - 1 && newVal == 0) { + } else {//24小时制 + if (oldVal == HOURS_IN_ALL_DAY - 1 && newVal == 0) {//同上面日期切换逻辑 cal.setTimeInMillis(mDate.getTimeInMillis()); cal.add(Calendar.DAY_OF_YEAR, 1); isDateChanged = true; @@ -104,8 +104,8 @@ public class DateTimePicker extends FrameLayout { isDateChanged = true; } } - int newHour = mHourSpinner.getValue() % HOURS_IN_HALF_DAY + (mIsAm ? 0 : HOURS_IN_HALF_DAY); - mDate.set(Calendar.HOUR_OF_DAY, newHour); + int newHour = mHourSpinner.getValue() % HOURS_IN_HALF_DAY + (mIsAm ? 0 : HOURS_IN_HALF_DAY);//24小时制的小时时间数 + mDate.set(Calendar.HOUR_OF_DAY, newHour); //通过set函数将新的Hour值传给mDate onDateTimeChanged(); if (isDateChanged) { setCurrentYear(cal.get(Calendar.YEAR)); @@ -115,18 +115,18 @@ public class DateTimePicker extends FrameLayout { } }; - private NumberPicker.OnValueChangeListener mOnMinuteChangedListener = new NumberPicker.OnValueChangeListener() { + private NumberPicker.OnValueChangeListener mOnMinuteChangedListener = new NumberPicker.OnValueChangeListener() {//分钟变更 @Override public void onValueChange(NumberPicker picker, int oldVal, int newVal) { int minValue = mMinuteSpinner.getMinValue(); int maxValue = mMinuteSpinner.getMaxValue(); - int offset = 0; + int offset = 0; //分钟导致的的小时切换 if (oldVal == maxValue && newVal == minValue) { - offset += 1; + offset += 1; //小时加一 } else if (oldVal == minValue && newVal == maxValue) { - offset -= 1; + offset -= 1; //小时减一 } - if (offset != 0) { + if (offset != 0) { //更新小时时间 mDate.add(Calendar.HOUR_OF_DAY, offset); mHourSpinner.setValue(getCurrentHour()); updateDateControl(); @@ -139,44 +139,44 @@ public class DateTimePicker extends FrameLayout { updateAmPmControl(); } } - mDate.set(Calendar.MINUTE, newVal); + mDate.set(Calendar.MINUTE, newVal);//通过set函数将新的minutes值传给mDate onDateTimeChanged(); } }; - private NumberPicker.OnValueChangeListener mOnAmPmChangedListener = new NumberPicker.OnValueChangeListener() { + private NumberPicker.OnValueChangeListener mOnAmPmChangedListener = new NumberPicker.OnValueChangeListener() {//上下午变更 @Override public void onValueChange(NumberPicker picker, int oldVal, int newVal) { - mIsAm = !mIsAm; - if (mIsAm) { + mIsAm = !mIsAm;//为啥要变成否定的 + if (mIsAm) {//下午变成上午了24小时制减去12 mDate.add(Calendar.HOUR_OF_DAY, -HOURS_IN_HALF_DAY); - } else { - mDate.add(Calendar.HOUR_OF_DAY, HOURS_IN_HALF_DAY); + } else {//上午变下午，就加12除余 + mDate.add(Calendar.HOUR_OF_DAY, HOURS_IN_HALF_DAY);// } updateAmPmControl(); onDateTimeChanged(); } }; - public interface OnDateTimeChangedListener { + public interface OnDateTimeChangedListener {//接口，要求实现onDateTimeChanged void onDateTimeChanged(DateTimePicker view, int year, int month, int dayOfMonth, int hourOfDay, int minute); } - public DateTimePicker(Context context) { + public DateTimePicker(Context context) {// 获得1970 年 1 月 1 日的 00:00:00.000到Calendar对象表示的时间之间的毫秒数 this(context, System.currentTimeMillis()); } public DateTimePicker(Context context, long date) { - this(context, date, DateFormat.is24HourFormat(context)); + this(context, date, DateFormat.is24HourFormat(context));//把上一个函数的毫秒改成24小时制的日期格式 } public DateTimePicker(Context context, long date, boolean is24HourView) { - super(context); + super(context);//super是啥？？ mDate = Calendar.getInstance(); mInitialising = true; mIsAm = getCurrentHourOfDay() >= HOURS_IN_HALF_DAY; - inflate(context, R.layout.datetime_picker, this); + inflate(context, R.layout.datetime_picker, this);//inflate的作用？？ mDateSpinner = (NumberPicker) findViewById(R.id.date); mDateSpinner.setMinValue(DATE_SPINNER_MIN_VAL); @@ -188,14 +188,14 @@ public class DateTimePicker extends FrameLayout { mMinuteSpinner = (NumberPicker) findViewById(R.id.minute); mMinuteSpinner.setMinValue(MINUT_SPINNER_MIN_VAL); mMinuteSpinner.setMaxValue(MINUT_SPINNER_MAX_VAL); - mMinuteSpinner.setOnLongPressUpdateInterval(100); + mMinuteSpinner.setOnLongPressUpdateInterval(100);//？ mMinuteSpinner.setOnValueChangedListener(mOnMinuteChangedListener); String[] stringsForAmPm = new DateFormatSymbols().getAmPmStrings(); mAmPmSpinner = (NumberPicker) findViewById(R.id.amPm); mAmPmSpinner.setMinValue(AMPM_SPINNER_MIN_VAL); mAmPmSpinner.setMaxValue(AMPM_SPINNER_MAX_VAL); - mAmPmSpinner.setDisplayedValues(stringsForAmPm); + mAmPmSpinner.setDisplayedValues(stringsForAmPm);//设置展示的字符串 mAmPmSpinner.setOnValueChangedListener(mOnAmPmChangedListener); // update controls to initial state @@ -208,7 +208,7 @@ public class DateTimePicker extends FrameLayout { // set to current time setCurrentDate(date); - setEnabled(isEnabled()); + setEnabled(isEnabled());//? // set the content descriptions mInitialising = false; @@ -241,6 +241,7 @@ public class DateTimePicker extends FrameLayout { return mDate.getTimeInMillis(); } +//两种不同的参数，对应不同的设置现在时间的方法 /** * Set the current date * @@ -426,58 +427,87 @@ public class DateTimePicker extends FrameLayout { if (mIs24HourView == is24HourView) { return; } - mIs24HourView = is24HourView; + mIs24HourView = is24HourView; //spinner拉条 ，就是选am还是pm时候用的 mAmPmSpinner.setVisibility(is24HourView ? View.GONE : View.VISIBLE); int hour = getCurrentHourOfDay(); updateHourControl(); setCurrentHour(hour); updateAmPmControl(); } - + // + /** + * 更新日期选择控件的显示值 + * 生成当前日期前后一周的日期显示值，并设置到日期选择器中 + */ private void updateDateControl() { Calendar cal = Calendar.getInstance(); cal.setTimeInMillis(mDate.getTimeInMillis()); + // 计算起始日期：当前日期减去3天（DAYS_IN_ALL_WEEK/2=3）再减1天，得到一周前的日期 cal.add(Calendar.DAY_OF_YEAR, -DAYS_IN_ALL_WEEK / 2 - 1); mDateSpinner.setDisplayedValues(null); for (int i = 0; i < DAYS_IN_ALL_WEEK; ++i) { - cal.add(Calendar.DAY_OF_YEAR, 1); + // 每次循环增加一天，生成一周内的日期 + cal.add(Calendar.DAY_OF_YEAR, 1); + // 格式化日期为"MM.dd EEEE"格式（例如：05.20 星期一） mDateDisplayValues[i] = (String) DateFormat.format("MM.dd EEEE", cal); } + // 设置日期显示值到选择器 mDateSpinner.setDisplayedValues(mDateDisplayValues); + // 将选择器默认值设置为中间位置（即当前日期） mDateSpinner.setValue(DAYS_IN_ALL_WEEK / 2); + // 刷新选择器显示 mDateSpinner.invalidate(); } + /** + * 更新上午/下午选择控件的显示 + * 根据当前是否为24小时制，决定是否显示上午/下午选择器 + */ private void updateAmPmControl() { if (mIs24HourView) { + // 24小时制下，隐藏上午/下午选择器 mAmPmSpinner.setVisibility(View.GONE); } else { + // 12小时制下，根据当前是上午还是下午设置选择器值 int index = mIsAm ? Calendar.AM : Calendar.PM; mAmPmSpinner.setValue(index); + // 显示上午/下午选择器 mAmPmSpinner.setVisibility(View.VISIBLE); } } + /** + * 更新小时选择控件的显示范围 + * 根据当前是否为24小时制，设置不同的小时范围 + */ private void updateHourControl() { if (mIs24HourView) { + // 24小时制：小时范围0-23 mHourSpinner.setMinValue(HOUR_SPINNER_MIN_VAL_24_HOUR_VIEW); mHourSpinner.setMaxValue(HOUR_SPINNER_MAX_VAL_24_HOUR_VIEW); } else { + // 12小时制：小时范围1-12 mHourSpinner.setMinValue(HOUR_SPINNER_MIN_VAL_12_HOUR_VIEW); mHourSpinner.setMaxValue(HOUR_SPINNER_MAX_VAL_12_HOUR_VIEW); } } /** - * Set the callback that indicates the 'Set' button has been pressed. - * @param callback the callback, if null will do nothing + * 设置日期时间改变监听器 + * 当用户修改日期或时间时，会调用该监听器的回调方法 + * @param callback 监听器对象，null表示不设置监听器 */ public void setOnDateTimeChangedListener(OnDateTimeChangedListener callback) { mOnDateTimeChangedListener = callback; } + /** + * 日期时间改变时的回调方法 + * 当用户修改日期或时间时，调用该方法通知注册的监听器 + */ private void onDateTimeChanged() { if (mOnDateTimeChangedListener != null) { + // 调用监听器的onDateTimeChanged方法，传递当前选择的年、月、日、时、分 mOnDateTimeChangedListener.onDateTimeChanged(this, getCurrentYear(), getCurrentMonth(), getCurrentDay(), getCurrentHourOfDay(), getCurrentMinute()); } diff --git a/src/ui/DateTimePickerDialog.java b/src/ui/DateTimePickerDialog.java index 2c47ba4..f0d05ef 100644 --- a/src/ui/DateTimePickerDialog.java +++ b/src/ui/DateTimePickerDialog.java @@ -28,37 +28,39 @@ import android.content.DialogInterface; import android.content.DialogInterface.OnClickListener; import android.text.format.DateFormat; import android.text.format.DateUtils; - + //对话框弹出 public class DateTimePickerDialog extends AlertDialog implements OnClickListener { private Calendar mDate = Calendar.getInstance(); private boolean mIs24HourView; - private OnDateTimeSetListener mOnDateTimeSetListener; + private OnDateTimeSetListener mOnDateTimeSetListener; //设置时间的接口 private DateTimePicker mDateTimePicker; - public interface OnDateTimeSetListener { + public interface OnDateTimeSetListener {//实现接口的函数调用 void OnDateTimeSet(AlertDialog dialog, long date); } public DateTimePickerDialog(Context context, long date) { - super(context); + super(context);//访问AlertDialog的context mDateTimePicker = new DateTimePicker(context); - setView(mDateTimePicker); - mDateTimePicker.setOnDateTimeChangedListener(new OnDateTimeChangedListener() { + setView(mDateTimePicker);//自定义对话框 + mDateTimePicker.setOnDateTimeChangedListener(new OnDateTimeChangedListener() { //注册监听器，用户操作日期时间选择器时，这个监听器会被自动触发 public void onDateTimeChanged(DateTimePicker view, int year, int month, int dayOfMonth, int hourOfDay, int minute) { + //用户修改时，实时更新时间 mDate.set(Calendar.YEAR, year); mDate.set(Calendar.MONTH, month); mDate.set(Calendar.DAY_OF_MONTH, dayOfMonth); mDate.set(Calendar.HOUR_OF_DAY, hourOfDay); mDate.set(Calendar.MINUTE, minute); - updateTitle(mDate.getTimeInMillis()); + updateTitle(mDate.getTimeInMillis());//根据新的日期时间更新对话框标题 } }); - mDate.setTimeInMillis(date); - mDate.set(Calendar.SECOND, 0); - mDateTimePicker.setCurrentDate(mDate.getTimeInMillis()); - setButton(context.getString(R.string.datetime_dialog_ok), this); + //下面三行是日期时间选择器初始化的核心逻辑 + mDate.setTimeInMillis(date); //导入calendar时间 + mDate.set(Calendar.SECOND, 0);//秒数设为0 + mDateTimePicker.setCurrentDate(mDate.getTimeInMillis());//设置为当前时间 + setButton(context.getString(R.string.datetime_dialog_ok), this);//设置了确认和取消按钮 setButton2(context.getString(R.string.datetime_dialog_cancel), (OnClickListener)null); set24HourView(DateFormat.is24HourFormat(this.getContext())); updateTitle(mDate.getTimeInMillis()); @@ -68,20 +70,21 @@ public class DateTimePickerDialog extends AlertDialog implements OnClickListener mIs24HourView = is24HourView; } - public void setOnDateTimeSetListener(OnDateTimeSetListener callBack) { - mOnDateTimeSetListener = callBack; + public void setOnDateTimeSetListener(OnDateTimeSetListener callBack) { //设置时间的接口 + mOnDateTimeSetListener = callBack; } private void updateTitle(long date) { - int flag = + int flag = //亮点，位掩码设计 返回了结果是一个包含所有标志位的整数作为时间显示格式 DateUtils.FORMAT_SHOW_YEAR | DateUtils.FORMAT_SHOW_DATE | DateUtils.FORMAT_SHOW_TIME; - flag |= mIs24HourView ? DateUtils.FORMAT_24HOUR : DateUtils.FORMAT_24HOUR; - setTitle(DateUtils.formatDateTime(this.getContext(), date, flag)); - } - - public void onClick(DialogInterface arg0, int arg1) { + //再并上24小时格式或12小时格式 + flag |= mIs24HourView ? DateUtils.FORMAT_24HOUR : DateUtils.FORMAT_12HOUR; //错误应为12HOUR + setTitle(DateUtils.formatDateTime(this.getContext(), date, flag)); //设置对话框标题 + } //日期时间的本地化格式化 + + public void onClick(DialogInterface arg0, int arg1) {//点击确认按钮时调用 if (mOnDateTimeSetListener != null) { mOnDateTimeSetListener.OnDateTimeSet(this, mDate.getTimeInMillis()); } diff --git a/src/ui/DropdownMenu.java b/src/ui/DropdownMenu.java index 613dc74..33f6b96 100644 --- a/src/ui/DropdownMenu.java +++ b/src/ui/DropdownMenu.java @@ -29,33 +29,35 @@ import net.micode.notes.R; public class DropdownMenu { private Button mButton; - private PopupMenu mPopupMenu; + private PopupMenu mPopupMenu; //弹窗菜单 private Menu mMenu; public DropdownMenu(Context context, Button button, int menuId) { mButton = button; - mButton.setBackgroundResource(R.drawable.dropdown_icon); + mButton.setBackgroundResource(R.drawable.dropdown_icon);//绘制下拉菜单图标 mPopupMenu = new PopupMenu(context, mButton); - mMenu = mPopupMenu.getMenu(); - mPopupMenu.getMenuInflater().inflate(menuId, mMenu); - mButton.setOnClickListener(new OnClickListener() { + mMenu = mPopupMenu.getMenu();//获取弹窗菜单的菜单对象 + mPopupMenu.getMenuInflater().inflate(menuId, mMenu);//获得菜单 + //第一个参数用于指定我们通过哪一个资源文件来创建菜单，menuId。 + // 第二个参数用于指定我们的菜单项将添加到哪一个 Meau 对象中 + mButton.setOnClickListener(new OnClickListener() {//设置下拉菜单图标点击事件 public void onClick(View v) { mPopupMenu.show(); } }); } - public void setOnDropdownMenuItemClickListener(OnMenuItemClickListener listener) { + public void setOnDropdownMenuItemClickListener(OnMenuItemClickListener listener) {//设置下拉菜单选项点击事件监听 if (mPopupMenu != null) { mPopupMenu.setOnMenuItemClickListener(listener); } } - public MenuItem findItem(int id) { + public MenuItem findItem(int id) {//根据菜单项的ID查找菜单项 return mMenu.findItem(id); } - public void setTitle(CharSequence title) { + public void setTitle(CharSequence title) {//设置下拉菜单图标上的文本 mButton.setText(title); } } diff --git a/src/ui/FoldersListAdapter.java b/src/ui/FoldersListAdapter.java index 96b77da..3384004 100644 --- a/src/ui/FoldersListAdapter.java +++ b/src/ui/FoldersListAdapter.java @@ -28,8 +28,8 @@ import net.micode.notes.R; import net.micode.notes.data.Notes; import net.micode.notes.data.Notes.NoteColumns; - -public class FoldersListAdapter extends CursorAdapter { + //将cursor对象数据加载到界面的适配器 +public class FoldersListAdapter extends CursorAdapter {//将文件夹数据转换成视图 public static final String [] PROJECTION = { NoteColumns.ID, NoteColumns.SNIPPET @@ -39,41 +39,43 @@ public class FoldersListAdapter extends CursorAdapter { public static final int NAME_COLUMN = 1; public FoldersListAdapter(Context context, Cursor c) { - super(context, c); + super(context, c);//调用父类构造方法，初始化上下文和游标 // TODO Auto-generated constructor stub } @Override - public View newView(Context context, Cursor cursor, ViewGroup parent) { - return new FolderListItem(context); + public View newView(Context context, Cursor cursor, ViewGroup parent) {//创建新的视图 + return new FolderListItem(context);//创建一个新的FolderListItem视图 } @Override - public void bindView(View view, Context context, Cursor cursor) { - if (view instanceof FolderListItem) { + public void bindView(View view, Context context, Cursor cursor) {//绑定视图与数据 + if (view instanceof FolderListItem) {//判断视图是否为FolderListItem类型 + //根据文件夹类型动态显示不同的名称，当文件夹是文件夹时，显示移动到父文件夹 + //当文件夹是 普通文件夹时，显示其实际名称 String folderName = (cursor.getLong(ID_COLUMN) == Notes.ID_ROOT_FOLDER) ? context .getString(R.string.menu_move_parent_folder) : cursor.getString(NAME_COLUMN); - ((FolderListItem) view).bind(folderName); + ((FolderListItem) view).bind(folderName);//将文件夹名称绑定到FolderListItem视图 } } - public String getFolderName(Context context, int position) { + public String getFolderName(Context context, int position) {//根据位置找到对应文件夹的名称 Cursor cursor = (Cursor) getItem(position); return (cursor.getLong(ID_COLUMN) == Notes.ID_ROOT_FOLDER) ? context .getString(R.string.menu_move_parent_folder) : cursor.getString(NAME_COLUMN); } - - private class FolderListItem extends LinearLayout { + //布局管理器 之一，属于 ViewGroup 的子类，用于 将子View按照线性方向排列 + private class FolderListItem extends LinearLayout {//文件夹列表项视图 private TextView mName; - public FolderListItem(Context context) { super(context); - inflate(context, R.layout.folder_list_item, this); - mName = (TextView) findViewById(R.id.tv_folder_name); + inflate(context, R.layout.folder_list_item, this);//对 LayoutInflater.inflate()的简化 + //将R.layout.folder_list_item布局文件实例化并添加到当前视图（FolderListItem）中 + mName = (TextView) findViewById(R.id.tv_folder_name);//获取布局文件中的TextView控件 } public void bind(String name) { - mName.setText(name); + mName.setText(name);//将文件夹名称设置到TextView中 } } diff --git a/src/ui/NoteEditActivity.java b/src/ui/NoteEditActivity.java index 96a9ff8..3ce63a7 100644 --- a/src/ui/NoteEditActivity.java +++ b/src/ui/NoteEditActivity.java @@ -74,17 +74,17 @@ import java.util.regex.Pattern; public class NoteEditActivity extends Activity implements OnClickListener, NoteSettingChangedListener, OnTextViewChangeListener { - private class HeadViewHolder { - public TextView tvModified; + private class HeadViewHolder {//头视图持有者类？？？ + public TextView tvModified;//文本修改 - public ImageView ivAlertIcon; + public ImageView ivAlertIcon;//图像提醒按钮？ - public TextView tvAlertDate; + public TextView tvAlertDate;//文本提醒日期？ - public ImageView ibSetBgColor; + public ImageView ibSetBgColor;//设置背景颜色图像视图 } - private static final Map sBgSelectorBtnsMap = new HashMap(); + private static final Map sBgSelectorBtnsMap = new HashMap();//背景颜色选择按钮映射 static { sBgSelectorBtnsMap.put(R.id.iv_bg_yellow, ResourceParser.YELLOW); sBgSelectorBtnsMap.put(R.id.iv_bg_red, ResourceParser.RED); @@ -92,7 +92,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, sBgSelectorBtnsMap.put(R.id.iv_bg_green, ResourceParser.GREEN); sBgSelectorBtnsMap.put(R.id.iv_bg_white, ResourceParser.WHITE); } - + //上下是反的为啥？构建双向印射关系，方便根据颜色值获取对应的选择按钮ID（比如当前背景是红的，红的按钮就是按下去的），或者根据选择按钮ID获取对应的颜色值 private static final Map sBgSelectorSelectionMap = new HashMap(); static { sBgSelectorSelectionMap.put(ResourceParser.YELLOW, R.id.iv_bg_yellow_select); @@ -102,14 +102,14 @@ public class NoteEditActivity extends Activity implements OnClickListener, sBgSelectorSelectionMap.put(ResourceParser.WHITE, R.id.iv_bg_white_select); } - private static final Map sFontSizeBtnsMap = new HashMap(); + private static final Map sFontSizeBtnsMap = new HashMap();//字体大小选择按钮映射 static { sFontSizeBtnsMap.put(R.id.ll_font_large, ResourceParser.TEXT_LARGE); sFontSizeBtnsMap.put(R.id.ll_font_small, ResourceParser.TEXT_SMALL); sFontSizeBtnsMap.put(R.id.ll_font_normal, ResourceParser.TEXT_MEDIUM); sFontSizeBtnsMap.put(R.id.ll_font_super, ResourceParser.TEXT_SUPER); } - +//同颜色的映射关系 private static final Map sFontSelectorSelectionMap = new HashMap(); static { sFontSelectorSelectionMap.put(ResourceParser.TEXT_LARGE, R.id.iv_large_select); @@ -150,7 +150,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, private Pattern mPattern; @Override - protected void onCreate(Bundle savedInstanceState) { + protected void onCreate(Bundle savedInstanceState) {//创建活动时调用 super.onCreate(savedInstanceState); this.setContentView(R.layout.note_edit); @@ -158,19 +158,19 @@ public class NoteEditActivity extends Activity implements OnClickListener, finish(); return; } - initResources(); + initResources();//初始化资源 } /** * Current activity may be killed when the memory is low. Once it is killed, for another time - * user load this activity, we should restore the former state + * user load this activity, we should restore the former state/ */ @Override - protected void onRestoreInstanceState(Bundle savedInstanceState) { - super.onRestoreInstanceState(savedInstanceState); + protected void onRestoreInstanceState(Bundle savedInstanceState) {//存储uid便于恢复活动状态时调用 + super.onRestoreInstanceState(savedInstanceState); //使用 Intent Extra 在组件之间传递uid if (savedInstanceState != null && savedInstanceState.containsKey(Intent.EXTRA_UID)) { - Intent intent = new Intent(Intent.ACTION_VIEW); - intent.putExtra(Intent.EXTRA_UID, savedInstanceState.getLong(Intent.EXTRA_UID)); + Intent intent = new Intent(Intent.ACTION_VIEW); //创建一个意图，用于显示笔记详情,大小是（action_view显示数据功能） + intent.putExtra(Intent.EXTRA_UID, savedInstanceState.getLong(Intent.EXTRA_UID));//将uid添加到意图中，用于之后再调出来 if (!initActivityState(intent)) { finish(); return; @@ -185,56 +185,56 @@ public class NoteEditActivity extends Activity implements OnClickListener, * then jump to the NotesListActivity */ mWorkingNote = null; - if (TextUtils.equals(Intent.ACTION_VIEW, intent.getAction())) { - long noteId = intent.getLongExtra(Intent.EXTRA_UID, 0); - mUserQuery = ""; + if (TextUtils.equals(Intent.ACTION_VIEW, intent.getAction())) {//如果意图是查看操作 + long noteId = intent.getLongExtra(Intent.EXTRA_UID, 0);//获取uid + mUserQuery = "";//初始化用户查询，用于后续搜索 /** * Starting from the searched result */ - if (intent.hasExtra(SearchManager.EXTRA_DATA_KEY)) { - noteId = Long.parseLong(intent.getStringExtra(SearchManager.EXTRA_DATA_KEY)); - mUserQuery = intent.getStringExtra(SearchManager.USER_QUERY); + if (intent.hasExtra(SearchManager.EXTRA_DATA_KEY)) {//如果意图包含搜索数据键 + noteId = Long.parseLong(intent.getStringExtra(SearchManager.EXTRA_DATA_KEY));//解析出笔记id + mUserQuery = intent.getStringExtra(SearchManager.USER_QUERY);//解析出用户查询 } - if (!DataUtils.visibleInNoteDatabase(getContentResolver(), noteId, Notes.TYPE_NOTE)) { + if (!DataUtils.visibleInNoteDatabase(getContentResolver(), noteId, Notes.TYPE_NOTE)) {//如果笔记数据库中不存在该笔记 Intent jump = new Intent(this, NotesListActivity.class); - startActivity(jump); - showToast(R.string.error_note_not_exist); + startActivity(jump);//执行跳转 + showToast(R.string.error_note_not_exist);//显示笔记不存在的提示 finish(); return false; } else { - mWorkingNote = WorkingNote.load(this, noteId); + mWorkingNote = WorkingNote.load(this, noteId);//加载笔记 if (mWorkingNote == null) { Log.e(TAG, "load note failed with note id" + noteId); finish(); return false; } } - getWindow().setSoftInputMode( - WindowManager.LayoutParams.SOFT_INPUT_STATE_HIDDEN - | WindowManager.LayoutParams.SOFT_INPUT_ADJUST_RESIZE); - } else if(TextUtils.equals(Intent.ACTION_INSERT_OR_EDIT, intent.getAction())) { + getWindow().setSoftInputMode( //控制软键盘的操作？ + WindowManager.LayoutParams.SOFT_INPUT_STATE_HIDDEN //隐藏 + | WindowManager.LayoutParams.SOFT_INPUT_ADJUST_RESIZE);//调整布局 + } else if(TextUtils.equals(Intent.ACTION_INSERT_OR_EDIT, intent.getAction())) {//如果意图是插入或编辑操作 // New note - long folderId = intent.getLongExtra(Notes.INTENT_EXTRA_FOLDER_ID, 0); + long folderId = intent.getLongExtra(Notes.INTENT_EXTRA_FOLDER_ID, 0);//获取文件夹id int widgetId = intent.getIntExtra(Notes.INTENT_EXTRA_WIDGET_ID, - AppWidgetManager.INVALID_APPWIDGET_ID); + AppWidgetManager.INVALID_APPWIDGET_ID);//获取小部件id int widgetType = intent.getIntExtra(Notes.INTENT_EXTRA_WIDGET_TYPE, - Notes.TYPE_WIDGET_INVALIDE); + Notes.TYPE_WIDGET_INVALIDE);//获取小部件类型 int bgResId = intent.getIntExtra(Notes.INTENT_EXTRA_BACKGROUND_ID, - ResourceParser.getDefaultBgId(this)); + ResourceParser.getDefaultBgId(this));//获取背景资源id // Parse call-record note - String phoneNumber = intent.getStringExtra(Intent.EXTRA_PHONE_NUMBER); - long callDate = intent.getLongExtra(Notes.INTENT_EXTRA_CALL_DATE, 0); - if (callDate != 0 && phoneNumber != null) { + String phoneNumber = intent.getStringExtra(Intent.EXTRA_PHONE_NUMBER);//获取电话号码 + long callDate = intent.getLongExtra(Notes.INTENT_EXTRA_CALL_DATE, 0);//获取调用日期 + if (callDate != 0 && phoneNumber != null) {//如果调用日期和电话号码都不为空 if (TextUtils.isEmpty(phoneNumber)) { Log.w(TAG, "The call record number is null"); } - long noteId = 0; + long noteId = 0;//初始化笔记id if ((noteId = DataUtils.getNoteIdByPhoneNumberAndCallDate(getContentResolver(), - phoneNumber, callDate)) > 0) { - mWorkingNote = WorkingNote.load(this, noteId); + phoneNumber, callDate)) > 0) {//如果记录中根据电话号码和调用日期查询到笔记id + mWorkingNote = WorkingNote.load(this, noteId);//加载笔记 if (mWorkingNote == null) { Log.e(TAG, "load call note failed with note id" + noteId); finish(); @@ -242,15 +242,15 @@ public class NoteEditActivity extends Activity implements OnClickListener, } } else { mWorkingNote = WorkingNote.createEmptyNote(this, folderId, widgetId, - widgetType, bgResId); - mWorkingNote.convertToCallNote(phoneNumber, callDate); + widgetType, bgResId);//新建笔记 + mWorkingNote.convertToCallNote(phoneNumber, callDate);//将笔记转换为call笔记 } } else { mWorkingNote = WorkingNote.createEmptyNote(this, folderId, widgetId, widgetType, - bgResId); + bgResId);//新建笔记 } - getWindow().setSoftInputMode( + getWindow().setSoftInputMode(//设置软键盘操作 WindowManager.LayoutParams.SOFT_INPUT_ADJUST_RESIZE | WindowManager.LayoutParams.SOFT_INPUT_STATE_VISIBLE); } else { @@ -258,32 +258,32 @@ public class NoteEditActivity extends Activity implements OnClickListener, finish(); return false; } - mWorkingNote.setOnSettingStatusChangedListener(this); + mWorkingNote.setOnSettingStatusChangedListener(this);//设置笔记设置状态改变监听器 return true; } @Override - protected void onResume() { + protected void onResume() {//已经oncreate后切出，再次调用时，初始化笔记界面 super.onResume(); initNoteScreen(); } private void initNoteScreen() { mNoteEditor.setTextAppearance(this, TextAppearanceResources - .getTexAppearanceResource(mFontSizeId)); - if (mWorkingNote.getCheckListMode() == TextNote.MODE_CHECK_LIST) { - switchToListMode(mWorkingNote.getContent()); + .getTexAppearanceResource(mFontSizeId));//设置文本字体外观资源 + if (mWorkingNote.getCheckListMode() == TextNote.MODE_CHECK_LIST) {//根据笔记模式（ 清单模式 或 普通模式 ）初始化编辑器内容 + switchToListMode(mWorkingNote.getContent());//切换到列表清单模式 } else { - mNoteEditor.setText(getHighlightQueryResult(mWorkingNote.getContent(), mUserQuery)); - mNoteEditor.setSelection(mNoteEditor.getText().length()); + mNoteEditor.setText(getHighlightQueryResult(mWorkingNote.getContent(), mUserQuery));//设置文本内容为高亮查询结果 + mNoteEditor.setSelection(mNoteEditor.getText().length());//将光标定位到文本末尾，方便用户继续编辑 } - for (Integer id : sBgSelectorSelectionMap.keySet()) { + for (Integer id : sBgSelectorSelectionMap.keySet()) {//隐藏所有背景色选择器的 选中状态指示器 findViewById(sBgSelectorSelectionMap.get(id)).setVisibility(View.GONE); } - mHeadViewPanel.setBackgroundResource(mWorkingNote.getTitleBgResId()); - mNoteEditorPanel.setBackgroundResource(mWorkingNote.getBgColorResId()); + mHeadViewPanel.setBackgroundResource(mWorkingNote.getTitleBgResId());//设置笔记标题界面的 背景资源 + mNoteEditorPanel.setBackgroundResource(mWorkingNote.getBgColorResId());设置笔记编辑区界面的 背景资源 - mNoteHeaderHolder.tvModified.setText(DateUtils.formatDateTime(this, + mNoteHeaderHolder.tvModified.setText(DateUtils.formatDateTime(this, //显示笔记的 最后修改日期 ，并格式化显示 mWorkingNote.getModifiedDate(), DateUtils.FORMAT_SHOW_DATE | DateUtils.FORMAT_NUMERIC_DATE | DateUtils.FORMAT_SHOW_TIME | DateUtils.FORMAT_SHOW_YEAR)); @@ -295,14 +295,14 @@ public class NoteEditActivity extends Activity implements OnClickListener, showAlertHeader(); } - private void showAlertHeader() { + private void showAlertHeader() {//显示笔记的 闹钟提醒 信息 if (mWorkingNote.hasClockAlert()) { long time = System.currentTimeMillis(); if (time > mWorkingNote.getAlertDate()) { - mNoteHeaderHolder.tvAlertDate.setText(R.string.note_alert_expired); + mNoteHeaderHolder.tvAlertDate.setText(R.string.note_alert_expired);//显示已过期信息 } else { mNoteHeaderHolder.tvAlertDate.setText(DateUtils.getRelativeTimeSpanString( - mWorkingNote.getAlertDate(), time, DateUtils.MINUTE_IN_MILLIS)); + mWorkingNote.getAlertDate(), time, DateUtils.MINUTE_IN_MILLIS));//显示剩余时间信息 } mNoteHeaderHolder.tvAlertDate.setVisibility(View.VISIBLE); mNoteHeaderHolder.ivAlertIcon.setVisibility(View.VISIBLE); @@ -313,13 +313,13 @@ public class NoteEditActivity extends Activity implements OnClickListener, } @Override - protected void onNewIntent(Intent intent) { + protected void onNewIntent(Intent intent) {//处理新的intent super.onNewIntent(intent); initActivityState(intent); } @Override - protected void onSaveInstanceState(Bundle outState) { + protected void onSaveInstanceState(Bundle outState) {//保存活动状态 super.onSaveInstanceState(outState); /** * For new note without note id, we should firstly save it to @@ -334,23 +334,23 @@ public class NoteEditActivity extends Activity implements OnClickListener, } @Override - public boolean dispatchTouchEvent(MotionEvent ev) { + public boolean dispatchTouchEvent(MotionEvent ev) {//处理触摸事件 if (mNoteBgColorSelector.getVisibility() == View.VISIBLE - && !inRangeOfView(mNoteBgColorSelector, ev)) { - mNoteBgColorSelector.setVisibility(View.GONE); + && !inRangeOfView(mNoteBgColorSelector, ev)) {//如果背景色选择器可见，且触摸事件不在范围内？ + mNoteBgColorSelector.setVisibility(View.GONE);//隐藏背景色选择器 return true; } if (mFontSizeSelector.getVisibility() == View.VISIBLE - && !inRangeOfView(mFontSizeSelector, ev)) { - mFontSizeSelector.setVisibility(View.GONE); + && !inRangeOfView(mFontSizeSelector, ev)) {//如果字体大小选择器可见，且触摸事件不在范围内？ + mFontSizeSelector.setVisibility(View.GONE);//隐藏字体大小选择器 return true; } - return super.dispatchTouchEvent(ev); + return super.dispatchTouchEvent(ev);//将事件传递给父类处理 } - private boolean inRangeOfView(View view, MotionEvent ev) { - int []location = new int[2]; + private boolean inRangeOfView(View view, MotionEvent ev) {//判断触摸事件是否在视图范围内 + int []location = new int[2];//获取视图在屏幕上的坐标，长度为2的整数数组 view.getLocationOnScreen(location); int x = location[0]; int y = location[1]; @@ -363,7 +363,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, return true; } - private void initResources() { + private void initResources() {//初始化资源 mHeadViewPanel = findViewById(R.id.note_title); mNoteHeaderHolder = new HeadViewHolder(); mNoteHeaderHolder.tvModified = (TextView) findViewById(R.id.tv_modified_date); @@ -398,16 +398,16 @@ public class NoteEditActivity extends Activity implements OnClickListener, } @Override - protected void onPause() { - super.onPause(); + protected void onPause() {//在活动暂停时调用（切出去了） + super.onPause();//调用父类的onPause方法 if(saveNote()) { Log.d(TAG, "Note data was saved with length:" + mWorkingNote.getContent().length()); } - clearSettingState(); + clearSettingState();//清除设置状态 } - private void updateWidget() { - Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_UPDATE); + private void updateWidget() {//更新应用小部件 + Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_UPDATE);//接受意图 if (mWorkingNote.getWidgetType() == Notes.TYPE_WIDGET_2X) { intent.setClass(this, NoteWidgetProvider_2x.class); } else if (mWorkingNote.getWidgetType() == Notes.TYPE_WIDGET_4X) { @@ -417,30 +417,31 @@ public class NoteEditActivity extends Activity implements OnClickListener, return; } - intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_IDS, new int[] { + intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_IDS, new int[] {//添加应用小部件id mWorkingNote.getWidgetId() }); - sendBroadcast(intent); - setResult(RESULT_OK, intent); + sendBroadcast(intent);//发送广播更新应用小部件 + setResult(RESULT_OK, intent);//设置结果为成功，返回意图 } - public void onClick(View v) { + public void onClick(View v) {//点击事件处理，语法细节没看 int id = v.getId(); - if (id == R.id.btn_set_bg_color) { + if (id == R.id.btn_set_bg_color) {//如果点击的是设置背景颜色按钮 mNoteBgColorSelector.setVisibility(View.VISIBLE); findViewById(sBgSelectorSelectionMap.get(mWorkingNote.getBgColorId())).setVisibility( - View.VISIBLE); - } else if (sBgSelectorBtnsMap.containsKey(id)) { + } else if (sBgSelectorBtnsMap.containsKey(id)) {//如果点击的是背景颜色选择按钮 findViewById(sBgSelectorSelectionMap.get(mWorkingNote.getBgColorId())).setVisibility( View.GONE); mWorkingNote.setBgColorId(sBgSelectorBtnsMap.get(id)); mNoteBgColorSelector.setVisibility(View.GONE); - } else if (sFontSizeBtnsMap.containsKey(id)) { + } else if (sFontSizeBtnsMap.containsKey(id)) {//如果点击的是字体大小选择按钮 findViewById(sFontSelectorSelectionMap.get(mFontSizeId)).setVisibility(View.GONE); mFontSizeId = sFontSizeBtnsMap.get(id); mSharedPrefs.edit().putInt(PREFERENCE_FONT_SIZE, mFontSizeId).commit(); findViewById(sFontSelectorSelectionMap.get(mFontSizeId)).setVisibility(View.VISIBLE); + //区分两种模式，列表模式和普通模式 if (mWorkingNote.getCheckListMode() == TextNote.MODE_CHECK_LIST) { getWorkingText(); switchToListMode(mWorkingNote.getContent()); @@ -453,17 +454,17 @@ public class NoteEditActivity extends Activity implements OnClickListener, } @Override - public void onBackPressed() { + public void onBackPressed() {//返回键处理 if(clearSettingState()) { return; } - saveNote(); + saveNote();//保存笔记 super.onBackPressed(); } - private boolean clearSettingState() { - if (mNoteBgColorSelector.getVisibility() == View.VISIBLE) { + private boolean clearSettingState() {//清除设置状态 + if (mNoteBgColorSelector.getVisibility() == View.VISIBLE) {// mNoteBgColorSelector.setVisibility(View.GONE); return true; } else if (mFontSizeSelector.getVisibility() == View.VISIBLE) { @@ -473,29 +474,29 @@ public class NoteEditActivity extends Activity implements OnClickListener, return false; } - public void onBackgroundColorChanged() { + public void onBackgroundColorChanged() {// findViewById(sBgSelectorSelectionMap.get(mWorkingNote.getBgColorId())).setVisibility( - View.VISIBLE); - mNoteEditorPanel.setBackgroundResource(mWorkingNote.getBgColorResId()); - mHeadViewPanel.setBackgroundResource(mWorkingNote.getTitleBgResId()); + View.VISIBLE);//显示选中的背景颜色 + mNoteEditorPanel.setBackgroundResource(mWorkingNote.getBgColorResId());//设置笔记编辑面板的背景颜色 + mHeadViewPanel.setBackgroundResource(mWorkingNote.getTitleBgResId());//设置标题栏的背景颜色 } @Override - public boolean onPrepareOptionsMenu(Menu menu) { + public boolean onPrepareOptionsMenu(Menu menu) {//准备选项菜单 if (isFinishing()) { return true; } clearSettingState(); menu.clear(); - if (mWorkingNote.getFolderId() == Notes.ID_CALL_RECORD_FOLDER) { - getMenuInflater().inflate(R.menu.call_note_edit, menu); + if (mWorkingNote.getFolderId() == Notes.ID_CALL_RECORD_FOLDER) {//判断类型 + getMenuInflater().inflate(R.menu.call_note_edit, menu);//如果是通话记录文件夹， 通话记录转化为菜单 } else { getMenuInflater().inflate(R.menu.note_edit, menu); } if (mWorkingNote.getCheckListMode() == TextNote.MODE_CHECK_LIST) { - menu.findItem(R.id.menu_list_mode).setTitle(R.string.menu_normal_mode); + menu.findItem(R.id.menu_list_mode).setTitle(R.string.menu_normal_mode);//如果是列表模式， 菜单标题为普通模式 } else { - menu.findItem(R.id.menu_list_mode).setTitle(R.string.menu_list_mode); + menu.findItem(R.id.menu_list_mode).setTitle(R.string.menu_list_mode);//如果不是列表模式， 菜单标题为列表模式 } if (mWorkingNote.hasClockAlert()) { menu.findItem(R.id.menu_alert).setVisible(false); @@ -506,13 +507,13 @@ public class NoteEditActivity extends Activity implements OnClickListener, } @Override - public boolean onOptionsItemSelected(MenuItem item) { + public boolean onOptionsItemSelected(MenuItem item) {//处理选项菜单点击事件 switch (item.getItemId()) { - case R.id.menu_new_note: + case R.id.menu_new_note://新建笔记 createNewNote(); break; - case R.id.menu_delete: - AlertDialog.Builder builder = new AlertDialog.Builder(this); + case R.id.menu_delete://删除笔记 + AlertDialog.Builder builder = new AlertDialog.Builder(this);//创建删除确认对话框 builder.setTitle(getString(R.string.alert_title_delete)); builder.setIcon(android.R.drawable.ic_dialog_alert); builder.setMessage(getString(R.string.alert_message_delete_note)); @@ -526,25 +527,25 @@ public class NoteEditActivity extends Activity implements OnClickListener, builder.setNegativeButton(android.R.string.cancel, null); builder.show(); break; - case R.id.menu_font_size: + case R.id.menu_font_size://字体大小选择 mFontSizeSelector.setVisibility(View.VISIBLE); findViewById(sFontSelectorSelectionMap.get(mFontSizeId)).setVisibility(View.VISIBLE); break; - case R.id.menu_list_mode: + case R.id.menu_list_mode://列表模式切换 mWorkingNote.setCheckListMode(mWorkingNote.getCheckListMode() == 0 ? TextNote.MODE_CHECK_LIST : 0); break; - case R.id.menu_share: + case R.id.menu_share://分享笔记 getWorkingText(); sendTo(this, mWorkingNote.getContent()); break; - case R.id.menu_send_to_desktop: + case R.id.menu_send_to_desktop://发送到桌面 sendToDesktop(); break; - case R.id.menu_alert: + case R.id.menu_alert://设置提醒 setReminder(); break; - case R.id.menu_delete_remind: + case R.id.menu_delete_remind://删除提醒 mWorkingNote.setAlertDate(0, false); break; default: @@ -552,7 +553,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, } return true; } - +//下面是上文相关函数的具体实现 private void setReminder() { DateTimePickerDialog d = new DateTimePickerDialog(this, System.currentTimeMillis()); d.setOnDateTimeSetListener(new OnDateTimeSetListener() { @@ -569,7 +570,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, */ private void sendTo(Context context, String info) { Intent intent = new Intent(Intent.ACTION_SEND); - intent.putExtra(Intent.EXTRA_TEXT, info); + intent.putExtra(Intent.EXTRA_TEXT, info);//再intetn中添加标签为EXTRA_TEXT， 值为info intent.setType("text/plain"); context.startActivity(intent); } @@ -590,17 +591,17 @@ public class NoteEditActivity extends Activity implements OnClickListener, if (mWorkingNote.existInDatabase()) { HashSet ids = new HashSet(); long id = mWorkingNote.getNoteId(); - if (id != Notes.ID_ROOT_FOLDER) { - ids.add(id); + if (id != Notes.ID_ROOT_FOLDER) {//如果不是根文件夹 + ids.add(id);//将笔记id添加到集合中 } else { Log.d(TAG, "Wrong note id, should not happen"); } - if (!isSyncMode()) { - if (!DataUtils.batchDeleteNotes(getContentResolver(), ids)) { + if (!isSyncMode()) {//如果不是同步模式 + if (!DataUtils.batchDeleteNotes(getContentResolver(), ids)) {//批量删除笔记 Log.e(TAG, "Delete Note error"); } } else { - if (!DataUtils.batchMoveToFolder(getContentResolver(), ids, Notes.ID_TRASH_FOLER)) { + if (!DataUtils.batchMoveToFolder(getContentResolver(), ids, Notes.ID_TRASH_FOLER)) {//将笔记移动到回收站文件夹 Log.e(TAG, "Move notes to trash folder error, should not happens"); } } @@ -612,7 +613,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, return NotesPreferenceActivity.getSyncAccountName(this).trim().length() > 0; } - public void onClockAlertChanged(long date, boolean set) { + public void onClockAlertChanged(long date, boolean set) {//设置提醒时间 /** * User could set clock to an unsaved note, so before setting the * alert clock, we should save the note first @@ -646,33 +647,34 @@ public class NoteEditActivity extends Activity implements OnClickListener, updateWidget(); } - public void onEditTextDelete(int index, String text) { - int childCount = mEditTextList.getChildCount(); + public void onEditTextDelete(int index, String text) {//处理清单模式下删除列表项 的操作 + int childCount = mEditTextList.getChildCount();//获取编辑框的子视图数量 if (childCount == 1) { return; } - for (int i = index + 1; i < childCount; i++) { + for (int i = index + 1; i < childCount; i++) {//遍历删除项（index处）之后的所有列表项 ，将它们的索引减1，不会影响到后续的列表项的索引，从而避免了索引错乱的问题 ((NoteEditText) mEditTextList.getChildAt(i).findViewById(R.id.et_edit_text)) .setIndex(i - 1); } - mEditTextList.removeViewAt(index); + mEditTextList.removeViewAt(index);//删除index处的子图 + //亮点：小米笔记清单模式下的特殊设计 ，属于防误删的安全机制 ，主要为了保护用户内容，这是啥意思？ NoteEditText edit = null; if(index == 0) { edit = (NoteEditText) mEditTextList.getChildAt(0).findViewById( R.id.et_edit_text); } else { edit = (NoteEditText) mEditTextList.getChildAt(index - 1).findViewById( - R.id.et_edit_text); + R.id.et_edit_text);// } - int length = edit.length(); - edit.append(text); - edit.requestFocus(); - edit.setSelection(length); + int length = edit.length();//获取删除项（index处）之前的列表项的文本长度 + edit.append(text);//将被删除项的文本追加到目标项末尾 + edit.requestFocus();//将焦点自动切换到目标项 + edit.setSelection(length);//将光标定位到合并前的文本末尾 } - public void onEditTextEnter(int index, String text) { + public void onEditTextEnter(int index, String text) {//处理清单模式下添加列表项的操作 /** * Should not happen, check for debug */ @@ -681,40 +683,40 @@ public class NoteEditActivity extends Activity implements OnClickListener, } View view = getListItem(text, index); - mEditTextList.addView(view, index); - NoteEditText edit = (NoteEditText) view.findViewById(R.id.et_edit_text); + mEditTextList.addView(view, index);//将新的列表项视图添加到编辑框中，位置为index + NoteEditText edit = (NoteEditText) view.findViewById(R.id.et_edit_text);//获取新添加的列表项的编辑框 edit.requestFocus(); - edit.setSelection(0); - for (int i = index + 1; i < mEditTextList.getChildCount(); i++) { + edit.setSelection(0);//将光标定位到新添加的列表项的文本开头 + for (int i = index + 1; i < mEditTextList.getChildCount(); i++) {//索引加一 ((NoteEditText) mEditTextList.getChildAt(i).findViewById(R.id.et_edit_text)) .setIndex(i); } } - private void switchToListMode(String text) { + private void switchToListMode(String text) {//将编辑框切换到清单模式 mEditTextList.removeAllViews(); String[] items = text.split("\n"); int index = 0; for (String item : items) { if(!TextUtils.isEmpty(item)) { - mEditTextList.addView(getListItem(item, index)); + mEditTextList.addView(getListItem(item, index));//将新的列表项视图添加到编辑框中，位置为index index++; } } - mEditTextList.addView(getListItem("", index)); - mEditTextList.getChildAt(index).findViewById(R.id.et_edit_text).requestFocus(); + mEditTextList.addView(getListItem("", index));//添加一个空列表项 + mEditTextList.getChildAt(index).findViewById(R.id.et_edit_text).requestFocus();//将焦点自动切换到新添加的空列表项的编辑框 - mNoteEditor.setVisibility(View.GONE); + mNoteEditor.setVisibility(View.GONE);//隐藏编辑框 mEditTextList.setVisibility(View.VISIBLE); } - private Spannable getHighlightQueryResult(String fullText, String userQuery) { - SpannableString spannable = new SpannableString(fullText == null ? "" : fullText); - if (!TextUtils.isEmpty(userQuery)) { - mPattern = Pattern.compile(userQuery); - Matcher m = mPattern.matcher(fullText); + private Spannable getHighlightQueryResult(String fullText, String userQuery) {//高亮显示用户查询的文本，这里用了spannable，是比较好的视图管理器 + SpannableString spannable = new SpannableString(fullText == null ? "" : fullText);//存储高亮显示的文本 + if (!TextUtils.isEmpty(userQuery)) { + mPattern = Pattern.compile(userQuery, Pattern.CASE_INSENSITIVE);//编译正则表达式 + Matcher m = mPattern.matcher(fullText);//创建一个 Matcher 对象，用于对输入字符串进行匹配操作 int start = 0; - while (m.find(start)) { + while (m.find(start)) { //构建span字符串 spannable.setSpan( new BackgroundColorSpan(this.getResources().getColor( R.color.user_query_highlight)), m.start(), m.end(), @@ -725,28 +727,28 @@ public class NoteEditActivity extends Activity implements OnClickListener, return spannable; } - private View getListItem(String item, int index) { + private View getListItem(String item, int index) { //获取清单模式下的列表项视图 View view = LayoutInflater.from(this).inflate(R.layout.note_edit_list_item, null); - final NoteEditText edit = (NoteEditText) view.findViewById(R.id.et_edit_text); + final NoteEditText edit = (NoteEditText) view.findViewById(R.id.et_edit_text);//获取列表项的编辑框 edit.setTextAppearance(this, TextAppearanceResources.getTexAppearanceResource(mFontSizeId)); - CheckBox cb = ((CheckBox) view.findViewById(R.id.cb_edit_item)); - cb.setOnCheckedChangeListener(new OnCheckedChangeListener() { - public void onCheckedChanged(CompoundButton buttonView, boolean isChecked) { - if (isChecked) { - edit.setPaintFlags(edit.getPaintFlags() | Paint.STRIKE_THRU_TEXT_FLAG); + CheckBox cb = ((CheckBox) view.findViewById(R.id.cb_edit_item)); //复选框用于让用户从有限数量的选项中选择一个或多个选项。 + cb.setOnCheckedChangeListener(new OnCheckedChangeListener() {//复选框变化监听 + public void onCheckedChanged(CompoundButton buttonView, boolean isChecked) {// + if (isChecked) {//PaintFlags是Android中用于控制文本绘制样式的位掩码 ，通过位运算组合多个绘制标志 + edit.setPaintFlags(edit.getPaintFlags() | Paint.STRIKE_THRU_TEXT_FLAG);//添加删除线效果 } else { - edit.setPaintFlags(Paint.ANTI_ALIAS_FLAG | Paint.DEV_KERN_TEXT_FLAG); + edit.setPaintFlags(Paint.ANTI_ALIAS_FLAG | Paint.DEV_KERN_TEXT_FLAG);//清除删除线效果 } } }); - if (item.startsWith(TAG_CHECKED)) { + if (item.startsWith(TAG_CHECKED)) {//如果列表项以(TAG_CHECKED)开头，则将复选框设置为选中状态 cb.setChecked(true); - edit.setPaintFlags(edit.getPaintFlags() | Paint.STRIKE_THRU_TEXT_FLAG); - item = item.substring(TAG_CHECKED.length(), item.length()).trim(); + edit.setPaintFlags(edit.getPaintFlags() | Paint.STRIKE_THRU_TEXT_FLAG);// + item = item.substring(TAG_CHECKED.length(), item.length()).trim();// } else if (item.startsWith(TAG_UNCHECKED)) { cb.setChecked(false); - edit.setPaintFlags(Paint.ANTI_ALIAS_FLAG | Paint.DEV_KERN_TEXT_FLAG); + edit.setPaintFlags(Paint.ANTI_ALIAS_FLAG | Paint.DEV_KERN_TEXT_FLAG);// item = item.substring(TAG_UNCHECKED.length(), item.length()).trim(); } @@ -756,25 +758,25 @@ public class NoteEditActivity extends Activity implements OnClickListener, return view; } - public void onTextChange(int index, boolean hasText) { - if (index >= mEditTextList.getChildCount()) { + public void onTextChange(int index, boolean hasText) {// 列表项文本变化事件 + if (index >= mEditTextList.getChildCount()) {//检查索引是否超出范围 Log.e(TAG, "Wrong index, should not happen"); return; } - if(hasText) { + if(hasText) {//如果列表项有文本 mEditTextList.getChildAt(index).findViewById(R.id.cb_edit_item).setVisibility(View.VISIBLE); } else { mEditTextList.getChildAt(index).findViewById(R.id.cb_edit_item).setVisibility(View.GONE); } } - public void onCheckListModeChanged(int oldMode, int newMode) { - if (newMode == TextNote.MODE_CHECK_LIST) { + public void onCheckListModeChanged(int oldMode, int newMode) {// 检查列表模式变化事件 + if (newMode == TextNote.MODE_CHECK_LIST) {//如果切换到检查列表模式 switchToListMode(mNoteEditor.getText().toString()); } else { if (!getWorkingText()) { mWorkingNote.setWorkingText(mWorkingNote.getContent().replace(TAG_UNCHECKED + " ", - "")); + ""));//如果没有选中项，则将所有未选中项的文本删除 } mNoteEditor.setText(getHighlightQueryResult(mWorkingNote.getContent(), mUserQuery)); mEditTextList.setVisibility(View.GONE); @@ -782,19 +784,19 @@ public class NoteEditActivity extends Activity implements OnClickListener, } } - private boolean getWorkingText() { + private boolean getWorkingText() {//获取选中项的文本 boolean hasChecked = false; - if (mWorkingNote.getCheckListMode() == TextNote.MODE_CHECK_LIST) { + if (mWorkingNote.getCheckListMode() == TextNote.MODE_CHECK_LIST) {//如果是检查列表模式 StringBuilder sb = new StringBuilder(); - for (int i = 0; i < mEditTextList.getChildCount(); i++) { + for (int i = 0; i < mEditTextList.getChildCount(); i++) {//遍历所有列表项 View view = mEditTextList.getChildAt(i); NoteEditText edit = (NoteEditText) view.findViewById(R.id.et_edit_text); if (!TextUtils.isEmpty(edit.getText())) { if (((CheckBox) view.findViewById(R.id.cb_edit_item)).isChecked()) { - sb.append(TAG_CHECKED).append(" ").append(edit.getText()).append("\n"); + sb.append(TAG_CHECKED).append(" ").append(edit.getText()).append("\n");//如果列表项选中，则将其文本添加到 StringBuilder 中 hasChecked = true; } else { - sb.append(TAG_UNCHECKED).append(" ").append(edit.getText()).append("\n"); + sb.append(TAG_UNCHECKED).append(" ").append(edit.getText()).append("\n");//如果列表项未选中，则将其文本添加到 StringBuilder 中 } } } @@ -805,7 +807,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, return hasChecked; } - private boolean saveNote() { + private boolean saveNote() {//保存笔记 getWorkingText(); boolean saved = mWorkingNote.saveNote(); if (saved) { @@ -821,29 +823,29 @@ public class NoteEditActivity extends Activity implements OnClickListener, return saved; } - private void sendToDesktop() { + private void sendToDesktop() {//将笔记发送到桌面 /** * Before send message to home, we should make sure that current * editing note is exists in databases. So, for new note, firstly * save it */ - if (!mWorkingNote.existInDatabase()) { + if (!mWorkingNote.existInDatabase()) {//如果笔记不存在于数据库中 saveNote(); } - if (mWorkingNote.getNoteId() > 0) { + if (mWorkingNote.getNoteId() > 0) {//如果笔记存在于数据库中 Intent sender = new Intent(); Intent shortcutIntent = new Intent(this, NoteEditActivity.class); - shortcutIntent.setAction(Intent.ACTION_VIEW); + shortcutIntent.setAction(Intent.ACTION_VIEW);//设置意图操作行为为查看 shortcutIntent.putExtra(Intent.EXTRA_UID, mWorkingNote.getNoteId()); - sender.putExtra(Intent.EXTRA_SHORTCUT_INTENT, shortcutIntent); + sender.putExtra(Intent.EXTRA_SHORTCUT_INTENT, shortcutIntent);//将意图添加到发送者意图中 sender.putExtra(Intent.EXTRA_SHORTCUT_NAME, - makeShortcutIconTitle(mWorkingNote.getContent())); + makeShortcutIconTitle(mWorkingNote.getContent()));//将快捷图标标题添加到发送者意图中 sender.putExtra(Intent.EXTRA_SHORTCUT_ICON_RESOURCE, Intent.ShortcutIconResource.fromContext(this, R.drawable.icon_app)); - sender.putExtra("duplicate", true); - sender.setAction("com.android.launcher.action.INSTALL_SHORTCUT"); - showToast(R.string.info_note_enter_desktop); + sender.putExtra("duplicate", true);//将重复项添加到发送者意图中 + sender.setAction("com.android.launcher.action.INSTALL_SHORTCUT");//设置意图操作行为为安装快捷图标 + showToast(R.string.info_note_enter_desktop);//显示提示消息（成功） sendBroadcast(sender); } else { /** @@ -856,18 +858,18 @@ public class NoteEditActivity extends Activity implements OnClickListener, } } - private String makeShortcutIconTitle(String content) { + private String makeShortcutIconTitle(String content) {//创建快捷图标标题 content = content.replace(TAG_CHECKED, ""); content = content.replace(TAG_UNCHECKED, ""); return content.length() > SHORTCUT_ICON_TITLE_MAX_LEN ? content.substring(0, SHORTCUT_ICON_TITLE_MAX_LEN) : content; } - private void showToast(int resId) { - showToast(resId, Toast.LENGTH_SHORT); + private void showToast(int resId) {//显示短时间的提示消息 + showToast(resId, Toast.LENGTH_SHORT);// } - private void showToast(int resId, int duration) { + private void showToast(int resId, int duration) {//显示自定义时间长度的 Toast 消息 Toast.makeText(this, resId, duration).show(); } } diff --git a/src/ui/NoteEditText.java b/src/ui/NoteEditText.java index 2afe2a8..e0fe20a 100644 --- a/src/ui/NoteEditText.java +++ b/src/ui/NoteEditText.java @@ -37,73 +37,111 @@ import net.micode.notes.R; import java.util.HashMap; import java.util.Map; +/** + * 小米笔记的自定义文本编辑组件，扩展了Android原生EditText的功能 + * 支持特殊的按键处理、链接识别和动态添加/删除编辑框 + */ public class NoteEditText extends EditText { - private static final String TAG = "NoteEditText"; - private int mIndex; - private int mSelectionStartBeforeDelete; + private static final String TAG = "NoteEditText"; // 日志标签 + private int mIndex; // 当前编辑框在容器中的索引位置 + private int mSelectionStartBeforeDelete; // 删除操作前的光标起始位置 - private static final String SCHEME_TEL = "tel:" ; - private static final String SCHEME_HTTP = "http:" ; - private static final String SCHEME_EMAIL = "mailto:" ; + // 支持的链接协议常量 + private static final String SCHEME_TEL = "tel:" ; // 电话协议 + private static final String SCHEME_HTTP = "http:" ; // HTTP协议 + private static final String SCHEME_EMAIL = "mailto:" ; // 邮件协议 + // 协议到字符串资源的映射表，用于上下文菜单显示 private static final Map sSchemaActionResMap = new HashMap(); static { - sSchemaActionResMap.put(SCHEME_TEL, R.string.note_link_tel); - sSchemaActionResMap.put(SCHEME_HTTP, R.string.note_link_web); - sSchemaActionResMap.put(SCHEME_EMAIL, R.string.note_link_email); + sSchemaActionResMap.put(SCHEME_TEL, R.string.note_link_tel); // 电话链接菜单 + sSchemaActionResMap.put(SCHEME_HTTP, R.string.note_link_web); // 网页链接菜单 + sSchemaActionResMap.put(SCHEME_EMAIL, R.string.note_link_email); // 邮件链接菜单 } /** - * Call by the {@link NoteEditActivity} to delete or add edit text + * 与NoteEditActivity通信的监听器接口，用于处理编辑框的动态添加和删除 */ public interface OnTextViewChangeListener { /** - * Delete current edit text when {@link KeyEvent#KEYCODE_DEL} happens - * and the text is null + * 当按下删除键且文本为空时，删除当前编辑框 + * @param index 当前编辑框的索引 + * @param text 当前编辑框的文本内容 */ void onEditTextDelete(int index, String text); /** - * Add edit text after current edit text when {@link KeyEvent#KEYCODE_ENTER} - * happen + * 当按下回车键时，在当前编辑框后添加新的编辑框 + * @param index 新编辑框的索引位置 + * @param text 新编辑框的初始文本内容 */ void onEditTextEnter(int index, String text); /** - * Hide or show item option when text change + * 当文本内容变化时，通知外部显示或隐藏选项 + * @param index 当前编辑框的索引 + * @param hasText 是否包含文本 */ void onTextChange(int index, boolean hasText); } - private OnTextViewChangeListener mOnTextViewChangeListener; + private OnTextViewChangeListener mOnTextViewChangeListener; // 文本变化监听器实例 + /** + * 构造函数，创建NoteEditText实例 + * @param context 上下文对象 + */ public NoteEditText(Context context) { super(context, null); mIndex = 0; } + /** + * 设置当前编辑框在容器中的索引位置 + * @param index 索引值 + */ public void setIndex(int index) { mIndex = index; } + /** + * 设置文本变化监听器，用于与NoteEditActivity通信 + * @param listener 监听器实例 + */ public void setOnTextViewChangeListener(OnTextViewChangeListener listener) { mOnTextViewChangeListener = listener; } + /** + * 构造函数，从XML布局创建NoteEditText实例 + * @param context 上下文对象 + * @param attrs XML属性集合 + */ public NoteEditText(Context context, AttributeSet attrs) { super(context, attrs, android.R.attr.editTextStyle); } + /** + * 构造函数，从XML布局创建NoteEditText实例，支持自定义样式 + * @param context 上下文对象 + * @param attrs XML属性集合 + * @param defStyle 自定义样式 + */ public NoteEditText(Context context, AttributeSet attrs, int defStyle) { super(context, attrs, defStyle); // TODO Auto-generated constructor stub } + /** + * 重写触摸事件处理，实现精确的文本选择 + * @param event 触摸事件对象 + * @return 事件处理结果 + */ @Override public boolean onTouchEvent(MotionEvent event) { switch (event.getAction()) { case MotionEvent.ACTION_DOWN: - + // 计算触摸点在文本中的精确位置 int x = (int) event.getX(); int y = (int) event.getY(); x -= getTotalPaddingLeft(); @@ -114,22 +152,30 @@ public class NoteEditText extends EditText { Layout layout = getLayout(); int line = layout.getLineForVertical(y); int off = layout.getOffsetForHorizontal(line, x); - Selection.setSelection(getText(), off); + Selection.setSelection(getText(), off); // 设置光标位置 break; } return super.onTouchEvent(event); } + /** + * 重写按键按下事件处理 + * @param keyCode 按键码 + * @param event 按键事件对象 + * @return 事件处理结果 + */ @Override public boolean onKeyDown(int keyCode, KeyEvent event) { switch (keyCode) { case KeyEvent.KEYCODE_ENTER: + // 回车键按下时，交由onKeyUp处理 if (mOnTextViewChangeListener != null) { return false; } break; case KeyEvent.KEYCODE_DEL: + // 记录删除前的光标位置 mSelectionStartBeforeDelete = getSelectionStart(); break; default: @@ -138,10 +184,17 @@ public class NoteEditText extends EditText { return super.onKeyDown(keyCode, event); } + /** + * 重写按键释放事件处理，实现特殊的删除和回车功能 + * @param keyCode 按键码 + * @param event 按键事件对象 + * @return 事件处理结果 + */ @Override public boolean onKeyUp(int keyCode, KeyEvent event) { switch(keyCode) { case KeyEvent.KEYCODE_DEL: + // 删除键处理：当光标在开头且非第一个编辑框时，删除当前编辑框 if (mOnTextViewChangeListener != null) { if (0 == mSelectionStartBeforeDelete && mIndex != 0) { mOnTextViewChangeListener.onEditTextDelete(mIndex, getText().toString()); @@ -152,10 +205,14 @@ public class NoteEditText extends EditText { } break; case KeyEvent.KEYCODE_ENTER: + // 回车键处理：在当前位置分割文本，创建新的编辑框 if (mOnTextViewChangeListener != null) { int selectionStart = getSelectionStart(); + // 获取光标后的文本 String text = getText().subSequence(selectionStart, length()).toString(); + // 保留光标前的文本 setText(getText().subSequence(0, selectionStart)); + // 通知Activity添加新的编辑框 mOnTextViewChangeListener.onEditTextEnter(mIndex + 1, text); } else { Log.d(TAG, "OnTextViewChangeListener was not seted"); @@ -167,9 +224,16 @@ public class NoteEditText extends EditText { return super.onKeyUp(keyCode, event); } + /** + * 重写焦点变化事件处理 + * @param focused 是否获得焦点 + * @param direction 焦点移动方向 + * @param previouslyFocusedRect 之前焦点所在的矩形区域 + */ @Override protected void onFocusChanged(boolean focused, int direction, Rect previouslyFocusedRect) { if (mOnTextViewChangeListener != null) { + // 失去焦点且文本为空时，通知Activity隐藏相关选项 if (!focused && TextUtils.isEmpty(getText())) { mOnTextViewChangeListener.onTextChange(mIndex, false); } else { @@ -179,6 +243,10 @@ public class NoteEditText extends EditText { super.onFocusChanged(focused, direction, previouslyFocusedRect); } + /** + * 创建上下文菜单，支持链接点击操作 + * @param menu 上下文菜单对象 + */ @Override protected void onCreateContextMenu(ContextMenu menu) { if (getText() instanceof Spanned) { @@ -188,8 +256,10 @@ public class NoteEditText extends EditText { int min = Math.min(selStart, selEnd); int max = Math.max(selStart, selEnd); + // 查找选中区域内的URLSpan final URLSpan[] urls = ((Spanned) getText()).getSpans(min, max, URLSpan.class); if (urls.length == 1) { + // 根据链接协议选择合适的菜单文本 int defaultResId = 0; for(String schema: sSchemaActionResMap.keySet()) { if(urls[0].getURL().indexOf(schema) >= 0) { @@ -202,10 +272,11 @@ public class NoteEditText extends EditText { defaultResId = R.string.note_link_other; } + // 添加菜单选项并设置点击监听器 menu.add(0, 0, 0, defaultResId).setOnMenuItemClickListener( new OnMenuItemClickListener() { public boolean onMenuItemClick(MenuItem item) { - // goto a new intent + // 执行链接点击操作 urls[0].onClick(NoteEditText.this); return true; } diff --git a/src/ui/NoteItemData.java b/src/ui/NoteItemData.java index 0f5a878..7021ee6 100644 --- a/src/ui/NoteItemData.java +++ b/src/ui/NoteItemData.java @@ -26,57 +26,76 @@ import net.micode.notes.data.Notes.NoteColumns; import net.micode.notes.tool.DataUtils; +/** + * 笔记列表项的数据模型类，负责从数据库Cursor中读取数据并封装成Java对象 + * 包含笔记的基本属性、通话记录信息和列表位置状态 + */ public class NoteItemData { + /** + * 数据库查询的列投影，定义需要从数据库读取的字段 + */ static final String [] PROJECTION = new String [] { - NoteColumns.ID, - NoteColumns.ALERTED_DATE, - NoteColumns.BG_COLOR_ID, - NoteColumns.CREATED_DATE, - NoteColumns.HAS_ATTACHMENT, - NoteColumns.MODIFIED_DATE, - NoteColumns.NOTES_COUNT, - NoteColumns.PARENT_ID, - NoteColumns.SNIPPET, - NoteColumns.TYPE, - NoteColumns.WIDGET_ID, - NoteColumns.WIDGET_TYPE, + NoteColumns.ID, // 笔记ID + NoteColumns.ALERTED_DATE, // 提醒日期 + NoteColumns.BG_COLOR_ID, // 背景颜色ID + NoteColumns.CREATED_DATE, // 创建日期 + NoteColumns.HAS_ATTACHMENT, // 是否有附件 + NoteColumns.MODIFIED_DATE, // 修改日期 + NoteColumns.NOTES_COUNT, // 文件夹包含的笔记数量 + NoteColumns.PARENT_ID, // 父文件夹ID + NoteColumns.SNIPPET, // 笔记内容摘要 + NoteColumns.TYPE, // 笔记类型 + NoteColumns.WIDGET_ID, // 关联的小部件ID + NoteColumns.WIDGET_TYPE, // 小部件类型 }; - private static final int ID_COLUMN = 0; - private static final int ALERTED_DATE_COLUMN = 1; - private static final int BG_COLOR_ID_COLUMN = 2; - private static final int CREATED_DATE_COLUMN = 3; - private static final int HAS_ATTACHMENT_COLUMN = 4; - private static final int MODIFIED_DATE_COLUMN = 5; - private static final int NOTES_COUNT_COLUMN = 6; - private static final int PARENT_ID_COLUMN = 7; - private static final int SNIPPET_COLUMN = 8; - private static final int TYPE_COLUMN = 9; - private static final int WIDGET_ID_COLUMN = 10; - private static final int WIDGET_TYPE_COLUMN = 11; - - private long mId; - private long mAlertDate; - private int mBgColorId; - private long mCreatedDate; - private boolean mHasAttachment; - private long mModifiedDate; - private int mNotesCount; - private long mParentId; - private String mSnippet; - private int mType; - private int mWidgetId; - private int mWidgetType; - private String mName; - private String mPhoneNumber; - - private boolean mIsLastItem; - private boolean mIsFirstItem; - private boolean mIsOnlyOneItem; - private boolean mIsOneNoteFollowingFolder; - private boolean mIsMultiNotesFollowingFolder; - + /** + * 投影数组的列索引常量，用于从Cursor中快速获取对应字段 + */ + private static final int ID_COLUMN = 0; // 笔记ID + private static final int ALERTED_DATE_COLUMN = 1; // 提醒日期 + private static final int BG_COLOR_ID_COLUMN = 2; // 背景颜色ID + private static final int CREATED_DATE_COLUMN = 3; // 创建日期 + private static final int HAS_ATTACHMENT_COLUMN = 4; // 是否有附件 + private static final int MODIFIED_DATE_COLUMN = 5; // 修改日期 + private static final int NOTES_COUNT_COLUMN = 6; // 文件夹包含的笔记数量 + private static final int PARENT_ID_COLUMN = 7; // 父文件夹ID + private static final int SNIPPET_COLUMN = 8; // 笔记内容摘要 + private static final int TYPE_COLUMN = 9; // 笔记类型 + private static final int WIDGET_ID_COLUMN = 10; // 小部件ID + private static final int WIDGET_TYPE_COLUMN = 11; // 小部件类型 + + // 笔记基本属性 + private long mId; // 笔记唯一标识符 + private long mAlertDate; // 提醒日期时间 + private int mBgColorId; // 背景颜色ID + private long mCreatedDate; // 创建日期时间 + private boolean mHasAttachment; // 是否包含附件 + private long mModifiedDate; // 最后修改日期时间 + private int mNotesCount; // 文件夹包含的笔记数量 + private long mParentId; // 所属父文件夹ID + private String mSnippet; // 笔记内容摘要 + private int mType; // 笔记类型（普通笔记/文件夹/系统文件夹） + private int mWidgetId; // 关联的小部件ID + private int mWidgetType; // 小部件类型 + + // 通话记录相关属性 + private String mName; // 通话记录联系人姓名 + private String mPhoneNumber; // 通话记录电话号码 + + // 列表位置状态 + private boolean mIsLastItem; // 是否为列表最后一项 + private boolean mIsFirstItem; // 是否为列表第一项 + private boolean mIsOnlyOneItem; // 是否为列表唯一一项 + private boolean mIsOneNoteFollowingFolder; // 是否是文件夹下的唯一笔记 + private boolean mIsMultiNotesFollowingFolder; // 是否是文件夹下的多个笔记之一 + + /** + * 构造函数，从Cursor中读取数据并初始化成员变量 + * @param cursor 包含笔记数据的Cursor + */ public NoteItemData(Context context, Cursor cursor) { + // 读取基本笔记属性 mId = cursor.getLong(ID_COLUMN); mAlertDate = cursor.getLong(ALERTED_DATE_COLUMN); mBgColorId = cursor.getInt(BG_COLOR_ID_COLUMN); @@ -87,18 +106,21 @@ public class NoteItemData { mParentId = cursor.getLong(PARENT_ID_COLUMN); mSnippet = cursor.getString(SNIPPET_COLUMN); mSnippet = mSnippet.replace(NoteEditActivity.TAG_CHECKED, "").replace( - NoteEditActivity.TAG_UNCHECKED, ""); + NoteEditActivity.TAG_UNCHECKED, "");// 清除清单模式的标签标记 mType = cursor.getInt(TYPE_COLUMN); mWidgetId = cursor.getInt(WIDGET_ID_COLUMN); mWidgetType = cursor.getInt(WIDGET_TYPE_COLUMN); + // 处理通话记录相关属性 mPhoneNumber = ""; if (mParentId == Notes.ID_CALL_RECORD_FOLDER) { + // 获取通话记录的电话号码 mPhoneNumber = DataUtils.getCallNumberByNoteId(context.getContentResolver(), mId); if (!TextUtils.isEmpty(mPhoneNumber)) { + // 获取联系人姓名 mName = Contact.getContact(context, mPhoneNumber); if (mName == null) { - mName = mPhoneNumber; + mName = mPhoneNumber; // 无联系人时显示电话号码 } } } @@ -106,27 +128,37 @@ public class NoteItemData { if (mName == null) { mName = ""; } + // 检查并设置当前项在列表中的位置关系 checkPostion(cursor); } + /** + * 检查当前项在列表中的位置关系，并设置相应的状态标志 + */ private void checkPostion(Cursor cursor) { + // 检查基本位置状态 mIsLastItem = cursor.isLast() ? true : false; mIsFirstItem = cursor.isFirst() ? true : false; mIsOnlyOneItem = (cursor.getCount() == 1); mIsMultiNotesFollowingFolder = false; mIsOneNoteFollowingFolder = false; + // 检查是否跟随在文件夹之后 if (mType == Notes.TYPE_NOTE && !mIsFirstItem) { int position = cursor.getPosition(); + // 移动到前一项检查 if (cursor.moveToPrevious()) { + // 如果前一项是文件夹或系统文件夹 if (cursor.getInt(TYPE_COLUMN) == Notes.TYPE_FOLDER || cursor.getInt(TYPE_COLUMN) == Notes.TYPE_SYSTEM) { + // 检查后续是否还有更多笔记 if (cursor.getCount() > (position + 1)) { - mIsMultiNotesFollowingFolder = true; + mIsMultiNotesFollowingFolder = true; // 文件夹后有多个笔记 } else { - mIsOneNoteFollowingFolder = true; + mIsOneNoteFollowingFolder = true; // 文件夹后只有一个笔记 } } + // 恢复到原位置 if (!cursor.moveToNext()) { throw new IllegalStateException("cursor move to previous but can't move back"); } @@ -134,90 +166,179 @@ public class NoteItemData { } } + /** + * 是否是文件夹下的唯一笔记 + * @return true如果是文件夹下的唯一笔记，否则false + */ public boolean isOneFollowingFolder() { return mIsOneNoteFollowingFolder; } + /** + * 是否是文件夹下的多个笔记之一 + * @return true如果是文件夹下的多个笔记之一，否则false + */ public boolean isMultiFollowingFolder() { return mIsMultiNotesFollowingFolder; } + /** + * 是否为列表最后一项 + * @return true如果是最后一项，否则false + */ public boolean isLast() { return mIsLastItem; } + /** + * 获取通话记录联系人姓名 + * @return 联系人姓名，无联系人时返回电话号码 + */ public String getCallName() { return mName; } + /** + * 是否为列表第一项 + * @return true如果是第一项，否则false + */ public boolean isFirst() { return mIsFirstItem; } + /** + * 是否为列表唯一一项 + * @return true如果是唯一一项，否则false + */ public boolean isSingle() { return mIsOnlyOneItem; } + /** + * 获取笔记ID + * @return 笔记唯一标识符 + */ public long getId() { return mId; } + /** + * 获取提醒日期 + * @return 提醒日期时间戳（毫秒） + */ public long getAlertDate() { return mAlertDate; } + /** + * 获取创建日期 + * @return 创建日期时间戳（毫秒） + */ public long getCreatedDate() { return mCreatedDate; } + /** + * 是否包含附件 + * @return true如果包含附件，否则false + */ public boolean hasAttachment() { return mHasAttachment; } + /** + * 获取最后修改日期 + * @return 最后修改日期时间戳（毫秒） + */ public long getModifiedDate() { return mModifiedDate; } + /** + * 获取背景颜色ID + * @return 背景颜色ID + */ public int getBgColorId() { return mBgColorId; } + /** + * 获取父文件夹ID + * @return 所属父文件夹ID + */ public long getParentId() { return mParentId; } + /** + * 获取文件夹包含的笔记数量 + * @return 笔记数量 + */ public int getNotesCount() { return mNotesCount; } + /** + * 获取文件夹ID（与getParentId()相同） + * @return 文件夹ID + */ public long getFolderId () { return mParentId; } + /** + * 获取笔记类型 + * @return 笔记类型（普通笔记/文件夹/系统文件夹） + */ public int getType() { return mType; } + /** + * 获取小部件类型 + * @return 小部件类型 + */ public int getWidgetType() { return mWidgetType; } + /** + * 获取关联的小部件ID + * @return 小部件ID + */ public int getWidgetId() { return mWidgetId; } + /** + * 获取笔记内容摘要 + * @return 内容摘要 + */ public String getSnippet() { return mSnippet; } + /** + * 是否设置了提醒 + * @return true如果设置了提醒，否则false + */ public boolean hasAlert() { return (mAlertDate > 0); } + /** + * 是否为通话记录 + * @return true如果是通话记录，否则false + */ public boolean isCallRecord() { return (mParentId == Notes.ID_CALL_RECORD_FOLDER && !TextUtils.isEmpty(mPhoneNumber)); } + /** + * 静态方法：从Cursor中直接获取笔记类型 + * @param cursor 包含笔记数据的Cursor + * @return 笔记类型 + */ public static int getNoteType(Cursor cursor) { return cursor.getInt(TYPE_COLUMN); } diff --git a/src/ui/NotesListActivity.java b/src/ui/NotesListActivity.java index e843aec..42bac1d 100644 --- a/src/ui/NotesListActivity.java +++ b/src/ui/NotesListActivity.java @@ -78,65 +78,72 @@ import java.io.InputStream; import java.io.InputStreamReader; import java.util.HashSet; +/** + * 小米笔记的主界面类，负责管理笔记列表、文件夹、搜索和批量操作 + * 实现了笔记的创建、编辑、删除、移动等核心功能 + */ public class NotesListActivity extends Activity implements OnClickListener, OnItemLongClickListener { - private static final int FOLDER_NOTE_LIST_QUERY_TOKEN = 0; - - private static final int FOLDER_LIST_QUERY_TOKEN = 1; - - private static final int MENU_FOLDER_DELETE = 0; - - private static final int MENU_FOLDER_VIEW = 1; - - private static final int MENU_FOLDER_CHANGE_NAME = 2; - + /** + * 异步查询的Token常量，用于区分不同类型的查询请求 + */ + private static final int FOLDER_NOTE_LIST_QUERY_TOKEN = 0; // 查询文件夹下的笔记列表 + private static final int FOLDER_LIST_QUERY_TOKEN = 1; // 查询文件夹列表 + + /** + * 文件夹上下文菜单的菜单项ID + */ + private static final int MENU_FOLDER_DELETE = 0; // 删除文件夹 + private static final int MENU_FOLDER_VIEW = 1; // 查看文件夹内容 + private static final int MENU_FOLDER_CHANGE_NAME = 2; // 重命名文件夹 + + /** + * SharedPreferences键名，用于标记是否显示过添加笔记的介绍 + */ private static final String PREFERENCE_ADD_INTRODUCTION = "net.micode.notes.introduction"; + /** + * 列表编辑状态枚举，用于管理不同的列表视图状态 + */ private enum ListEditState { - NOTE_LIST, SUB_FOLDER, CALL_RECORD_FOLDER + NOTE_LIST, // 根目录笔记列表 + SUB_FOLDER, // 子文件夹笔记列表 + CALL_RECORD_FOLDER // 通话记录文件夹列表 }; - private ListEditState mState; - - private BackgroundQueryHandler mBackgroundQueryHandler; - - private NotesListAdapter mNotesListAdapter; - - private ListView mNotesListView; - - private Button mAddNewNote; - - private boolean mDispatch; - - private int mOriginY; - - private int mDispatchY; - - private TextView mTitleBar; - - private long mCurrentFolderId; - - private ContentResolver mContentResolver; - - private ModeCallback mModeCallBack; - - private static final String TAG = "NotesListActivity"; - - public static final int NOTES_LISTVIEW_SCROLL_RATE = 30; - - private NoteItemData mFocusNoteDataItem; - - private static final String NORMAL_SELECTION = NoteColumns.PARENT_ID + "=?"; - + private ListEditState mState; // 当前列表状态 + private BackgroundQueryHandler mBackgroundQueryHandler; // 异步查询处理器，用于后台加载数据 + + private NotesListAdapter mNotesListAdapter; // 笔记列表适配器，负责数据与UI的绑定 + private ListView mNotesListView; // 显示笔记列表的ListView组件 + private Button mAddNewNote; // 添加新笔记按钮 + private boolean mDispatch; // 触摸事件分发标志 + private int mOriginY; // 触摸事件起始Y坐标 + private int mDispatchY; // 触摸事件分发Y坐标 + private TextView mTitleBar; // 标题栏视图 + private long mCurrentFolderId; // 当前文件夹ID + private ContentResolver mContentResolver; // 内容解析器，用于访问数据库 + private ModeCallback mModeCallBack; // 多选模式回调，处理批量操作 + private static final String TAG = "NotesListActivity"; // 日志标签 + public static final int NOTES_LISTVIEW_SCROLL_RATE = 30; // ListView滚动速率 + private NoteItemData mFocusNoteDataItem; // 当前聚焦的笔记数据项 + + /** + * 数据库查询条件 + */ + private static final String NORMAL_SELECTION = NoteColumns.PARENT_ID + "=?"; // 普通文件夹查询条件 private static final String ROOT_FOLDER_SELECTION = "(" + NoteColumns.TYPE + "<>" + Notes.TYPE_SYSTEM + " AND " + NoteColumns.PARENT_ID + "=?)" + " OR (" + NoteColumns.ID + "=" + Notes.ID_CALL_RECORD_FOLDER + " AND " - + NoteColumns.NOTES_COUNT + ">0)"; + + NoteColumns.NOTES_COUNT + ">0)"; // 根文件夹查询条件 - private final static int REQUEST_CODE_OPEN_NODE = 102; - private final static int REQUEST_CODE_NEW_NODE = 103; + /** + * startActivityForResult的请求码 + */ + private final static int REQUEST_CODE_OPEN_NODE = 102; // 打开笔记的请求码 + private final static int REQUEST_CODE_NEW_NODE = 103; // 新建笔记的请求码 @Override - protected void onCreate(Bundle savedInstanceState) { + protected void onCreate(Bundle savedInstanceState) {// 初始化活动，设置布局和资源 super.onCreate(savedInstanceState); setContentView(R.layout.note_list); initResources(); @@ -148,7 +155,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } @Override - protected void onActivityResult(int requestCode, int resultCode, Intent data) { + protected void onActivityResult(int requestCode, int resultCode, Intent data) {// 处理子活动返回结果 if (resultCode == RESULT_OK && (requestCode == REQUEST_CODE_OPEN_NODE || requestCode == REQUEST_CODE_NEW_NODE)) { mNotesListAdapter.changeCursor(null); @@ -157,20 +164,23 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } + /** + * 首次使用应用时插入介绍笔记 + */ private void setAppInfoFromRawRes() { - SharedPreferences sp = PreferenceManager.getDefaultSharedPreferences(this); - if (!sp.getBoolean(PREFERENCE_ADD_INTRODUCTION, false)) { + SharedPreferences sp = PreferenceManager.getDefaultSharedPreferences(this);// 亮点：SharedPreferences 是Android平台上一个轻量级的存储类，主要用于保存应用的一些常用配置。它通过键值对的形式将数据保存在XML文件中 + if (!sp.getBoolean(PREFERENCE_ADD_INTRODUCTION, false)) {// 检查是否已添加介绍笔记 StringBuilder sb = new StringBuilder(); InputStream in = null; try { in = getResources().openRawResource(R.raw.introduction); if (in != null) { - InputStreamReader isr = new InputStreamReader(in); - BufferedReader br = new BufferedReader(isr); + InputStreamReader isr = new InputStreamReader(in, "UTF-8");// 亮点：指定字符编码为UTF-8，确保能够正确读取包含特殊字符的文本文件 + BufferedReader br = new BufferedReader(isr);// 亮点：BufferedReader 是Java IO库中的一个字符流类，用于读取字符数据。它提供了缓冲区的功能，能够一次读取多个字符，提高了读取效率。 char [] buf = new char[1024]; int len = 0; while ((len = br.read(buf)) > 0) { - sb.append(buf, 0, len); + sb.append(buf, 0, len);//将读取到的字符数组buf中的0到len-1位置的字符添加到StringBuilder中 } } else { Log.e(TAG, "Read introduction file error"); @@ -203,12 +213,18 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } + /** + * 活动启动时执行，开始异步查询笔记列表 + */ @Override protected void onStart() { super.onStart(); startAsyncNotesListQuery(); } + /** + * 初始化资源和UI组件 + */ private void initResources() { mContentResolver = this.getContentResolver(); mBackgroundQueryHandler = new BackgroundQueryHandler(this.getContentResolver()); @@ -231,11 +247,23 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt mModeCallBack = new ModeCallback(); } + /** + * 多选模式回调类，处理批量操作和菜单项点击事件 + */ private class ModeCallback implements ListView.MultiChoiceModeListener, OnMenuItemClickListener { + /** 下拉菜单，用于显示选择操作选项 */ private DropdownMenu mDropDownMenu; + /** ActionMode实例，用于管理多选模式的生命周期 */ private ActionMode mActionMode; + /** 移动菜单项，用于批量移动笔记 */ private MenuItem mMoveMenu; + /** + * 创建多选模式时的初始化操作 + * @param mode ActionMode实例 + * @param menu 菜单对象 + * @return 是否成功创建多选模式 + */ public boolean onCreateActionMode(ActionMode mode, Menu menu) { getMenuInflater().inflate(R.menu.note_list_options, menu); menu.findItem(R.id.delete).setOnMenuItemClickListener(this); @@ -269,12 +297,12 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt return true; } - private void updateMenu() { + private void updateMenu() {// 更新下拉菜单显示的选中项数量 int selectedCount = mNotesListAdapter.getSelectedCount(); // Update dropdown menu String format = getResources().getString(R.string.menu_select_title, selectedCount); mDropDownMenu.setTitle(format); - MenuItem item = mDropDownMenu.findItem(R.id.action_select_all); + MenuItem item = mDropDownMenu.findItem(R.id.action_select_all);// 查找选择所有项的菜单项 if (item != null) { if (mNotesListAdapter.isAllSelected()) { item.setChecked(true); @@ -286,33 +314,33 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } - public boolean onPrepareActionMode(ActionMode mode, Menu menu) { + public boolean onPrepareActionMode(ActionMode mode, Menu menu) {// 准备多选模式时的操作 // TODO Auto-generated method stub return false; } - public boolean onActionItemClicked(ActionMode mode, MenuItem item) { + public boolean onActionItemClicked(ActionMode mode, MenuItem item) {// 处理下拉菜单项点击事件 // TODO Auto-generated method stub return false; } - public void onDestroyActionMode(ActionMode mode) { + public void onDestroyActionMode(ActionMode mode) {// 多选模式结束时的操作 mNotesListAdapter.setChoiceMode(false); mNotesListView.setLongClickable(true); mAddNewNote.setVisibility(View.VISIBLE); } - public void finishActionMode() { + public void finishActionMode() {// 结束多选模式 mActionMode.finish(); } public void onItemCheckedStateChanged(ActionMode mode, int position, long id, - boolean checked) { + boolean checked) {// 处理列表项选中状态改变事件，注意actionmode的生命周期 mNotesListAdapter.setCheckedItem(position, checked); updateMenu(); } - public boolean onMenuItemClick(MenuItem item) { + public boolean onMenuItemClick(MenuItem item) {// 处理下拉菜单项点击事件 if (mNotesListAdapter.getSelectedCount() == 0) { Toast.makeText(NotesListActivity.this, getString(R.string.menu_select_none), Toast.LENGTH_SHORT).show(); @@ -346,8 +374,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } - private class NewNoteOnTouchListener implements OnTouchListener { - + private class NewNoteOnTouchListener implements OnTouchListener {// 处理"新建笔记"按钮的触摸事件 public boolean onTouch(View v, MotionEvent event) { switch (event.getAction()) { case MotionEvent.ACTION_DOWN: { @@ -359,7 +386,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt /** * Minus TitleBar's height */ - if (mState == ListEditState.SUB_FOLDER) { + if (mState == ListEditState.SUB_FOLDER) {// 如果当前状态是子文件夹 eventY -= mTitleBar.getHeight(); start -= mTitleBar.getHeight(); } @@ -372,11 +399,11 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt * Notice that, if the background of the button changes, the formula should * also change. This is very bad, just for the UI designer's strong requirement. */ - if (event.getY() < (event.getX() * (-0.12) + 94)) { + if (event.getY() < (event.getX() * (-0.12) + 94)) {// 如果点击位置在"新建笔记"按钮的透明部分 View view = mNotesListView.getChildAt(mNotesListView.getChildCount() - 1 - - mNotesListView.getFooterViewsCount()); + - mNotesListView.getFooterViewsCount());// 获取列表项的底部视图 if (view != null && view.getBottom() > start - && (view.getTop() < (start + 94))) { + && (view.getTop() < (start + 94))) {// 如果点击位置在"新建笔记"按钮的透明部分且在列表项范围内 mOriginY = (int) event.getY(); mDispatchY = eventY; event.setLocation(event.getX(), mDispatchY); @@ -386,7 +413,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } break; } - case MotionEvent.ACTION_MOVE: { + case MotionEvent.ACTION_MOVE: {// 处理"新建笔记"按钮的移动事件 if (mDispatch) { mDispatchY += (int) event.getY() - mOriginY; event.setLocation(event.getX(), mDispatchY); @@ -394,7 +421,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } break; } - default: { + default: {// 处理"新建笔记"按钮的其他事件 if (mDispatch) { event.setLocation(event.getX(), mDispatchY); mDispatch = false; @@ -408,27 +435,44 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt }; + /** + * 启动异步查询笔记列表的方法 + * 根据当前文件夹ID构建查询条件，使用异步查询处理器加载数据 + */ private void startAsyncNotesListQuery() { String selection = (mCurrentFolderId == Notes.ID_ROOT_FOLDER) ? ROOT_FOLDER_SELECTION : NORMAL_SELECTION; mBackgroundQueryHandler.startQuery(FOLDER_NOTE_LIST_QUERY_TOKEN, null, Notes.CONTENT_NOTE_URI, NoteItemData.PROJECTION, selection, new String[] { String.valueOf(mCurrentFolderId) - }, NoteColumns.TYPE + " DESC," + NoteColumns.MODIFIED_DATE + " DESC"); + }, NoteColumns.TYPE + " DESC," + NoteColumns.MODIFIED_DATE + " DESC" );// 按类型和修改日期排序 } + /** + * 异步查询处理器，用于在后台执行数据库查询操作 + */ private final class BackgroundQueryHandler extends AsyncQueryHandler { + /** + * 构造函数 + * @param contentResolver 内容解析器，用于访问数据库 + */ public BackgroundQueryHandler(ContentResolver contentResolver) { super(contentResolver); } + /** + * 查询完成后的回调处理 + * @param token 查询标识，区分不同类型的查询 + * @param cookie 额外数据 + * @param cursor 查询结果游标 + */ @Override protected void onQueryComplete(int token, Object cookie, Cursor cursor) { switch (token) { - case FOLDER_NOTE_LIST_QUERY_TOKEN: + case FOLDER_NOTE_LIST_QUERY_TOKEN:// 查询笔记列表 mNotesListAdapter.changeCursor(cursor); break; - case FOLDER_LIST_QUERY_TOKEN: + case FOLDER_LIST_QUERY_TOKEN:// 查询文件夹列表 if (cursor != null && cursor.getCount() > 0) { showFolderListMenu(cursor); } else { @@ -441,7 +485,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } - private void showFolderListMenu(Cursor cursor) { + private void showFolderListMenu(Cursor cursor) {// 显示文件夹列表菜单 AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this); builder.setTitle(R.string.menu_title_select_folder); final FoldersListAdapter adapter = new FoldersListAdapter(this, cursor); @@ -462,14 +506,14 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt builder.show(); } - private void createNewNote() { + private void createNewNote() {// 创建新笔记 Intent intent = new Intent(this, NoteEditActivity.class); intent.setAction(Intent.ACTION_INSERT_OR_EDIT); intent.putExtra(Notes.INTENT_EXTRA_FOLDER_ID, mCurrentFolderId); this.startActivityForResult(intent, REQUEST_CODE_NEW_NODE); } - private void batchDelete() { + private void batchDelete() {// 批量删除笔记 new AsyncTask>() { protected HashSet doInBackground(Void... unused) { HashSet widgets = mNotesListAdapter.getSelectedWidget(); @@ -492,7 +536,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } @Override - protected void onPostExecute(HashSet widgets) { + protected void onPostExecute(HashSet widgets) {// 批量删除笔记完成后的回调处理 if (widgets != null) { for (AppWidgetAttribute widget : widgets) { if (widget.widgetId != AppWidgetManager.INVALID_APPWIDGET_ID @@ -506,7 +550,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt }.execute(); } - private void deleteFolder(long folderId) { + private void deleteFolder(long folderId) {// 删除文件夹 if (folderId == Notes.ID_ROOT_FOLDER) { Log.e(TAG, "Wrong folder id, should not happen " + folderId); return; @@ -533,14 +577,14 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } - private void openNode(NoteItemData data) { + private void openNode(NoteItemData data) {// 打开笔记 Intent intent = new Intent(this, NoteEditActivity.class); intent.setAction(Intent.ACTION_VIEW); intent.putExtra(Intent.EXTRA_UID, data.getId()); this.startActivityForResult(intent, REQUEST_CODE_OPEN_NODE); } - private void openFolder(NoteItemData data) { + private void openFolder(NoteItemData data) {// 打开文件夹 mCurrentFolderId = data.getId(); startAsyncNotesListQuery(); if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) { @@ -567,19 +611,19 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } - private void showSoftInput() { + private void showSoftInput() {// 显示软键盘 InputMethodManager inputMethodManager = (InputMethodManager) getSystemService(Context.INPUT_METHOD_SERVICE); if (inputMethodManager != null) { inputMethodManager.toggleSoftInput(InputMethodManager.SHOW_FORCED, 0); } } - private void hideSoftInput(View view) { + private void hideSoftInput(View view) {// 隐藏软键盘 InputMethodManager inputMethodManager = (InputMethodManager) getSystemService(Context.INPUT_METHOD_SERVICE); inputMethodManager.hideSoftInputFromWindow(view.getWindowToken(), 0); } - private void showCreateOrModifyFolderDialog(final boolean create) { + private void showCreateOrModifyFolderDialog(final boolean create) {// 显示创建或修改文件夹对话框 final AlertDialog.Builder builder = new AlertDialog.Builder(this); View view = LayoutInflater.from(this).inflate(R.layout.dialog_edit_text, null); final EditText etName = (EditText) view.findViewById(R.id.et_foler_name); @@ -606,7 +650,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt final Dialog dialog = builder.setView(view).show(); final Button positive = (Button)dialog.findViewById(android.R.id.button1); - positive.setOnClickListener(new OnClickListener() { + positive.setOnClickListener(new OnClickListener() {// 确认创建或修改文件夹 public void onClick(View v) { hideSoftInput(etName); String name = etName.getText().toString(); @@ -617,7 +661,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt return; } if (!create) { - if (!TextUtils.isEmpty(name)) { + if (!TextUtils.isEmpty(name)) {// 修改文件夹名称 ContentValues values = new ContentValues(); values.put(NoteColumns.SNIPPET, name); values.put(NoteColumns.TYPE, Notes.TYPE_FOLDER); @@ -627,7 +671,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt String.valueOf(mFocusNoteDataItem.getId()) }); } - } else if (!TextUtils.isEmpty(name)) { + } else if (!TextUtils.isEmpty(name)) {// 创建新文件夹 ContentValues values = new ContentValues(); values.put(NoteColumns.SNIPPET, name); values.put(NoteColumns.TYPE, Notes.TYPE_FOLDER); @@ -637,19 +681,19 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } }); - if (TextUtils.isEmpty(etName.getText())) { + if (TextUtils.isEmpty(etName.getText())) {// 输入框为空时禁用确认按钮 positive.setEnabled(false); } /** * When the name edit text is null, disable the positive button */ - etName.addTextChangedListener(new TextWatcher() { + etName.addTextChangedListener(new TextWatcher() {// 监听输入框文本变化 public void beforeTextChanged(CharSequence s, int start, int count, int after) { // TODO Auto-generated method stub } - public void onTextChanged(CharSequence s, int start, int before, int count) { + public void onTextChanged(CharSequence s, int start, int before, int count) {// 输入框文本变化时更新确认按钮状态 if (TextUtils.isEmpty(etName.getText())) { positive.setEnabled(false); } else { @@ -657,7 +701,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } - public void afterTextChanged(Editable s) { + public void afterTextChanged(Editable s) {// 输入框文本变化后更新确认按钮状态 // TODO Auto-generated method stub } @@ -665,22 +709,22 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } @Override - public void onBackPressed() { + public void onBackPressed() {// 处理返回键事件 switch (mState) { - case SUB_FOLDER: + case SUB_FOLDER:// 返回上一级文件夹 mCurrentFolderId = Notes.ID_ROOT_FOLDER; mState = ListEditState.NOTE_LIST; startAsyncNotesListQuery(); mTitleBar.setVisibility(View.GONE); break; - case CALL_RECORD_FOLDER: + case CALL_RECORD_FOLDER:// 返回上一级通话记录文件夹 mCurrentFolderId = Notes.ID_ROOT_FOLDER; mState = ListEditState.NOTE_LIST; mAddNewNote.setVisibility(View.VISIBLE); mTitleBar.setVisibility(View.GONE); startAsyncNotesListQuery(); break; - case NOTE_LIST: + case NOTE_LIST:// 返回主界面 super.onBackPressed(); break; default: @@ -688,7 +732,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } - private void updateWidget(int appWidgetId, int appWidgetType) { + private void updateWidget(int appWidgetId, int appWidgetType) {// 更新指定应用小部件 Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_UPDATE); if (appWidgetType == Notes.TYPE_WIDGET_2X) { intent.setClass(this, NoteWidgetProvider_2x.class); @@ -707,7 +751,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt setResult(RESULT_OK, intent); } - private final OnCreateContextMenuListener mFolderOnCreateContextMenuListener = new OnCreateContextMenuListener() { + private final OnCreateContextMenuListener mFolderOnCreateContextMenuListener = new OnCreateContextMenuListener() {// 文件夹上下文菜单创建监听 public void onCreateContextMenu(ContextMenu menu, View v, ContextMenuInfo menuInfo) { if (mFocusNoteDataItem != null) { menu.setHeaderTitle(mFocusNoteDataItem.getSnippet()); @@ -719,7 +763,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt }; @Override - public void onContextMenuClosed(Menu menu) { + public void onContextMenuClosed(Menu menu) {// 上下文菜单关闭时移除监听 if (mNotesListView != null) { mNotesListView.setOnCreateContextMenuListener(null); } @@ -733,10 +777,10 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt return false; } switch (item.getItemId()) { - case MENU_FOLDER_VIEW: + case MENU_FOLDER_VIEW:// 查看文件夹 openFolder(mFocusNoteDataItem); break; - case MENU_FOLDER_DELETE: + case MENU_FOLDER_DELETE:// 删除文件夹 AlertDialog.Builder builder = new AlertDialog.Builder(this); builder.setTitle(getString(R.string.alert_title_delete)); builder.setIcon(android.R.drawable.ic_dialog_alert); @@ -750,7 +794,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt builder.setNegativeButton(android.R.string.cancel, null); builder.show(); break; - case MENU_FOLDER_CHANGE_NAME: + case MENU_FOLDER_CHANGE_NAME:// 重命名文件夹 showCreateOrModifyFolderDialog(false); break; default: @@ -761,7 +805,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } @Override - public boolean onPrepareOptionsMenu(Menu menu) { + public boolean onPrepareOptionsMenu(Menu menu) {// 准备选项菜单 menu.clear(); if (mState == ListEditState.NOTE_LIST) { getMenuInflater().inflate(R.menu.note_list, menu); @@ -779,19 +823,19 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } @Override - public boolean onOptionsItemSelected(MenuItem item) { + public boolean onOptionsItemSelected(MenuItem item) {// 选项菜单项点击事件处理 switch (item.getItemId()) { - case R.id.menu_new_folder: { + case R.id.menu_new_folder: {// 新建文件夹 showCreateOrModifyFolderDialog(true); break; } - case R.id.menu_export_text: { + case R.id.menu_export_text: {// 导出笔记为文本文件 exportNoteToText(); break; } - case R.id.menu_sync: { + case R.id.menu_sync: {// 同步笔记 if (isSyncMode()) { - if (TextUtils.equals(item.getTitle(), getString(R.string.menu_sync))) { + if (TextUtils.equals(item.getTitle(), getString(R.string.menu_sync))) {// 同步笔记 GTaskSyncService.startSync(this); } else { GTaskSyncService.cancelSync(this); @@ -801,17 +845,23 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } break; } - case R.id.menu_setting: { + case R.id.menu_setting: {// 打开偏好设置 startPreferenceActivity(); break; } - case R.id.menu_new_note: { + case R.id.menu_new_note: {// 新建笔记 createNewNote(); break; } - case R.id.menu_search: + case R.id.menu_search: {// 搜索笔记 + onSearchRequested(); + break; + } + + case R.id.menu_search:{ onSearchRequested(); break; + } default: break; } @@ -819,24 +869,24 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } @Override - public boolean onSearchRequested() { + public boolean onSearchRequested() {// 搜索笔记 startSearch(null, false, null /* appData */, false); return true; } - private void exportNoteToText() { + private void exportNoteToText() {// 导出笔记为文本文件 final BackupUtils backup = BackupUtils.getInstance(NotesListActivity.this); new AsyncTask() { @Override - protected Integer doInBackground(Void... unused) { + protected Integer doInBackground(Void... unused) {// 后台导出笔记为文本文件 return backup.exportToText(); } @Override - protected void onPostExecute(Integer result) { + protected void onPostExecute(Integer result) {// 导出笔记为文本文件完成后的回调 if (result == BackupUtils.STATE_SD_CARD_UNMOUONTED) { - AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this); + AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this);// 导出笔记为文本文件失败对话框 builder.setTitle(NotesListActivity.this .getString(R.string.failed_sdcard_export)); builder.setMessage(NotesListActivity.this @@ -844,7 +894,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt builder.setPositiveButton(android.R.string.ok, null); builder.show(); } else if (result == BackupUtils.STATE_SUCCESS) { - AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this); + AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this);// 导出笔记为文本文件成功对话框 builder.setTitle(NotesListActivity.this .getString(R.string.success_sdcard_export)); builder.setMessage(NotesListActivity.this.getString( @@ -852,7 +902,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt .getExportedTextFileName(), backup.getExportedTextFileDir())); builder.setPositiveButton(android.R.string.ok, null); builder.show(); - } else if (result == BackupUtils.STATE_SYSTEM_ERROR) { + } else if (result == BackupUtils.STATE_SYSTEM_ERROR) {// 导出笔记为文本文件系统错误对话框 AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this); builder.setTitle(NotesListActivity.this .getString(R.string.failed_sdcard_export)); @@ -866,19 +916,19 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt }.execute(); } - private boolean isSyncMode() { + private boolean isSyncMode() {// 判断是否为同步模式 return NotesPreferenceActivity.getSyncAccountName(this).trim().length() > 0; } - private void startPreferenceActivity() { + private void startPreferenceActivity() {// 打开偏好设置活动 Activity from = getParent() != null ? getParent() : this; Intent intent = new Intent(from, NotesPreferenceActivity.class); from.startActivityIfNeeded(intent, -1); } - private class OnListItemClickListener implements OnItemClickListener { + private class OnListItemClickListener implements OnItemClickListener {// 列表项点击监听器 - public void onItemClick(AdapterView parent, View view, int position, long id) { + public void onItemClick(AdapterView parent, View view, int position, long id) {// 列表项点击事件 if (view instanceof NotesListItem) { NoteItemData item = ((NotesListItem) view).getItemData(); if (mNotesListAdapter.isInChoiceMode()) { @@ -890,9 +940,9 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt return; } - switch (mState) { + switch (mState) {// 根据当前状态处理点击事件 case NOTE_LIST: - if (item.getType() == Notes.TYPE_FOLDER + if (item.getType() == Notes.TYPE_FOLDER// 点击文件夹项 || item.getType() == Notes.TYPE_SYSTEM) { openFolder(item); } else if (item.getType() == Notes.TYPE_NOTE) { @@ -917,7 +967,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } - private void startQueryDestinationFolders() { + private void startQueryDestinationFolders() {// 查询目标文件夹 String selection = NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>? AND " + NoteColumns.ID + "<>?"; selection = (mState == ListEditState.NOTE_LIST) ? selection: "(" + selection + ") OR (" + NoteColumns.ID + "=" + Notes.ID_ROOT_FOLDER + ")"; @@ -935,7 +985,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt NoteColumns.MODIFIED_DATE + " DESC"); } - public boolean onItemLongClick(AdapterView parent, View view, int position, long id) { + public boolean onItemLongClick(AdapterView parent, View view, int position, long id) {// 列表项长按事件 if (view instanceof NotesListItem) { mFocusNoteDataItem = ((NotesListItem) view).getItemData(); if (mFocusNoteDataItem.getType() == Notes.TYPE_NOTE && !mNotesListAdapter.isInChoiceMode()) { diff --git a/src/ui/NotesListAdapter.java b/src/ui/NotesListAdapter.java index 51c9cb9..98106be 100644 --- a/src/ui/NotesListAdapter.java +++ b/src/ui/NotesListAdapter.java @@ -31,81 +31,80 @@ import java.util.HashSet; import java.util.Iterator; -public class NotesListAdapter extends CursorAdapter { - private static final String TAG = "NotesListAdapter"; - private Context mContext; - private HashMap mSelectedIndex; - private int mNotesCount; - private boolean mChoiceMode; - - public static class AppWidgetAttribute { - public int widgetId; - public int widgetType; +public class NotesListAdapter extends CursorAdapter {//Adapter作为Activity和ListView之间的适配器，将Cursor数据转换为ListView可以理解的视图格式 + private static final String TAG = "NotesListAdapter"; // 日志标签 + private Context mContext; // 上下文对象 + private HashMap mSelectedIndex; // 选中项索引映射 + private int mNotesCount; // 笔记数量（排除文件夹） + private boolean mChoiceMode; // 是否处于选择模式 + + public static class AppWidgetAttribute { // 小部件属性类，用于存储小部件的ID和类型 + public int widgetId; // 小部件ID + public int widgetType; // 小部件类型 }; - public NotesListAdapter(Context context) { + public NotesListAdapter(Context context) { // 构造函数，创建NotesListAdapter实例 super(context, null); - mSelectedIndex = new HashMap(); + mSelectedIndex = new HashMap(); // 初始化选中项映射 mContext = context; mNotesCount = 0; } @Override public View newView(Context context, Cursor cursor, ViewGroup parent) { - return new NotesListItem(context); + return new NotesListItem(context); // 创建新的NotesListItem } @Override public void bindView(View view, Context context, Cursor cursor) { if (view instanceof NotesListItem) { - NoteItemData itemData = new NoteItemData(context, cursor); - ((NotesListItem) view).bind(context, itemData, mChoiceMode, + NoteItemData itemData = new NoteItemData(context, cursor); // 创建数据模型 + ((NotesListItem) view).bind(context, itemData, mChoiceMode, // 绑定数据到视图 isSelectedItem(cursor.getPosition())); } } public void setCheckedItem(final int position, final boolean checked) { - mSelectedIndex.put(position, checked); - notifyDataSetChanged(); + mSelectedIndex.put(position, checked); // 更新选中状态 + notifyDataSetChanged(); // 通知数据变化，刷新UI } public boolean isInChoiceMode() { - return mChoiceMode; + return mChoiceMode; // 检查是否处于选择模式 } public void setChoiceMode(boolean mode) { - mSelectedIndex.clear(); - mChoiceMode = mode; + mSelectedIndex.clear(); // 清除之前的选中状态 + mChoiceMode = mode; // 更新模式标志 } public void selectAll(boolean checked) { Cursor cursor = getCursor(); for (int i = 0; i < getCount(); i++) { if (cursor.moveToPosition(i)) { - if (NoteItemData.getNoteType(cursor) == Notes.TYPE_NOTE) { - setCheckedItem(i, checked); + if (NoteItemData.getNoteType(cursor) == Notes.TYPE_NOTE) { // 只处理普通笔记，跳过文件夹 + setCheckedItem(i, checked); // 设置选中状态 } } } } - public HashSet getSelectedItemIds() { + public HashSet getSelectedItemIds() {// 获取选中项的ID集合 HashSet itemSet = new HashSet(); for (Integer position : mSelectedIndex.keySet()) { if (mSelectedIndex.get(position) == true) { - Long id = getItemId(position); + Long id = getItemId(position); // 获取选中项的ID if (id == Notes.ID_ROOT_FOLDER) { Log.d(TAG, "Wrong item id, should not happen"); } else { - itemSet.add(id); + itemSet.add(id); // 添加到集合 } } } - return itemSet; } - public HashSet getSelectedWidget() { + public HashSet getSelectedWidget() {// 获取选中项的小部件属性集合 HashSet itemSet = new HashSet(); for (Integer position : mSelectedIndex.keySet()) { if (mSelectedIndex.get(position) == true) { @@ -113,12 +112,10 @@ public class NotesListAdapter extends CursorAdapter { if (c != null) { AppWidgetAttribute widget = new AppWidgetAttribute(); NoteItemData item = new NoteItemData(mContext, c); - widget.widgetId = item.getWidgetId(); - widget.widgetType = item.getWidgetType(); + widget.widgetId = item.getWidgetId(); // 获取小部件ID + widget.widgetType = item.getWidgetType(); // 获取小部件类型 itemSet.add(widget); - /** - * Don't close cursor here, only the adapter could close it - */ + // Don't close cursor here, only the adapter could close it } else { Log.e(TAG, "Invalid cursor"); return null; @@ -128,7 +125,7 @@ public class NotesListAdapter extends CursorAdapter { return itemSet; } - public int getSelectedCount() { + public int getSelectedCount() {// 获取选中项数量 Collection values = mSelectedIndex.values(); if (null == values) { return 0; @@ -140,39 +137,39 @@ public class NotesListAdapter extends CursorAdapter { count++; } } - return count; + return count; // 返回选中项数量 } - public boolean isAllSelected() { + public boolean isAllSelected() {// 检查是否所有笔记都被选中 int checkedCount = getSelectedCount(); - return (checkedCount != 0 && checkedCount == mNotesCount); + return (checkedCount != 0 && checkedCount == mNotesCount); } - public boolean isSelectedItem(final int position) { + public boolean isSelectedItem(final int position) {// 检查指定位置的项是否被选中 if (null == mSelectedIndex.get(position)) { return false; } - return mSelectedIndex.get(position); + return mSelectedIndex.get(position); // 检查指定位置的项是否被选中 } @Override protected void onContentChanged() { super.onContentChanged(); - calcNotesCount(); + calcNotesCount(); // 当内容变化时，重新计算笔记数量 } @Override public void changeCursor(Cursor cursor) { super.changeCursor(cursor); - calcNotesCount(); + calcNotesCount(); // 当游标变化时，重新计算笔记数量 } - private void calcNotesCount() { + private void calcNotesCount() {// 计算普通笔记的数量 mNotesCount = 0; for (int i = 0; i < getCount(); i++) { Cursor c = (Cursor) getItem(i); if (c != null) { - if (NoteItemData.getNoteType(c) == Notes.TYPE_NOTE) { + if (NoteItemData.getNoteType(c) == Notes.TYPE_NOTE) { // 只统计普通笔记，排除文件夹 mNotesCount++; } } else { diff --git a/src/ui/NotesListItem.java b/src/ui/NotesListItem.java index 1221e80..60c91cd 100644 --- a/src/ui/NotesListItem.java +++ b/src/ui/NotesListItem.java @@ -31,13 +31,16 @@ import net.micode.notes.tool.ResourceParser.NoteItemBgResources; public class NotesListItem extends LinearLayout { - private ImageView mAlert; - private TextView mTitle; - private TextView mTime; - private TextView mCallName; - private NoteItemData mItemData; - private CheckBox mCheckBox; + private ImageView mAlert; // 提醒图标（时钟或通话记录图标） + private TextView mTitle; // 笔记/文件夹标题或内容摘要 + private TextView mTime; // 最后修改时间 + private TextView mCallName; // 通话记录来电者名称（仅通话记录显示） + private NoteItemData mItemData; // 当前列表项的数据模型 + private CheckBox mCheckBox; // 选择模式下的复选框（用于批量操作） + /** + * 构造函数，初始化视图组件 + */ public NotesListItem(Context context) { super(context); inflate(context, R.layout.note_item, this); @@ -48,7 +51,13 @@ public class NotesListItem extends LinearLayout { mCheckBox = (CheckBox) findViewById(android.R.id.checkbox); } + /** + * 绑定数据到视图，根据数据类型动态调整UI样式 + * @param data 笔记数据模型 + * @param checked 选择模式下是否选中 + */ public void bind(Context context, NoteItemData data, boolean choiceMode, boolean checked) { + // 处理选择模式显示 if (choiceMode && data.getType() == Notes.TYPE_NOTE) { mCheckBox.setVisibility(View.VISIBLE); mCheckBox.setChecked(checked); @@ -57,6 +66,7 @@ public class NotesListItem extends LinearLayout { } mItemData = data; + // 处理通话记录文件夹 if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) { mCallName.setVisibility(View.GONE); mAlert.setVisibility(View.VISIBLE); @@ -64,7 +74,9 @@ public class NotesListItem extends LinearLayout { mTitle.setText(context.getString(R.string.call_record_folder_name) + context.getString(R.string.format_folder_files_count, data.getNotesCount())); mAlert.setImageResource(R.drawable.call_record); - } else if (data.getParentId() == Notes.ID_CALL_RECORD_FOLDER) { + } + // 处理通话记录笔记 + else if (data.getParentId() == Notes.ID_CALL_RECORD_FOLDER) { mCallName.setVisibility(View.VISIBLE); mCallName.setText(data.getCallName()); mTitle.setTextAppearance(context,R.style.TextAppearanceSecondaryItem); @@ -75,7 +87,9 @@ public class NotesListItem extends LinearLayout { } else { mAlert.setVisibility(View.GONE); } - } else { + } + // 处理普通文件夹和笔记 + else { mCallName.setVisibility(View.GONE); mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem); @@ -94,14 +108,20 @@ public class NotesListItem extends LinearLayout { } } } + // 设置最后修改时间（相对时间格式） mTime.setText(DateUtils.getRelativeTimeSpanString(data.getModifiedDate())); + // 根据数据类型和位置设置背景 setBackground(data); } + /** + * 根据笔记类型和位置设置不同的背景资源 + */ private void setBackground(NoteItemData data) { int id = data.getBgColorId(); if (data.getType() == Notes.TYPE_NOTE) { + // 根据笔记在列表中的位置设置不同背景 if (data.isSingle() || data.isOneFollowingFolder()) { setBackgroundResource(NoteItemBgResources.getNoteBgSingleRes(id)); } else if (data.isLast()) { @@ -112,10 +132,14 @@ public class NotesListItem extends LinearLayout { setBackgroundResource(NoteItemBgResources.getNoteBgNormalRes(id)); } } else { + // 文件夹使用统一背景 setBackgroundResource(NoteItemBgResources.getFolderBgRes()); } } + /** + * 获取当前列表项的数据模型 + */ public NoteItemData getItemData() { return mItemData; } diff --git a/src/ui/NotesPreferenceActivity.java b/src/ui/NotesPreferenceActivity.java index 07c5f7e..f9569c8 100644 --- a/src/ui/NotesPreferenceActivity.java +++ b/src/ui/NotesPreferenceActivity.java @@ -48,27 +48,37 @@ import net.micode.notes.data.Notes.NoteColumns; import net.micode.notes.gtask.remote.GTaskSyncService; +/** + * 小米笔记应用的偏好设置活动类，负责管理应用的各种设置选项 + * 包括同步账户管理、背景颜色设置和同步状态显示 + */ public class NotesPreferenceActivity extends PreferenceActivity { + /** 偏好设置文件名 */ public static final String PREFERENCE_NAME = "notes_preferences"; - + /** 同步账户名称偏好键 */ public static final String PREFERENCE_SYNC_ACCOUNT_NAME = "pref_key_account_name"; - + /** 最后同步时间偏好键 */ public static final String PREFERENCE_LAST_SYNC_TIME = "pref_last_sync_time"; - + /** 背景颜色随机显示偏好键 */ public static final String PREFERENCE_SET_BG_COLOR_KEY = "pref_key_bg_random_appear"; - + /** 同步账户分类键 */ private static final String PREFERENCE_SYNC_ACCOUNT_KEY = "pref_sync_account_key"; - + /** 账户授权过滤器键 */ private static final String AUTHORITIES_FILTER_KEY = "authorities"; + /** 账户设置分类 */ private PreferenceCategory mAccountCategory; - + /** GTask同步广播接收器 */ private GTaskReceiver mReceiver; - + /** 原始账户列表，用于检测是否添加了新账户 */ private Account[] mOriAccounts; - + /** 是否添加了新账户的标志 */ private boolean mHasAddedAccount; + /** + * 创建偏好设置活动时的初始化操作 + * @param icicle 保存的活动状态 + */ @Override protected void onCreate(Bundle icicle) { super.onCreate(icicle); @@ -88,6 +98,9 @@ public class NotesPreferenceActivity extends PreferenceActivity { getListView().addHeaderView(header, null, true); } + /** + * 活动恢复时调用，处理账户添加检测和UI刷新 + */ @Override protected void onResume() { super.onResume(); @@ -116,6 +129,9 @@ public class NotesPreferenceActivity extends PreferenceActivity { refreshUI(); } + /** + * 活动销毁时调用，用于清理资源 + */ @Override protected void onDestroy() { if (mReceiver != null) { @@ -124,6 +140,9 @@ public class NotesPreferenceActivity extends PreferenceActivity { super.onDestroy(); } + /** + * 加载账户偏好设置，创建账户选择偏好项 + */ private void loadAccountPreference() { mAccountCategory.removeAll(); @@ -154,6 +173,9 @@ public class NotesPreferenceActivity extends PreferenceActivity { mAccountCategory.addPreference(accountPref); } + /** + * 加载同步按钮和同步状态显示 + */ private void loadSyncButton() { Button syncButton = (Button) findViewById(R.id.preference_sync_button); TextView lastSyncTimeView = (TextView) findViewById(R.id.prefenerece_sync_status_textview); @@ -193,11 +215,17 @@ public class NotesPreferenceActivity extends PreferenceActivity { } } + /** + * 刷新UI界面，重新加载账户偏好和同步按钮状态 + */ private void refreshUI() { loadAccountPreference(); loadSyncButton(); } + /** + * 显示选择账户的对话框，允许用户选择或添加Google账户 + */ private void showSelectAccountAlertDialog() { AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(this); @@ -254,6 +282,9 @@ public class NotesPreferenceActivity extends PreferenceActivity { }); } + /** + * 显示更改账户的确认对话框，提示用户更改账户的风险 + */ private void showChangeAccountConfirmAlertDialog() { AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(this); @@ -283,11 +314,19 @@ public class NotesPreferenceActivity extends PreferenceActivity { dialogBuilder.show(); } + /** + * 获取所有Google账户列表 + * @return Google账户数组 + */ private Account[] getGoogleAccounts() { AccountManager accountManager = AccountManager.get(this); return accountManager.getAccountsByType("com.google"); } + /** + * 设置同步账户 + * @param account 账户名称 + */ private void setSyncAccount(String account) { if (!getSyncAccountName(this).equals(account)) { SharedPreferences settings = getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE); @@ -318,6 +357,9 @@ public class NotesPreferenceActivity extends PreferenceActivity { } } + /** + * 移除同步账户，清理相关数据 + */ private void removeSyncAccount() { SharedPreferences settings = getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE); SharedPreferences.Editor editor = settings.edit(); @@ -330,7 +372,7 @@ public class NotesPreferenceActivity extends PreferenceActivity { editor.commit(); // clean up local gtask related info - new Thread(new Runnable() { + new Thread(new Runnable() {//清空一系列数据，thread多线程操作，避免阻塞主线程 public void run() { ContentValues values = new ContentValues(); values.put(NoteColumns.GTASK_ID, ""); @@ -340,13 +382,20 @@ public class NotesPreferenceActivity extends PreferenceActivity { }).start(); } - public static String getSyncAccountName(Context context) { + /** + * 获取当前同步账户名称 + * @return 同步账户名称 + */ + public static String getSyncAccountName(Context context) {// SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE); return settings.getString(PREFERENCE_SYNC_ACCOUNT_NAME, ""); } - public static void setLastSyncTime(Context context, long time) { + /** + * 设置最后同步时间 + */ + public static void setLastSyncTime(Context context, long time) {// SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE); SharedPreferences.Editor editor = settings.edit(); @@ -354,16 +403,20 @@ public class NotesPreferenceActivity extends PreferenceActivity { editor.commit(); } - public static long getLastSyncTime(Context context) { + /** + * 获取最后同步时间 + * @return 最后同步时间（毫秒） + */ + public static long getLastSyncTime(Context context) {// SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE); return settings.getLong(PREFERENCE_LAST_SYNC_TIME, 0); } - private class GTaskReceiver extends BroadcastReceiver { + private class GTaskReceiver extends BroadcastReceiver {// 处理同步状态更新广播 @Override - public void onReceive(Context context, Intent intent) { + public void onReceive(Context context, Intent intent) {// 处理同步状态更新广播 refreshUI(); if (intent.getBooleanExtra(GTaskSyncService.GTASK_SERVICE_BROADCAST_IS_SYNCING, false)) { TextView syncStatus = (TextView) findViewById(R.id.prefenerece_sync_status_textview); @@ -374,7 +427,11 @@ public class NotesPreferenceActivity extends PreferenceActivity { } } - public boolean onOptionsItemSelected(MenuItem item) { + /** + * 处理选项菜单点击事件 + * @param item 点击的菜单项 + */ + public boolean onOptionsItemSelected(MenuItem item) {// switch (item.getItemId()) { case android.R.id.home: Intent intent = new Intent(this, NotesListActivity.class); diff --git a/src/widget/NoteWidgetProvider.java b/src/widget/NoteWidgetProvider.java index ec6f819..5400be7 100644 --- a/src/widget/NoteWidgetProvider.java +++ b/src/widget/NoteWidgetProvider.java @@ -32,11 +32,11 @@ import net.micode.notes.tool.ResourceParser; import net.micode.notes.ui.NoteEditActivity; import net.micode.notes.ui.NotesListActivity; -public abstract class NoteWidgetProvider extends AppWidgetProvider { +public abstract class NoteWidgetProvider extends AppWidgetProvider {//笔记小部件提供器 public static final String [] PROJECTION = new String [] { NoteColumns.ID, NoteColumns.BG_COLOR_ID, - NoteColumns.SNIPPET + NoteColumns.SNIPPET//笔记摘要 }; public static final int COLUMN_ID = 0; @@ -46,9 +46,9 @@ public abstract class NoteWidgetProvider extends AppWidgetProvider { private static final String TAG = "NoteWidgetProvider"; @Override - public void onDeleted(Context context, int[] appWidgetIds) { - ContentValues values = new ContentValues(); - values.put(NoteColumns.WIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID); + public void onDeleted(Context context, int[] appWidgetIds) {//删除小部件时调用 + ContentValues values = new ContentValues();//创建内容值对象，用于更新数据库 + values.put(NoteColumns.WIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID);//将小部件ID设置为无效值 for (int i = 0; i < appWidgetIds.length; i++) { context.getContentResolver().update(Notes.CONTENT_NOTE_URI, values, @@ -59,18 +59,18 @@ public abstract class NoteWidgetProvider extends AppWidgetProvider { private Cursor getNoteWidgetInfo(Context context, int widgetId) { return context.getContentResolver().query(Notes.CONTENT_NOTE_URI, - PROJECTION, + PROJECTION,//查询投影，指定要返回的列 NoteColumns.WIDGET_ID + "=? AND " + NoteColumns.PARENT_ID + "<>?", new String[] { String.valueOf(widgetId), String.valueOf(Notes.ID_TRASH_FOLER) }, null); } protected void update(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { - update(context, appWidgetManager, appWidgetIds, false); + update(context, appWidgetManager, appWidgetIds, false);//false } private void update(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds, - boolean privacyMode) { + boolean privacyMode) {//更新小部件，是上面的实现方式 for (int i = 0; i < appWidgetIds.length; i++) { if (appWidgetIds[i] != AppWidgetManager.INVALID_APPWIDGET_ID) { int bgId = ResourceParser.getDefaultBgId(context); @@ -90,36 +90,38 @@ public abstract class NoteWidgetProvider extends AppWidgetProvider { snippet = c.getString(COLUMN_SNIPPET); bgId = c.getInt(COLUMN_BG_COLOR_ID); intent.putExtra(Intent.EXTRA_UID, c.getLong(COLUMN_ID)); - intent.setAction(Intent.ACTION_VIEW); + intent.setAction(Intent.ACTION_VIEW);//设置意图操作，查看笔记 } else { snippet = context.getResources().getString(R.string.widget_havenot_content); - intent.setAction(Intent.ACTION_INSERT_OR_EDIT); + intent.setAction(Intent.ACTION_INSERT_OR_EDIT);//设置意图操作，插入或编辑笔记 } if (c != null) { c.close(); } - RemoteViews rv = new RemoteViews(context.getPackageName(), getLayoutId()); + RemoteViews rv = new RemoteViews(context.getPackageName(), getLayoutId());//创建远程视图对象，用于更新小部件的布局 + /*为什么在App Widget中使用RemoteViews而非普通View? RemoteViews是一种 跨进程视图描述机制 ，它不直接操作View对象，而是通过序列化方式传递视图的结构和属性 + 是Android系统为了解决跨进程视图更新问题而设计的一种安全、高效的机制。*/ rv.setImageViewResource(R.id.widget_bg_image, getBgResourceId(bgId)); intent.putExtra(Notes.INTENT_EXTRA_BACKGROUND_ID, bgId); /** * Generate the pending intent to start host for the widget */ - PendingIntent pendingIntent = null; + PendingIntent pendingIntent = null;//创建挂起意图对象，用于启动主活动 if (privacyMode) { rv.setTextViewText(R.id.widget_text, - context.getString(R.string.widget_under_visit_mode)); + context.getString(R.string.widget_under_visit_mode));//设置小部件文本为隐私模式下的提示文本 pendingIntent = PendingIntent.getActivity(context, appWidgetIds[i], new Intent( - context, NotesListActivity.class), PendingIntent.FLAG_UPDATE_CURRENT); + context, NotesListActivity.class), PendingIntent.FLAG_UPDATE_CURRENT);//用于动态更新 } else { rv.setTextViewText(R.id.widget_text, snippet); pendingIntent = PendingIntent.getActivity(context, appWidgetIds[i], intent, PendingIntent.FLAG_UPDATE_CURRENT); } - rv.setOnClickPendingIntent(R.id.widget_text, pendingIntent); - appWidgetManager.updateAppWidget(appWidgetIds[i], rv); + rv.setOnClickPendingIntent(R.id.widget_text, pendingIntent);//设置小部件文本点击事件，启动挂起意图 + appWidgetManager.updateAppWidget(appWidgetIds[i], rv);//更新小部件布局 } } } diff --git a/src/widget/NoteWidgetProvider_2x.java b/src/widget/NoteWidgetProvider_2x.java index adcb2f7..188caaf 100644 --- a/src/widget/NoteWidgetProvider_2x.java +++ b/src/widget/NoteWidgetProvider_2x.java @@ -24,10 +24,10 @@ import net.micode.notes.data.Notes; import net.micode.notes.tool.ResourceParser; -public class NoteWidgetProvider_2x extends NoteWidgetProvider { +public class NoteWidgetProvider_2x extends NoteWidgetProvider {//小部件2x布局类 @Override public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { - super.update(context, appWidgetManager, appWidgetIds); + super.update(context, appWidgetManager, appWidgetIds);//调用父类更新方法 } @Override diff --git a/src/widget/NoteWidgetProvider_4x.java b/src/widget/NoteWidgetProvider_4x.java index c12a02e..86c103d 100644 --- a/src/widget/NoteWidgetProvider_4x.java +++ b/src/widget/NoteWidgetProvider_4x.java @@ -24,14 +24,14 @@ import net.micode.notes.data.Notes; import net.micode.notes.tool.ResourceParser; -public class NoteWidgetProvider_4x extends NoteWidgetProvider { +public class NoteWidgetProvider_4x extends NoteWidgetProvider {//小部件4x布局类 @Override public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { - super.update(context, appWidgetManager, appWidgetIds); + super.update(context, appWidgetManager, appWidgetIds);//调用父类更新方法 } protected int getLayoutId() { - return R.layout.widget_4x; + return R.layout.widget_4x;//返回4x布局资源ID } @Override